@ema.co/mcp-toolkit 0.2.0

package/docs/data-architecture.md

@@ -0,0 +1,166 @@
+# Data Architecture & Sourcing Strategy
+
+> **Principle**: MCP serves all data. Cursor rules are policy/flow only.
+
+---
+
+## Data Sourcing Hierarchy
+
+For any data that MCP exposes, follow this resolution order:
+
+```
+1. Ema API (live, authoritative)      ← PREFERRED
+2. resources/** (repo files)          ← FILE FALLBACK  
+3. src/sdk/*.ts (embedded constants)  ← CODE FALLBACK
+4. NEVER: .cursor/rules/**            ← POLICY ONLY, NO DATA
+```
+
+---
+
+## Current State Audit
+
+### ✅ DYNAMIC (API-First)
+
+| Resource | Source | Fallback | Notes |
+|----------|--------|----------|-------|
+| `ema://catalog/agents` | `listActions()` API | `AGENT_CATALOG` | Cached 60s, env-aware |
+| `ema://catalog/agents-summary` | `listActions()` API | `AGENT_CATALOG` | Markdown format |
+| `ema://catalog/templates` | `getPersonaTemplates()` API | Empty (use file-backed) | Cached 60s, env-aware |
+| `ema://catalog/templates-summary` | `getPersonaTemplates()` API | Empty | Markdown format |
+| `action(...)` tool | `listActions()` API | Embedded docs | Full API integration |
+
+### ⚠️ HARDCODED (Embedded in Code)
+
+| Resource | Source | Can Be Dynamic? | Priority |
+|----------|--------|-----------------|----------|
+| `ema://catalog/patterns` | `WORKFLOW_PATTERNS` | Yes - could query "template personas" | Medium |
+| `ema://catalog/widgets` | `WIDGET_CATALOG` | Yes - could query API | Low |
+| `ema://rules/input-sources` | `INPUT_SOURCE_RULES` | Unlikely - validation logic | Low |
+| `ema://rules/anti-patterns` | `ANTI_PATTERNS` | Unlikely - validation logic | Low |
+| `ema://rules/optimizations` | `OPTIMIZATION_RULES` | Unlikely - validation logic | Low |
+
+### 📁 FILE-BACKED (Repo Files - Fallback)
+
+| Resource | Path | Notes |
+|----------|------|-------|
+| `ema://templates/voice-ai/*` | `resources/templates/voice-ai/` | Fallback when API unavailable |
+| `ema://templates/chat-ai/*` | `resources/templates/chat-ai/` | Fallback when API unavailable |
+| `ema://templates/dashboard-ai/*` | `resources/templates/dashboard-ai/` | Fallback when API unavailable |
+| `ema://docs/*` | `docs/*.md` | Repo documentation |
+
+**Note**: For templates, prefer `ema://catalog/templates` (API-first) over file-backed `ema://templates/*`.
+
+---
+
+## Making More Things Dynamic
+
+### ✅ DONE: Templates
+
+Templates are now API-first via `getPersonaTemplates()`:
+
+```typescript
+// EmaClient method
+async getPersonaTemplates(): Promise<PersonaTemplateDTO[]>
+
+// MCP Resources (API-first with cache)
+ema://catalog/templates          // Full template data
+ema://catalog/templates-summary  // Markdown summary
+```
+
+### Medium Priority: Workflow Patterns
+
+Patterns could be derived from analyzing existing personas:
+
+```typescript
+// Future: Pattern extraction from existing personas
+async function getPatterns() {
+  // 1. Query personas tagged as "template" or "pattern"
+  const templatePersonas = await client.getPersonasWithTag("template");
+  if (templatePersonas.length > 0) {
+    return extractPatternsFromPersonas(templatePersonas);
+  }
+  
+  // 2. Fallback to embedded patterns
+  return WORKFLOW_PATTERNS;
+}
+```
+
+### Low Priority: Validation Rules
+
+These are internal logic, not external data. Keep embedded unless Ema provides a validation API.
+
+---
+
+## Where Data Lives
+
+```
+ema-mcp-toolkit/
+├── src/
+│   ├── mcp/
+│   │   ├── resources.ts        # Resource registry + dynamic fetching
+│   │   ├── server.ts           # Tool handlers (API calls)
+│   │   └── prompts.ts          # Prompt definitions (structured guidance)
+│   └── sdk/
+│       ├── client.ts           # EmaClient (API wrapper)
+│       ├── knowledge.ts        # AGENT_CATALOG, WORKFLOW_PATTERNS, WIDGET_CATALOG
+│       └── validation-rules.ts # INPUT_SOURCE_RULES, ANTI_PATTERNS, OPTIMIZATION_RULES
+├── resources/
+│   └── templates/              # File-backed templates (canonical location)
+│       ├── voice-ai/
+│       ├── chat-ai/
+│       └── dashboard-ai/
+└── .cursor/
+    └── rules/                  # POLICY/FLOW ONLY - NO DATA
+        ├── base/naming/        # Naming conventions
+        ├── ema/                # MCP usage guidance
+        └── platforms/ema/      # Platform-specific flows
+```
+
+---
+
+## Cursor Rules Policy
+
+### ✅ ALLOWED in Cursor Rules
+
+- **Process flows**: "How to create an AI Employee"
+- **Decision trees**: "When to use HITL"
+- **Tool usage guidance**: "Use `workflow(mode='analyze')` for..."
+- **References to MCP**: "Fetch from `ema://catalog/agents`"
+- **Best practices**: "Always extract email recipients via entity_extraction"
+
+### ❌ NOT ALLOWED in Cursor Rules
+
+- **Agent definitions**: Use `ema://catalog/agents`
+- **Template content**: Use `ema://templates/*`
+- **Validation rules data**: Use `ema://rules/*`
+- **Hardcoded patterns**: Use `ema://catalog/patterns`
+- **Any data that can change**: Must come from MCP
+
+---
+
+## Implementation Checklist
+
+### Already Done ✅
+
+- [x] Agent catalog is API-first (`getDynamicAgentCatalog()`)
+- [x] Templates moved from `.cursor/` to `resources/`
+- [x] `action(...)` tool uses API with docs fallback
+- [x] Resources support `?env=` parameter
+- [x] **Persona templates are API-first** (`getDynamicPersonaTemplates()`)
+- [x] Added `EmaClient.getPersonaTemplates()` method
+- [x] Added `ema://catalog/templates` and `ema://catalog/templates-summary` resources
+
+### To Do (Future)
+
+- [ ] Extract workflow patterns from template `workflow_definition` fields
+- [ ] Consider caching strategy improvements (longer TTL for stable data)
+- [ ] Add health check for API availability
+
+---
+
+## Related Documentation
+
+- `docs/mcp-tools-guide.md` - Tool usage
+- `docs/naming-conventions.md` - Naming standards
+- `.cursor/rules/base/naming/RULE.md` - Naming enforcement
+- `.cursor/rules/ema/RULE.md` - MCP source-of-truth policy

package/docs/ema-auto-builder-guide.html

@@ -0,0 +1,394 @@
+<!DOCTYPE html>
+<html lang="en">
+<head>
+  <meta charset="UTF-8">
+  <title>Ema Auto Builder Quick Reference</title>
+  <style>
+    body {
+      font-family: 'Google Sans', Arial, sans-serif;
+      max-width: 900px;
+      margin: 0 auto;
+      padding: 40px 20px;
+      line-height: 1.6;
+      color: #202124;
+    }
+    h1 { color: #1a73e8; border-bottom: 3px solid #1a73e8; padding-bottom: 10px; }
+    h2 { color: #185abc; margin-top: 40px; border-bottom: 1px solid #dadce0; padding-bottom: 8px; }
+    h3 { color: #1967d2; margin-top: 25px; }
+    h4 { color: #5f6368; }
+    table { border-collapse: collapse; width: 100%; margin: 15px 0; }
+    th, td { border: 1px solid #dadce0; padding: 10px 12px; text-align: left; }
+    th { background: #f8f9fa; font-weight: 600; color: #202124; }
+    tr:nth-child(even) { background: #fafafa; }
+    code { background: #f1f3f4; padding: 2px 6px; border-radius: 4px; font-family: 'Roboto Mono', monospace; font-size: 0.9em; color: #d93025; }
+    pre { background: #f8f9fa; padding: 16px; border-radius: 8px; overflow-x: auto; border: 1px solid #dadce0; }
+    pre code { background: none; color: #202124; }
+    blockquote { border-left: 4px solid #1a73e8; margin: 20px 0; padding: 10px 20px; background: #e8f0fe; color: #174ea6; }
+    .callout { background: #fef7e0; border-left: 4px solid #f9ab00; padding: 12px 16px; margin: 15px 0; }
+    .callout-info { background: #e8f0fe; border-left-color: #1a73e8; }
+    .callout-success { background: #e6f4ea; border-left-color: #34a853; }
+    .callout-warning { background: #fef7e0; border-left-color: #f9ab00; }
+    .callout-error { background: #fce8e6; border-left-color: #ea4335; }
+    ul, ol { margin: 10px 0; padding-left: 25px; }
+    li { margin: 5px 0; }
+    .emoji { font-size: 1.2em; }
+    .tag { display: inline-block; background: #e8f0fe; color: #1967d2; padding: 2px 8px; border-radius: 4px; font-size: 0.85em; margin: 2px; }
+    .tag-required { background: #fce8e6; color: #c5221f; }
+    hr { border: none; border-top: 1px solid #dadce0; margin: 30px 0; }
+  </style>
+</head>
+<body>
+
+<h1>🚀 Ema Auto Builder Quick Reference</h1>
+<p><strong>Ema AI Employee Builder (GWE)</strong>: Quick reference for natural language prompts — triggers, inputs, logic, outputs</p>
+
+<hr>
+
+<h2>🔧 MCP Tools: Use Ema MCP for Live Data</h2>
+
+<p><strong>Ema MCP Server provides real-time platform intelligence.</strong> Always leverage MCP tools.</p>
+
+<div class="callout callout-info">
+  <strong>Tool names in Cursor:</strong> MCP server defines base tool names like <code>persona</code>, <code>workflow</code>, <code>action</code>. In <strong>Cursor</strong>, tools are prefixed with <code>mcp_ema_</code> (e.g., <code>mcp_ema_persona</code>).
+</div>
+
+<table>
+  <tr><th>MCP Tool</th><th>When to Use</th></tr>
+  <tr><td><code>mcp_ema_template(questions=true)</code></td><td><strong>FIRST</strong> — Get structured questions before asking user</td></tr>
+  <tr><td><code>mcp_ema_action(suggest="...")</code></td><td>Match use case to recommended agents/patterns</td></tr>
+  <tr><td><code>mcp_ema_template(pattern="...")</code></td><td>Get template with nodes, connections, anti-patterns</td></tr>
+  <tr><td><code>mcp_ema_action(id="...", include_docs=true)</code></td><td>Get agent inputs/outputs + docs + critical rules</td></tr>
+  <tr><td><code>mcp_ema_reference(validate_prompt="...")</code></td><td><strong>LAST</strong> — Validate before outputting</td></tr>
+  <tr><td><code>mcp_ema_reference(mistakes=true)</code></td><td>Check against top errors before finalizing</td></tr>
+</table>
+
+<h3>MCP-First Generation Flow</h3>
+<pre><code>1. mcp_ema_template(questions=true) → Structure user questions
+2. mcp_ema_action(suggest="...") → Get recommended pattern
+3. mcp_ema_template(pattern="...") → Get template
+4. mcp_ema_action(id="...", include_docs=true) → Get each agent's details
+5. mcp_ema_reference(validate_prompt="...") → Validate before output</code></pre>
+
+<h3>Key MCP Tools by Category</h3>
+<table>
+  <tr><th>Category</th><th>Tools</th></tr>
+  <tr><td><strong>Discovery</strong></td><td><code>persona</code>, <code>env</code></td></tr>
+  <tr><td><strong>Agents</strong></td><td><code>action</code></td></tr>
+  <tr><td><strong>Patterns</strong></td><td><code>template</code></td></tr>
+  <tr><td><strong>Validation</strong></td><td><code>reference(validate_prompt=...)</code>, <code>reference(check_types={...})</code></td></tr>
+  <tr><td><strong>Guidance</strong></td><td><code>reference</code></td></tr>
+  <tr><td><strong>Sync</strong></td><td><code>sync</code>, <code>persona(mode="compare")</code></td></tr>
+  <tr><td><strong>Review</strong></td><td><code>workflow(mode="analyze")</code>, <code>workflow(mode="optimize")</code></td></tr>
+</table>
+
+<hr>
+
+<h2>⚠️ FIRST: Ask Qualifying Questions</h2>
+
+<div class="callout callout-warning">
+  <strong>Do NOT generate a workflow prompt until you have gathered sufficient information.</strong>
+</div>
+
+<div class="callout callout-info">
+  💡 <strong>MCP Tip:</strong> Call <code>mcp_ema_template(questions=true)</code> to get structured questions organized by category with "why it matters" context.
+</div>
+
+<table>
+  <tr><th>Category</th><th>Required Information</th></tr>
+  <tr><td><strong>AI Type</strong></td><td>Voice AI, Chat AI, or Dashboard AI?</td></tr>
+  <tr><td><strong>Intents</strong></td><td>What categories should the AI recognize? (+ Fallback)</td></tr>
+  <tr><td><strong>Data Sources</strong></td><td>What files, APIs, or databases are needed?</td></tr>
+  <tr><td><strong>Actions</strong></td><td>What can the AI do? (search, create ticket, send email)</td></tr>
+  <tr><td><strong>Routing</strong></td><td>What happens for each intent category?</td></tr>
+  <tr><td><strong>Approvals</strong></td><td>Which actions need human review?</td></tr>
+  <tr><td><strong>Success Output</strong></td><td>What should the response include?</td></tr>
+  <tr><td><strong>Voice Settings</strong></td><td>Welcome message, hang-up rules, wait message? (if Voice AI)</td></tr>
+</table>
+
+<h3>Minimum Viable Information</h3>
+<table>
+  <tr><th>Must Have</th><th>Description</th></tr>
+  <tr><td>AI Type</td><td>Voice, Chat, or Dashboard</td></tr>
+  <tr><td>2-3 Intent Categories</td><td>Plus Fallback</td></tr>
+  <tr><td>1 Primary Action</td><td>Data source OR external tool</td></tr>
+  <tr><td>Success Output</td><td>What to return on completion</td></tr>
+</table>
+
+<hr>
+
+<h2>🎯 Prime Directive: Generate ALL THREE Parts</h2>
+
+<p>For every AI Employee, <strong>ALWAYS generate THREE parts</strong>:</p>
+
+<h3>Part 1: Workflow Prompt (for Auto Builder)</h3>
+<p>The backend logic — what agents, how they connect, decision flow:</p>
+<ul>
+  <li>Trigger, Inputs, Agents/Nodes, Connections, Decision Logic, APIs, Outputs</li>
+</ul>
+
+<h3>Part 2: Persona Configuration (Voice/Chat Settings)</h3>
+<p>The frontend behavior — how the AI talks:</p>
+<ul>
+  <li>welcomeMessage, identityAndPurpose, takeActionInstructions, hangupInstructions</li>
+  <li>speechCharacteristics, systemPrompt, waitMessage</li>
+</ul>
+
+<h3>Part 3: Proto_Config JSON (Complete Configuration)</h3>
+<p>The full technical spec combining workflow + persona for direct deployment.</p>
+
+<hr>
+
+<h2>AI Employee Types</h2>
+
+<table>
+  <tr><th>Type</th><th>Project Type</th><th>Key Widgets</th></tr>
+  <tr><td><strong>Voice AI</strong></td><td>5</td><td>voiceSettings, conversationSettings, vadSettings</td></tr>
+  <tr><td><strong>Chat AI</strong></td><td>4</td><td>chatbotSdkConfig, fileUpload, feedback</td></tr>
+  <tr><td><strong>Dashboard AI</strong></td><td>2</td><td>dashboardConfig, inputSchema</td></tr>
+  <tr><td><strong>Document Gen</strong></td><td>3</td><td>documentSettings, templates</td></tr>
+</table>
+
+<hr>
+
+<h2>🎯 Opinionated Recommendations</h2>
+
+<blockquote>When multiple options exist, choose the best one.</blockquote>
+
+<h3>Node Selection</h3>
+<table>
+  <tr><th>Use Case</th><th>✅ Recommended</th><th>❌ Avoid</th></tr>
+  <tr><td>Intent routing</td><td><code>chat_categorizer</code></td><td><code>text_categorizer</code> for chat</td></tr>
+  <tr><td>Search-based response</td><td><code>respond_with_sources</code></td><td><code>call_llm</code> (loses citations)</td></tr>
+  <tr><td>Static content</td><td><code>fixed_response</code></td><td><code>call_llm</code> (wasteful)</td></tr>
+  <tr><td>Tool explanation</td><td><code>respond_for_external_actions</code></td><td><code>call_llm</code></td></tr>
+</table>
+
+<h3>Input Source Selection</h3>
+<table>
+  <tr><th>Node</th><th>✅ Always Use</th><th>❌ Never Use</th></tr>
+  <tr><td><code>chat_categorizer</code></td><td><code>chat_conversation</code></td><td><code>user_query</code></td></tr>
+  <tr><td><code>search</code></td><td><code>user_query</code> or <code>summarized</code></td><td><code>chat_conversation</code></td></tr>
+  <tr><td><code>call_llm</code> query</td><td><code>user_query</code></td><td><code>chat_conversation</code></td></tr>
+  <tr><td><code>call_llm</code> context</td><td><code>named_inputs</code> with <code>chat_conversation</code></td><td>—</td></tr>
+</table>
+
+<h3>Architecture Decisions</h3>
+<table>
+  <tr><th>Decision</th><th>Recommendation</th></tr>
+  <tr><td>Categories count</td><td><strong>3-5 max</strong> per categorizer; use hierarchy for more</td></tr>
+  <tr><td>HITL on external action</td><td><strong>Always</strong> for any action with side effects</td></tr>
+  <tr><td>Search strategy</td><td><strong>KB first</strong>, web search secondary</td></tr>
+  <tr><td>Error handling</td><td><strong>Always explicit</strong>; never assume happy path</td></tr>
+  <tr><td>Fallback</td><td><strong>Always include</strong>; ask clarifying question</td></tr>
+</table>
+
+<hr>
+
+<h2>Auto Builder: Official Action Names</h2>
+
+<h3>Triggers & Routing</h3>
+<table>
+  <tr><th>Action Name</th><th>Display Name</th><th>Output</th></tr>
+  <tr><td><code>chat_trigger</code></td><td>Chat Trigger</td><td><code>chat_conversation</code>, <code>user_query</code></td></tr>
+  <tr><td><code>document_trigger</code></td><td>Document Trigger</td><td><code>user_query</code> (documents)</td></tr>
+  <tr><td><code>chat_categorizer</code></td><td>Intent Classifier</td><td><code>category_&lt;name&gt;</code></td></tr>
+  <tr><td><code>text_categorizer</code></td><td>Text Categorizer</td><td><code>category_&lt;name&gt;</code></td></tr>
+  <tr><td><code>conversation_to_search_query</code></td><td>Conversation Summarizer</td><td><code>summarized_conversation</code></td></tr>
+</table>
+
+<h3>Search & Response</h3>
+<table>
+  <tr><th>Action Name</th><th>Display Name</th><th>Input → Output</th></tr>
+  <tr><td><code>search</code></td><td>File Search</td><td>query → <code>search_results</code></td></tr>
+  <tr><td><code>live_web_search</code></td><td>Live Web Search</td><td>query → <code>web_search_results</code></td></tr>
+  <tr><td><code>respond_with_sources</code></td><td>Respond using Search Results</td><td>query + search_results → response</td></tr>
+  <tr><td><code>call_llm</code></td><td>Respond</td><td>query + named_inputs → response</td></tr>
+  <tr><td><code>external_action_caller</code></td><td>External Tool Caller</td><td>query → tool_result</td></tr>
+</table>
+
+<h3>Validation Rules</h3>
+<table>
+  <tr><th>Action Name</th><th>Display Name</th><th>Critical Rules</th></tr>
+  <tr><td><code>general_hitl</code></td><td>Human Collaboration</td><td>MUST have both success AND failure paths</td></tr>
+  <tr><td><code>response_validator</code></td><td>Response Validator</td><td>Validates LLM output</td></tr>
+  <tr><td><code>entity_extraction_with_documents</code></td><td>Entity Extraction</td><td>Works on DOCUMENTS not text</td></tr>
+</table>
+
+<hr>
+
+<h2>Voice AI Required Fields</h2>
+
+<table>
+  <tr><th>UI Field</th><th>Config Key</th><th>Required</th></tr>
+  <tr><td><strong>How should the call start?</strong></td><td><code>welcomeMessage</code></td><td><span class="tag tag-required">Required</span></td></tr>
+  <tr><td><strong>Define identity and purpose</strong></td><td><code>identityAndPurpose</code></td><td><span class="tag tag-required">Required</span></td></tr>
+  <tr><td><strong>Define actions AI can perform</strong></td><td><code>takeActionInstructions</code></td><td><span class="tag tag-required">Required</span></td></tr>
+  <tr><td><strong>When should the call end?</strong></td><td><code>hangupInstructions</code></td><td><span class="tag tag-required">Required</span></td></tr>
+  <tr><td>When to transfer to human?</td><td><code>transferCallInstructions</code></td><td>Optional</td></tr>
+  <tr><td>Speech characteristics</td><td><code>speechCharacteristics</code></td><td>Optional</td></tr>
+  <tr><td>Tool calling instructions</td><td><code>systemPrompt</code></td><td>Optional</td></tr>
+  <tr><td>Wait message</td><td><code>waitMessage</code></td><td>Optional</td></tr>
+</table>
+
+<h3>Voice Settings Widget Types</h3>
+<table>
+  <tr><th>Widget ID</th><th>Widget</th><th>Purpose</th></tr>
+  <tr><td>38</td><td>voiceSettings</td><td>Language hints, voice model</td></tr>
+  <tr><td>39</td><td>conversationSettings</td><td>Identity, purpose, actions</td></tr>
+  <tr><td>43</td><td>vadSettings</td><td>turnTimeout, silenceEndCallTimeout, maxDuration</td></tr>
+  <tr><td>42</td><td>dataStorageSettings</td><td>Audio/transcript recording</td></tr>
+</table>
+
+<hr>
+
+<h2>Tool Calling Rules (Voice)</h2>
+<ol>
+  <li><strong>Collect all parameters</strong> before calling a tool</li>
+  <li><strong>Wait for response</strong> before calling another tool</li>
+  <li><strong>Never mention tool names</strong> to the user</li>
+  <li><strong>Never guess</strong> parameter values</li>
+  <li><strong>Plain language</strong> for what you're doing</li>
+  <li><strong>Handle delays</strong> with "Just a moment..."</li>
+  <li><strong>Handle errors</strong> gracefully, offer alternatives</li>
+</ol>
+
+<hr>
+
+<h2>Categorizer Validation (Critical!)</h2>
+
+<div class="callout callout-error">
+  <strong>⚠️ EVERY categorizer MUST have:</strong>
+  <ol>
+    <li>At least one outgoing edge</li>
+    <li>Output format: <code>category_&lt;CategoryName&gt;</code></li>
+    <li>Target input: <code>trigger_when</code></li>
+    <li>A Fallback category</li>
+  </ol>
+</div>
+
+<h3>Type Compatibility</h3>
+<pre><code>chat_trigger.chat_conversation → chat_categorizer.conversation ✅
+chat_trigger.user_query → search.query ✅
+search.search_results → respond_with_sources.search_results ✅
+call_llm.named_inputs accepts ANY type (WELL_KNOWN_TYPE_ANY)</code></pre>
+
+<hr>
+
+<h2>Agent Quick Reference</h2>
+
+<h3>Core Workflow Agents</h3>
+<table>
+  <tr><th>Agent</th><th>Use For</th></tr>
+  <tr><td>Abstain from Answering</td><td>Decline when cannot answer</td></tr>
+  <tr><td>Categorize Conversations and Route</td><td>First node, classify intent</td></tr>
+  <tr><td>Combine Search Results</td><td>Merge multiple search sources</td></tr>
+  <tr><td>Conversation Summarizer</td><td>Normalize chat to query</td></tr>
+  <tr><td>Deep Web Search</td><td>Real-time external info</td></tr>
+  <tr><td>Extract Entities</td><td>Pull structured data from text</td></tr>
+  <tr><td>Fixed Response</td><td>Static/template content</td></tr>
+  <tr><td>Human Collaboration</td><td>Route to human for approval</td></tr>
+  <tr><td>Knowledge Search</td><td>Answer from internal docs</td></tr>
+  <tr><td>Respond using Search Results</td><td>Synthesize search results with citations</td></tr>
+  <tr><td>Response Validator</td><td>Validate output, abstain if fail</td></tr>
+  <tr><td>External Tool Caller</td><td>Execute integrations (ServiceNow, Salesforce, etc.)</td></tr>
+</table>
+
+<h3>Domain Agents by Category</h3>
+<table>
+  <tr><th>Category</th><th>Agents</th></tr>
+  <tr><td><strong>Finance</strong></td><td>Audit Evidence Verifier, Financial Risk Assessor, Financial Statement Analyzer, Tax Advisor</td></tr>
+  <tr><td><strong>Healthcare</strong></td><td>Medical Record Summarizer, Medical Research Assistant, Insurance Claim Summarizer</td></tr>
+  <tr><td><strong>Legal</strong></td><td>Compliance Document Analyzer, Legal Expert, Legal Precedent Analyser</td></tr>
+  <tr><td><strong>Sales</strong></td><td>Sales Intelligence, Sales Contract Summarizer, Email Writer</td></tr>
+  <tr><td><strong>IT/Security</strong></td><td>Cybersecurity Expert, Phishing Email Detector, Technical Support</td></tr>
+  <tr><td><strong>HR</strong></td><td>Employee Onboarding Customizer, Internal Job Mobility Matcher</td></tr>
+</table>
+
+<hr>
+
+<h2>🔍 Workflow Review & Audit</h2>
+
+<p>Use these tools to analyze existing workflows, detect issues, and propose fixes.</p>
+
+<h3>Review Command Flow</h3>
+<pre><code>1. mcp_ema_persona(id=persona_id, include_workflow=true, env=env) → Get workflow
+2. mcp_ema_workflow(mode="analyze", persona_id=persona_id, env=env) → Full analysis
+3. mcp_ema_workflow(mode="analyze", workflow_def=&lt;workflow_def&gt;, include=["issues"]) → Find issues
+4. mcp_ema_workflow(mode="analyze", workflow_def=&lt;workflow_def&gt;, include=["fixes"]) → Get fix proposals
+5. Apply fixes and re-validate</code></pre>
+
+<h3>Issue Detection</h3>
+<table>
+  <tr><th>Issue Type</th><th>Detection</th><th>Impact</th></tr>
+  <tr><td><strong>Loops</strong></td><td>Cycles in edge graph</td><td>Infinite execution</td></tr>
+  <tr><td><strong>Deadlocks</strong></td><td>Unreachable inputs</td><td>Workflow hangs</td></tr>
+  <tr><td><strong>Orphans</strong></td><td>Disconnected nodes</td><td>Wasted resources</td></tr>
+  <tr><td><strong>Dead Ends</strong></td><td>No path to OUTPUT</td><td>Response lost</td></tr>
+  <tr><td><strong>Type Mismatch</strong></td><td>Incompatible types</td><td>Runtime errors</td></tr>
+  <tr><td><strong>Missing Fallback</strong></td><td>No Fallback category</td><td>Validation fails</td></tr>
+  <tr><td><strong>Incomplete HITL</strong></td><td>Missing success/failure</td><td>Approval breaks</td></tr>
+</table>
+
+<h3>Input Source Selection (CRITICAL)</h3>
+<table>
+  <tr><th>Node Type</th><th>✅ Use This</th><th>❌ NOT This</th></tr>
+  <tr><td><code>chat_categorizer</code></td><td><code>chat_conversation</code></td><td><code>user_query</code> (loses context)</td></tr>
+  <tr><td><code>search</code></td><td><code>user_query</code> or <code>summarized</code></td><td><code>chat_conversation</code> (type error)</td></tr>
+  <tr><td><code>respond_with_sources</code></td><td><code>user_query</code> for query</td><td><code>chat_conversation</code></td></tr>
+  <tr><td><code>call_llm</code></td><td><code>user_query</code> + <code>named_inputs</code></td><td><code>chat_conversation</code> for query</td></tr>
+</table>
+
+<hr>
+
+<h2>✅ Checklists</h2>
+
+<h3>All Prompts Checklist</h3>
+<ul>
+  <li>☐ Persona type specified (Voice/Chat/Dashboard)</li>
+  <li>☐ Clear one-sentence goal</li>
+  <li>☐ Trigger event specified</li>
+  <li>☐ Inputs with types/constraints</li>
+  <li>☐ Pre-fill/auto-suggest behavior</li>
+  <li>☐ Validations with API calls</li>
+  <li>☐ Decision logic (all branches)</li>
+  <li>☐ Actions for each outcome</li>
+  <li>☐ Output schemas (success + exception)</li>
+  <li>☐ Error handling/retries</li>
+</ul>
+
+<h3>Voice AI Specific Checklist</h3>
+<p><strong>REQUIRED:</strong></p>
+<ul>
+  <li>☐ welcomeMessage — "Hello! I'm [Name]..."</li>
+  <li>☐ identityAndPurpose — Role, responsibilities, guidelines</li>
+  <li>☐ takeActionInstructions — &lt;/Case N&gt; format with triggers + params</li>
+  <li>☐ hangupInstructions — When to end call</li>
+</ul>
+<p><strong>RECOMMENDED:</strong></p>
+<ul>
+  <li>☐ transferCallInstructions — When to escalate</li>
+  <li>☐ speechCharacteristics — TTS rules, tone</li>
+  <li>☐ systemPrompt — Tool calling rules</li>
+  <li>☐ waitMessage — Processing delays</li>
+</ul>
+
+<h3>MCP Integration Checklist</h3>
+<ul>
+  <li>☐ Called <code>mcp_ema_template(questions=true)</code> before asking user</li>
+  <li>☐ Called <code>mcp_ema_action(suggest="...")</code> for pattern recommendation</li>
+  <li>☐ Called <code>mcp_ema_template(pattern="...")</code> for template</li>
+  <li>☐ Called <code>mcp_ema_action(id="...", include_docs=true)</code> for each agent used</li>
+  <li>☐ Called <code>mcp_ema_reference(validate_prompt="...")</code> before final output</li>
+  <li>☐ Checked <code>mcp_ema_reference(mistakes=true)</code> for top errors</li>
+</ul>
+
+<hr>
+
+<p style="text-align: center; color: #5f6368; font-size: 0.9em;">
+  <em>Ema Auto Builder Quick Reference Guide</em><br>
+  Generated from ema-mcp-toolkit documentation
+</p>
+
+</body>
+</html>
+