@ema.co/mcp-toolkit 1.5.0 → 1.5.2

package/dist/mcp/handlers-consolidated.js

@@ -238,12 +238,13 @@ export async function handlePersona(args, client, getTemplateId, createClientFor
             }
             // IMPORTANT: The Ema API requires workflow to be sent along with proto_config
             // for proto_config changes to persist. This matches what the UI does.
+            const workflowToSet = args.workflow ?? existingWorkflow;
             await client.updateAiEmployee({
                 persona_id: persona.id,
                 name: args.name,
                 description: args.description,
                 proto_config: mergedProtoConfig,
-                workflow: existingWorkflow, // Include workflow for proto_config to persist
+                workflow: workflowToSet, // Use provided workflow or existing workflow for proto_config to persist
                 enabled_by_user: typeof args.enabled === "boolean" ? args.enabled : undefined,
             });
             return {
@@ -544,7 +545,7 @@ export async function handlePersona(args, client, getTemplateId, createClientFor
 // ═══════════════════════════════════════════════════════════════════════════
 // WORKFLOW Handler - Unified greenfield/brownfield operations
 // ═══════════════════════════════════════════════════════════════════════════
-export async function handleWorkflow(args, client) {
+export async function handleWorkflow(args, client, getTemplateId) {
     const personaId = args.persona_id;
     const workflowDef = args.workflow_def;
     const input = args.input;
@@ -570,8 +571,12 @@ export async function handleWorkflow(args, client) {
         // Auto-fix issues
         effectiveMode = "optimize";
     }
+    else if (personaId && workflowDef) {
+        // DEPLOY: Persona exists + workflow_def provided → deploy directly (no input needed)
+        effectiveMode = "deploy";
+    }
     else if (personaId && input) {
-        // BROWNFIELD: Modify existing workflow
+        // MODIFY: Persona exists + input provided → generate new workflow from input
         effectiveMode = "modify"; // New unified mode for all brownfield changes
     }
     else if (input && !personaId) {
@@ -589,8 +594,10 @@ export async function handleWorkflow(args, client) {
     const legacyMode = args.mode;
     if (legacyMode === "extend")
         effectiveMode = "modify";
-    if (legacyMode === "deploy" && personaId && input)
-        effectiveMode = "modify";
+    if (legacyMode === "deploy") {
+        // If explicit deploy mode, use it (works with or without input)
+        effectiveMode = "deploy";
+    }
     switch (effectiveMode) {
         case "extraction_schema": {
             // Generate extraction schema from JSON metadata (fully dynamic, no hardcoding)
@@ -783,7 +790,95 @@ export async function handleWorkflow(args, client) {
                 result.deployed_to = { persona_id: personaId, persona_name: persona.name };
             }
             else if (!preview && !personaId) {
-                result.hint = "Provide persona_id to deploy, or use persona(mode='create') first";
+                // GREENFIELD: Create new persona from template, then update proto_config only
+                // The template provides a valid workflow structure - we don't replace it,
+                // we just configure the persona settings (voice config, welcome message, etc.)
+                const personaName = args.name;
+                if (personaName) {
+                    const personaType = args.type || "chat";
+                    const DEFAULT_TEMPLATES = {
+                        voice: "00000000-0000-0000-0000-00000000001e", // Voice AI template
+                        chat: "00000000-0000-0000-0000-000000000004", // Chat AI template
+                        dashboard: "00000000-0000-0000-0000-000000000002", // Dashboard AI template
+                    };
+                    const templateId = getTemplateId?.(personaType) || DEFAULT_TEMPLATES[personaType];
+                    if (!templateId) {
+                        return {
+                            error: `No template found for type "${personaType}". Provide template_id or use type: voice, chat, or dashboard.`
+                        };
+                    }
+                    // Step 1: Create the persona from template
+                    const createResult = await client.createAiEmployee({
+                        name: personaName,
+                        description: args.description,
+                        template_id: templateId,
+                    });
+                    const newPersonaId = createResult.persona_id ?? createResult.id;
+                    if (!newPersonaId) {
+                        return { error: "Failed to create persona: no ID returned" };
+                    }
+                    // Step 2: Fetch the newly created persona to get template's valid structure
+                    const newPersona = await client.getPersonaById(newPersonaId);
+                    if (!newPersona) {
+                        return { error: `Failed to fetch newly created persona: ${newPersonaId}` };
+                    }
+                    // Step 3: Merge proto_config - keep template structure, update widget values
+                    const existingProtoConfig = (newPersona.proto_config ?? {});
+                    const generatedProtoConfig = args.proto_config || compiled.proto_config || {};
+                    // Merge widgets by name - template widgets provide structure, generated values override
+                    const existingWidgets = (existingProtoConfig.widgets ?? []);
+                    const generatedWidgets = (generatedProtoConfig.widgets ?? []);
+                    const widgetMap = new Map();
+                    // Start with template widgets (valid structure)
+                    for (const w of existingWidgets) {
+                        if (typeof w.name === "string" && w.name.trim().length > 0) {
+                            widgetMap.set(w.name, w);
+                        }
+                    }
+                    // Merge generated widget VALUES into template structure
+                    for (const genWidget of generatedWidgets) {
+                        const widgetName = genWidget.name;
+                        if (typeof widgetName === "string" && widgetName.trim().length > 0) {
+                            const existing = widgetMap.get(widgetName);
+                            if (existing) {
+                                // Merge: keep template structure, update config values
+                                const merged = { ...existing };
+                                // The widget config is stored under the widget name (e.g., conversationSettings)
+                                if (genWidget[widgetName]) {
+                                    merged[widgetName] = { ...(existing[widgetName] || {}), ...genWidget[widgetName] };
+                                }
+                                widgetMap.set(widgetName, merged);
+                            }
+                            else {
+                                // New widget not in template - add as-is
+                                widgetMap.set(widgetName, genWidget);
+                            }
+                        }
+                    }
+                    const mergedProtoConfig = {
+                        ...existingProtoConfig,
+                        widgets: Array.from(widgetMap.values()),
+                    };
+                    // Step 4: Update persona with merged proto_config only
+                    // DO NOT send workflow - keep the template's valid workflow structure
+                    await client.updateAiEmployee({
+                        persona_id: newPersonaId,
+                        proto_config: mergedProtoConfig,
+                    });
+                    result.deployed_to = {
+                        persona_id: newPersonaId,
+                        persona_name: personaName,
+                        created: true
+                    };
+                    result.status = "deployed";
+                    result.next_steps = [
+                        `Persona "${personaName}" created with template workflow.`,
+                        `To customize the workflow, use: workflow(persona_id="${newPersonaId}", input="add search node", preview=false)`,
+                    ];
+                }
+                else {
+                    result.hint = "Provide name to create new persona, or persona_id to deploy to existing persona";
+                }
             }
             if (preview) {
                 result.next_steps = [
@@ -959,8 +1054,68 @@ export async function handleWorkflow(args, client) {
             }
             return result;
         }
-        // Note: mode="deploy" is now handled by preview=false on extend/optimize/generate
-        // Legacy calls are converted at the top of the handler
+        case "deploy": {
+            // DEPLOY: Direct workflow deployment to existing persona (no input required)
+            if (!personaId) {
+                return { error: "persona_id required for deploy mode" };
+            }
+            if (!workflowDef) {
+                return { error: "workflow_def required for deploy mode" };
+            }
+            const persona = await client.getPersonaById(personaId);
+            if (!persona) {
+                return { error: `Persona not found: ${personaId}` };
+            }
+            // Sanitize workflow before deployment
+            const sanitizedWorkflow = sanitizeWorkflowForDeploy(workflowDef);
+            // Determine proto_config to use: provided > existing
+            const existingProtoConfig = persona.proto_config;
+            const providedProtoConfig = args.proto_config;
+            const protoConfigToUse = providedProtoConfig || existingProtoConfig || {};
+            // Check if this is a voice persona and warn if critical settings are missing
+            const projectSettings = protoConfigToUse.projectSettings;
+            const isVoice = projectSettings?.projectType === 5;
+            const warnings = [];
+            if (isVoice && !providedProtoConfig) {
+                // Check if existing proto_config has conversationSettings populated
+                const widgets = (protoConfigToUse.widgets ?? []);
+                const convSettings = widgets.find(w => w.name === "conversationSettings");
+                const convConfig = convSettings?.conversationSettings;
+                if (!convConfig?.welcomeMessage || !convConfig?.identityAndPurpose) {
+                    warnings.push("Voice persona detected but proto_config not provided. Voice settings (welcomeMessage, identityAndPurpose, etc.) may be empty or generic. " +
+                        "If you generated the workflow with workflow(input=...), pass the generated proto_config along with workflow_def to preserve voice settings.");
+                }
+            }
+            // Deploy workflow (always deploy, preview is not applicable for explicit deploy mode)
+            try {
+                await client.updateAiEmployee({
+                    persona_id: personaId,
+                    workflow: sanitizedWorkflow,
+                    proto_config: protoConfigToUse,
+                });
+                const result = {
+                    mode: "deploy",
+                    status: "deployed",
+                    persona_id: personaId,
+                    persona_name: persona.name,
+                    workflow_deployed: true,
+                };
+                if (warnings.length > 0) {
+                    result.warnings = warnings;
+                }
+                return result;
+            }
+            catch (err) {
+                const errorMessage = err instanceof Error ? err.message : String(err);
+                return {
+                    mode: "deploy",
+                    status: "failed",
+                    persona_id: personaId,
+                    persona_name: persona.name,
+                    error: errorMessage,
+                };
+            }
+        }
         case "compare": {
             if (!personaId || !args.compare_to) {
                 return { error: "persona_id and compare_to required for compare mode" };

package/dist/mcp/prompts.js

@@ -1147,12 +1147,12 @@ Now begin by reading the resources, then proceed with generation.`,
         ],
     },
     // ─────────────────────────────────────────────────────────────────────────
-    // Direct Workflow Generation (Bypasses Auto Builder)
+    // Direct Workflow Generation
     // ─────────────────────────────────────────────────────────────────────────
     workflow_generate: {
         definition: {
             name: "workflow_generate",
-            description: "Generate a complete workflow_def and proto_config directly, bypassing Auto Builder. Produces ready-to-deploy JSON configurations.",
+            description: "Generate an AI Employee workflow. Preview first, then deploy when ready.",
             arguments: [
                 {
                     name: "name",
@@ -1161,29 +1161,14 @@ Now begin by reading the resources, then proceed with generation.`,
                 },
                 {
                     name: "description",
-                    description: "What the AI Employee does",
+                    description: "What the AI Employee does (be detailed about capabilities, intents, data sources)",
                     required: true,
                 },
                 {
-                    name: "persona_type",
+                    name: "type",
                     description: "Type: 'voice', 'chat', or 'dashboard'",
                     required: true,
                 },
-                {
-                    name: "pattern",
-                    description: "Workflow pattern: 'kb_search' (FAQ/docs), 'intent_routing' (multi-intent), 'tool_calling' (external actions)",
-                    required: true,
-                },
-                {
-                    name: "intents",
-                    description: "For intent_routing: comma-separated intent names with handler type, e.g., 'Search:search,Help:llm,Transfer:fixed'",
-                    required: false,
-                },
-                {
-                    name: "tools",
-                    description: "For tool_calling: comma-separated tool names with namespace, e.g., 'Create_Ticket:service_now,Send_Email:outlook'",
-                    required: false,
-                },
             ],
         },
         render: (args) => [
@@ -1191,59 +1176,45 @@ Now begin by reading the resources, then proceed with generation.`,
                 role: "user",
                 content: {
                     type: "text",
-                    text: `Generate a complete workflow configuration for: ${args.name}
+                    text: `Generate AI Employee: ${args.name}
 
+**Type**: ${args.type}
 **Description**: ${args.description}
-**Persona Type**: ${args.persona_type}
-**Pattern**: ${args.pattern}
-${args.intents ? `**Intents**: ${args.intents}` : ""}
-${args.tools ? `**Tools**: ${args.tools}` : ""}
-
-## Instructions
-
-Generate deployment-ready JSON using the consolidated \`workflow\` tool (local compiler):
 
-### Step 1: Generate workflow_def + proto_config (Direct / Deterministic)
-Call:
-\`workflow(input=<requirements>, type="${args.persona_type}", use_autobuilder=false)\`
+## Step 1: Preview the workflow
 
-Where \`<requirements>\` includes:
-- Name: ${args.name}
-- Description: ${args.description}
-- Pattern hint: ${args.pattern}
-${args.intents ? `- Intents: ${args.intents}` : ""}
-${args.tools ? `- Tools: ${args.tools}` : ""}
-
-**HITL Policy**: DEFAULT is no approval gates. Only add HITL if user explicitly requests approval/confirmation before external actions.
-
-If the tool returns \`status="needs_input"\`, ask the missing questions, then call \`workflow(...)\` again with the additional details.
-
-### Step 2: (Optional) Validate the generated workflow
-Call \`workflow(mode="analyze", workflow_def=<workflow_def>)\` and fix any critical issues before deploying.
+\`\`\`
+workflow(
+  input="${args.description}",
+  type="${args.type}"
+)
+\`\`\`
 
-### Step 3: Deploy (Optional)
-If you already have a persona, deploy directly:
-\`workflow(mode="deploy", persona_id="<persona_id>", workflow_def=<workflow_def>, proto_config=<proto_config>)\`
+This returns workflow_def and proto_config. Review them before deploying.
 
-If you need to create one first:
-\`persona(mode="create", name="${args.name}", type="${args.persona_type}")\`
-then deploy as above.
+## Step 2: Deploy when ready
 
-## Output Format
+\`\`\`
+workflow(
+  input="${args.description}",
+  name="${args.name}",
+  type="${args.type}",
+  preview=false
+)
+\`\`\`
 
-Provide the final configurations in this format:
+This creates the persona and deploys the workflow in one step.
 
-\`\`\`json
-// workflow_def.json
-{workflow_def}
-\`\`\`
+${args.type === "voice" ? `
+## Voice AI Notes
 
-\`\`\`json
-// proto_config.json
-{proto_config}
-\`\`\`
+The generated proto_config includes voice settings:
+- welcomeMessage: Generated greeting
+- identityAndPurpose: Generated from description
+- takeActionInstructions, hangupInstructions: Sensible defaults
 
-Now generate by calling \`workflow(input=<requirements>, type="${args.persona_type}", use_autobuilder=false)\`.`,
+These are set automatically but can be customized via proto_config override.
+` : ""}`,
                 },
             },
         ],
@@ -1251,7 +1222,7 @@ Now generate by calling \`workflow(input=<requirements>, type="${args.persona_ty
     workflow_deploy: {
         definition: {
             name: "workflow_deploy",
-            description: "Deploy a generated workflow to an Ema environment. Takes workflow_def and proto_config and creates/updates an AI Employee.",
+            description: "Create a new AI Employee from template with configured settings, or modify an existing one.",
             arguments: [
                 {
                     name: "name",
@@ -1259,13 +1230,18 @@ Now generate by calling \`workflow(input=<requirements>, type="${args.persona_ty
                     required: true,
                 },
                 {
-                    name: "env",
-                    description: "Target environment (default: demo)",
-                    required: false,
+                    name: "type",
+                    description: "Type: voice, chat, or dashboard",
+                    required: true,
+                },
+                {
+                    name: "description",
+                    description: "What this AI Employee does",
+                    required: true,
                 },
                 {
-                    name: "update_existing",
-                    description: "If 'true', update existing AI Employee with same name instead of creating new",
+                    name: "env",
+                    description: "Target environment (default: demo)",
                     required: false,
                 },
             ],
@@ -1275,70 +1251,51 @@ Now generate by calling \`workflow(input=<requirements>, type="${args.persona_ty
                 role: "user",
                 content: {
                     type: "text",
-                    text: `Deploy workflow configuration for: ${args.name}
-
-**Target Environment**: ${args.env || "demo"}
-**Update Existing**: ${args.update_existing === "true" ? "Yes" : "No (create new)"}
-
-## Instructions
-
-### Pre-Deploy Checklist
-
-Before deploying, ensure you have:
-1. ✅ Generated workflow_def using workflow_generate prompt
-2. ✅ Generated proto_config/persona settings
-3. ✅ Validated the workflow (no critical issues)
-
-### Step 1: Check for Existing
+                    text: `Create AI Employee: ${args.name}
 
-${args.update_existing === "true" ? `
-Call \`persona(id="${args.name}", env="${args.env || "demo"}")\`
-to find the existing AI Employee (and capture its persona ID).
-` : `
-Call \`persona(query="${args.name}", env="${args.env || "demo"}")\`
-to check whether an AI Employee with this name already exists (and capture the persona ID if present).
-`}
-
-### Step 2: Create or Update
-
-${args.update_existing === "true" ? `
-If not found, create it:
-\`persona(mode="create", name="${args.name}", type="chat", env="${args.env || "demo"}")\`
-` : `
-Create a new AI Employee:
-\`persona(mode="create", name="${args.name}", type="chat", env="${args.env || "demo"}")\`
-`}
-
-### Step 3: Configure Workflow
-
-Deploy the workflow via MCP:
-\`workflow(mode="deploy", persona_id="<persona_id>", workflow_def=<workflow_def>, proto_config=<proto_config>, env="${args.env || "demo"}")\`
+**Type**: ${args.type || "chat"}
+**Environment**: ${args.env || "demo"}
+**Description**: ${args.description}
 
-### Step 4: Test
+## How It Works
 
-After deployment:
-1. Open the AI Employee in simulator
-2. Test each intent/path
-3. Verify responses are correct
-4. Check HITL flows work (if applicable)
+**Greenfield** (new personas): Creates from template, configures settings.
+- Template provides valid workflow structure
+- We configure proto_config (voice settings, welcome message, etc.)
+- Customize workflow AFTER creation via modify mode
 
-### Step 5: Activate
+**Brownfield** (existing personas): Uses LLM-native transformation.
+- Fetches existing workflow
+- Decompiles to WorkflowSpec
+- Transforms based on your input
+- Compiles back and deploys
 
-Once tested:
-1. Call \`persona(id="<persona_id>", mode="update", enabled=true, env="${args.env || "demo"}")\`
-2. Monitor initial conversations
-3. Iterate based on feedback
+## Create New Persona
 
-## Deployment Summary
+\`\`\`
+workflow(
+  input="${args.description}",
+  name="${args.name}",
+  type="${args.type || "chat"}",
+  preview=false,
+  env="${args.env || "demo"}"
+)
+\`\`\`
 
-Provide a deployment summary including:
-- AI Employee ID (if created/updated)
-- Environment
-- Workflow configuration details
-- Test results
-- Next steps
+This creates the persona from template and configures settings.
+${args.type === "voice" ? `
+For Voice AI, this sets:
+- welcomeMessage (generated greeting)
+- identityAndPurpose (from your description)
+- hangupInstructions, speechCharacteristics (defaults)
+` : ""}
+## After Creation
 
-Now proceed with deployment.`,
+1. Get persona_id from response
+2. Verify: \`persona(id="<persona_id>", include_workflow=true)\`
+3. Customize workflow: \`workflow(persona_id="<id>", input="add search node")\`
+4. Test in Ema simulator
+5. Enable: \`persona(id="<id>", mode="update", enabled=true)\``,
                 },
             },
         ],

package/dist/mcp/server.js

@@ -4843,7 +4843,12 @@ const toolHandlers = {
     // Consolidated workflow handler (replaces legacy inline handler)
     workflow: async (args) => {
         const client = createClient(args.env);
-        return handleWorkflow(args, client);
+        const DEFAULT_TEMPLATES = {
+            voice: "00000000-0000-0000-0000-00000000001e", // Voice AI template
+            chat: "00000000-0000-0000-0000-000000000004", // Chat AI template
+            dashboard: "00000000-0000-0000-0000-000000000002", // Dashboard AI template
+        };
+        return handleWorkflow(args, client, (type) => DEFAULT_TEMPLATES[type]);
     },
     action: async (args) => {
         const client = createClient(args.env);
@@ -4901,14 +4906,16 @@ toolHandlers.workflow = async (args) => {
     const rawMode = normalizedArgs.mode ? String(normalizedArgs.mode) : undefined;
     const mode = rawMode === "improve" ? "optimize" : rawMode;
     // Default mode selection:
-    // - persona_id + input → optimize (BROWNFIELD: enhance existing workflow)
+    // - persona_id + workflow_def → deploy (direct deployment, no input needed)
+    // - persona_id + input → modify (BROWNFIELD: generate new workflow from input)
     // - persona_id only or workflow_def → analyze (inspect)
     // - input only → generate (GREENFIELD: create from scratch)
     // - Otherwise → generate (and prompt for missing info)
     const effectiveMode = mode ??
-        (personaId && inputProvided ? "optimize" : // BROWNFIELD: existing persona + new requirements
-            workflowDef || personaId ? "analyze" : // Inspect existing
-                "generate"); // GREENFIELD: new workflow
+        (personaId && workflowDef ? "deploy" : // Direct deployment (no input required)
+            personaId && inputProvided ? "modify" : // BROWNFIELD: existing persona + new requirements
+                workflowDef || personaId ? "analyze" : // Inspect existing
+                    "generate"); // GREENFIELD: new workflow
     switch (effectiveMode) {
         case "generate": {
             const result = await legacyWorkflowTool({ ...normalizedArgs, mode: "generate" });
@@ -5137,11 +5144,131 @@ toolHandlers.sync = async (args) => {
         include_status: normalizedArgs.include_status,
     });
 };
-// Consolidated demo tool: consolidate | generate | validate | template
+// Consolidated demo tool: kit | validate_kit | scenarios | consolidate | generate | validate | template
 toolHandlers.demo = async (args) => {
     const normalizedArgs = { ...(args ?? {}) };
     const mode = normalizedArgs.mode ? String(normalizedArgs.mode) : "template";
     switch (mode) {
+        case "kit": {
+            // Generate complete demo kit for a persona
+            const personaId = String(normalizedArgs.persona_id ?? "");
+            const scenarioId = String(normalizedArgs.scenario ?? "sales-sdr");
+            if (!personaId) {
+                throw new Error('demo(mode="kit") requires: persona_id');
+            }
+            // Import demo generator
+            const { generateDemoKit, DEMO_SCENARIOS, generateDemoScriptMarkdown, validateDemoKit } = await import("../sdk/demo-generator.js");
+            // Get scenario
+            const scenario = DEMO_SCENARIOS[scenarioId];
+            if (!scenario) {
+                throw new Error(`Unknown scenario: ${scenarioId}. Available: ${Object.keys(DEMO_SCENARIOS).join(", ")}`);
+            }
+            // Get persona and workflow
+            const client = await createClient(normalizedArgs.env);
+            const persona = await client.getPersonaById(personaId);
+            if (!persona) {
+                throw new Error(`Persona not found: ${personaId}`);
+            }
+            const workflowDef = persona.workflow_def || {};
+            const customQA = normalizedArgs.custom_qa;
+            // Generate kit
+            const kit = generateDemoKit(personaId, persona.name || personaId, workflowDef, scenario, customQA);
+            // Generate markdown script
+            const demoScript = generateDemoScriptMarkdown(kit);
+            // Validate
+            const validation = validateDemoKit(kit);
+            return {
+                success: true,
+                persona_id: personaId,
+                persona_name: persona.name,
+                scenario: scenarioId,
+                kit_summary: {
+                    kb_documents: kit.kb_documents.length,
+                    demo_questions: kit.demo_script.length,
+                    fixed_responses: kit.fixed_responses.length,
+                    validation_queries: kit.validation_queries.length,
+                },
+                validation,
+                demo_script_preview: demoScript.slice(0, 2000) + (demoScript.length > 2000 ? "\n\n... (truncated)" : ""),
+                kit,
+                instructions: [
+                    "1. Upload KB documents to the persona's knowledge base",
+                    "2. Review the demo script and practice the questions",
+                    "3. Optionally apply fixed_responses for guaranteed fallbacks",
+                    "4. Run validation queries to verify demo readiness",
+                    "5. Conduct the demo with confidence!",
+                ],
+            };
+        }
+        case "validate_kit": {
+            // Validate a persona's demo readiness
+            const personaId = String(normalizedArgs.persona_id ?? "");
+            if (!personaId) {
+                throw new Error('demo(mode="validate_kit") requires: persona_id');
+            }
+            const { analyzeWorkflowForDemo, DEMO_SCENARIOS } = await import("../sdk/demo-generator.js");
+            const client = await createClient(normalizedArgs.env);
+            const persona = await client.getPersonaById(personaId);
+            if (!persona) {
+                throw new Error(`Persona not found: ${personaId}`);
+            }
+            const analysis = analyzeWorkflowForDemo(persona.workflow_def || {});
+            // Check data sources
+            const dataSourcesResult = await client.listDataSourceFiles(personaId);
+            const dataSources = dataSourcesResult.files || [];
+            const hasKnowledgeBase = dataSources.length > 0;
+            const issues = [];
+            if (!hasKnowledgeBase) {
+                issues.push("No knowledge base documents uploaded - RAG search will fail");
+            }
+            if (analysis.intents.length === 0) {
+                issues.push("No categorizer intents detected - workflow may not route correctly");
+            }
+            if (!analysis.has_search) {
+                issues.push("No search nodes detected - cannot retrieve KB data");
+            }
+            // Suggest best scenario
+            let suggestedScenario = "sales-sdr";
+            for (const [id, scenario] of Object.entries(DEMO_SCENARIOS)) {
+                const intentOverlap = scenario.intents.filter(i => analysis.intents.some(ai => ai.toLowerCase().includes(i.name.toLowerCase()))).length;
+                if (intentOverlap > 0) {
+                    suggestedScenario = id;
+                    break;
+                }
+            }
+            return {
+                persona_id: personaId,
+                persona_name: persona.name,
+                ready: issues.length === 0,
+                issues,
+                workflow_analysis: analysis,
+                knowledge_base: {
+                    has_documents: hasKnowledgeBase,
+                    document_count: dataSources.length,
+                },
+                suggested_scenario: suggestedScenario,
+                next_steps: issues.length > 0
+                    ? issues.map((issue, i) => `${i + 1}. Fix: ${issue}`)
+                    : [`Generate demo kit: demo(mode="kit", persona_id="${personaId}", scenario="${suggestedScenario}")`],
+            };
+        }
+        case "scenarios": {
+            // List available demo scenarios
+            const { DEMO_SCENARIOS } = await import("../sdk/demo-generator.js");
+            return {
+                scenarios: Object.entries(DEMO_SCENARIOS).map(([id, scenario]) => ({
+                    id,
+                    name: scenario.name,
+                    description: scenario.description,
+                    persona_types: scenario.persona_types,
+                    tags: scenario.tags,
+                    intent_count: scenario.intents.length,
+                    qa_count: scenario.qa_pairs.length,
+                    entity_types: scenario.entities.map(e => e.type),
+                })),
+                usage: 'demo(mode="kit", persona_id="...", scenario="<scenario_id>")',
+            };
+        }
         case "consolidate": {
             const source = String(normalizedArgs.source ?? "");
             const output = String(normalizedArgs.output ?? "");