@ema.co/mcp-toolkit 2026.2.13 → 2026.2.23-1

package/.context/public/guides/mcp-tools-guide.md

@@ -1,67 +1,45 @@
 ---
-title: "Ema MCP Tools Guide (Consolidated)"
-date: 2026-01-27
+title: "Ema MCP Tools Guide"
+date: 2026-02-13
 audience: public
 ---
-# Ema MCP Tools Guide (Consolidated)
+# Ema MCP Tools Guide
 
 This MCP server is intentionally designed for **LLM + agent ergonomics**:
 
 - **Self-contained guidance**: Server instructions, tool tips, and response hints are built-in
-- **Few tools, consistent shapes**: a small set of noun-based tools with predictable `mode` / flag patterns
+- **Few tools, consistent shapes**: a small set of noun-based tools with predictable `method` / `mode` patterns
 - **Resources-first**: use `ema://...` resources for reference data/templates, then tools for actions
 - **Low ambiguity**: defaults are chosen to avoid "which of 5 similar tools?" confusion
-- **Explicit mode**: tools with multiple operations require explicit `mode` - they clarify if omitted
+- **Explicit method/mode**: tools with multiple operations require explicit parameter - they clarify if omitted
 
 > **Note**: No external configuration files (like Cursor rules) are required. All guidance is embedded in the MCP server and delivered via server instructions, tool descriptions, and response tips.
 
 ## Tool names in MCP clients
 
-The server defines **base tool names** like `persona`, `template`.
+The server defines **base tool names** like `persona`, `catalog`.
 
 Some clients show a **prefixed name** (for example Cursor: `mcp_ema_persona`). Always call **the tool name your client displays**; the semantics are the same.
 
-## The tool set (7 active tools)
+## The tool set (6 public tools)
 
-| Tool | Purpose | Mode Required? |
-|------|---------|----------------|
-| `env` | List environments | No (single operation) |
-| `persona` | AI Employee management | **YES** |
-| `data` | Data management + document generation | **YES** |
-| `action` | Actions/agents lookup | No (flag-based) |
-| `template` | Patterns, widgets, questions | No (flag-based) |
-| `reference` | Envs, actions, templates, patterns, concepts, guidance | No (flag-based) |
-| `sync` | Sync across environments | **YES** |
-
-### `workflow` tool (get/deploy only)
-
-| Mode | Purpose |
-|------|---------|
-| `get` | Returns workflow_def, schema, examples for LLM |
-| `deploy` | Deploys LLM-generated workflow_def |
+| Tool | Purpose | Key Parameter |
+|------|---------|---------------|
+| `persona` | AI Employee management (CRUD, data, snapshots, sanitization) | `method` (required) |
+| `catalog` | Browse platform catalog (actions, templates, widgets, voices, patterns, concepts) | `method` + `type` (required) |
+| `workflow` | Get workflow data, validate, deploy LLM-generated workflows, optimize | `mode` (required) |
+| `sync` | Sync personas between environments | `method` (required) |
+| `env` | List available environments | No params |
+| `toolkit_feedback` | Submit feedback about the toolkit | `method` (required) |
 
 **LLM does all thinking** (analyze, compare, generate). MCP only provides data and executes.
 
-### Deprecated tools (still work, show warnings)
-
-| Tool | Status | Use Instead |
-|------|--------|-------------|
-| `knowledge` | Deprecated | `data` |
-| `demo` | Deprecated | `data` + `persona` |
-
-> **Tip**: For new code, use `persona`, `data`, `workflow`, `sync`.
-
-## ⚠️ THE KEY INSIGHT: ONE CALL
+## THE KEY INSIGHT: ONE CALL
 
 Creating an AI Employee should be **ONE `persona()` call**, not multiple calls.
 
-```typescript
-persona(
-  input="Voice AI SDR: qualifies leads, identifies use-case, sends follow-up email",
-  type="voice",
-  name="Sales SDR",
-  preview=false
-)
+```
+persona(method="create", name="Sales SDR", type="voice")
 ```
 
 **MCP handles internally:** template selection, config generation, widget formatting, API orchestration.
@@ -70,77 +48,46 @@ persona(
 
 ### Create a new AI Employee (greenfield)
 
-1. **Get qualifying questions from MCP**: `template(questions=true)`
-2. **Ask user those questions**
+1. **Browse templates**: `catalog(method="list", type="templates")`
+2. **Ask user qualifying questions**
 3. **Create in ONE call**:
-   ```typescript
-   persona(
-     input="<everything from user answers>",
-     name="My AI Employee",
-     type="voice",
-     preview=false
-   )
    ```
-
-### Complex Workflows (email, HITL, multi-intent)
-
-For complex workflows, MCP returns `status: "needs_llm_generation"` with a prompt you send to an LLM:
-
-```typescript
-// Step 1: Request creation
-result = persona(
-  input="SDR that qualifies leads and sends follow-up emails",
-  type="voice",
-  name="Sales SDR",
-  preview=true
-)
-
-// If result.status === "needs_llm_generation":
-// Step 2: Send result.llm_prompt to an LLM (Claude, GPT-4, etc.)
-// Step 3: Deploy the LLM's workflow response
-persona(
-  workflow_def=llm_response_json,
-  name="Sales SDR",
-  type="voice",
-  preview=false
-)
-```
-
-**Simple workflows** (basic Q&A, search + respond) deploy directly without this extra step.
+   persona(method="create", name="My AI Employee", type="voice")
+   ```
 
 ### Modify an existing AI Employee (brownfield)
 
-```typescript
-// Optional: Understand what exists first
-persona(mode="get", id="abc-123")
+```
+// Understand what exists first
+persona(method="get", id="abc-123")
 
 // Modify config in ONE call
-persona(mode="update", id="abc-123", config={widgets: [{name: "conversationSettings", conversationSettings: {...}}]})
+persona(method="update", id="abc-123", config={widgets: [{name: "conversationSettings", conversationSettings: {...}}]})
 ```
 
 ### Get workflow data (for LLM to analyze/modify)
 
-```typescript
+```
 workflow(mode="get", persona_id="abc-123")  // Returns workflow_def, schema, examples
 ```
 
 The LLM then analyzes/modifies the workflow and deploys:
 
-```typescript
-workflow(mode="deploy", persona_id="abc-123", workflow_def={...})  // Deploy LLM's result
+```
+workflow(mode="deploy", persona_id="abc-123", base_fingerprint="...", workflow_def={...})
 ```
 
 ### Upload / manage knowledge base documents
 
-1. Upload: `data(persona_id="...", mode="upload", file="/path/to/file.pdf")`
-2. Enable embedding: `data(persona_id="...", mode="embedding", enabled=true)`
-3. Verify: `data(persona_id="...", mode="list")`
+1. Upload: `persona(id="abc", data={method:"upload", path:"/path/to/file.pdf"})`
+2. Enable embedding: `persona(id="abc", data={method:"embed", enabled:true})`
+3. Verify: `persona(id="abc", data={method:"stats"})`
 
 ### Clone and sanitize personas for demo
 
 **Recommended: Use action composition for multi-step operations**
 
-```typescript
+```
 // Clone with data copy and sanitization (recommended)
 persona(
   method="create",
@@ -165,36 +112,22 @@ persona(method="create", from="source-id", name="Demo Clone", actions=["standard
 
 **Context variables:** `$source` (from param), `$target` (created persona ID), `$env` (environment)
 
-**Legacy syntax (still works):**
-
-```typescript
-// Clone a persona with all data (files + dashboard rows for dashboard personas)
-// Note: Dashboard cloning auto-enables the persona (required for adding rows)
-persona(mode="clone", from="source-id", name="Demo Clone", include_data=true)
-
-// Clone with data sanitization (sanitizes both config and dashboard row data)
-persona(mode="clone", from="source-id", name="Demo Clone", include_data=true, sanitize=true)
-
-// Provide custom examples of sensitive data to sanitize
-persona(mode="clone", from="source-id", name="Demo Clone", include_data=true, sanitize=true, sanitize_examples=["Acme Corp", "john@example.com"])
-```
-
 **Sanitize an existing persona (TWO STEP PROCESS):**
 
-```typescript
+```
 // Step 1: Preview (identifies PII, returns items_needing_review count)
 persona(method="sanitize", id="abc")
 
-// Step 2: Provide known PII values and apply (only works when items_needing_review=0)
+// Step 2: Provide known PII values and apply
 persona(method="sanitize", id="abc", examples=["Acme Corp", "john@example.com"], apply=true)
 ```
 
 **Sanitization Notes:**
-- **Two-step process**: First call returns preview with `items_needing_review` count. Changes only apply when `items_needing_review=0` AND `preview=false`
+- **Two-step process**: First call returns preview with `items_needing_review` count. Second call applies with `apply=true`
 - **Auto-detects**: emails, phones, SSNs, credit cards (by issuer prefix), API keys, JWTs
 - **NOT detected by default**: UUIDs (typically system IDs like `template_id`, `persona_id`)
-- `sanitize_examples`: for company names, person names, vendor names, custom identifiers - providing these reduces `items_needing_review`
-- **Transforms**: pseudonymize (names → fake names), mask (phones → `***-***-1234`), redact (credentials)
+- `examples`: for company names, person names, vendor names, custom identifiers - providing these reduces `items_needing_review`
+- **Transforms**: pseudonymize (names -> fake names), mask (phones -> `***-***-1234`), redact (credentials)
 - **Allowlist approach**: Only content fields sanitized (description, prompts, fixed_response), system fields preserved
 - Dashboard row sanitization: applies to row data during clone
 
@@ -202,251 +135,209 @@ persona(method="sanitize", id="abc", examples=["Acme Corp", "john@example.com"],
 
 For fine-grained control over dashboard data:
 
-```typescript
-// List rows from a dashboard
-knowledge(persona_id="abc", mode="dashboard_rows")
+```
+// List data items from a persona
+persona(id="abc", data={method:"list"})
 
-// Clone dashboard rows separately (usually not needed - use persona clone_data instead)
-knowledge(persona_id="target", mode="dashboard_clone", source_persona_id="source")
+// Get file counts
+persona(id="abc", data={method:"stats"})
 ```
 
 ### Sync between environments
 
-- Run (single): `sync(id="My Bot", source="demo", target="dev", dry_run=true|false)`
-- Run (all tagged): `sync(target="dev", scope="all", dry_run=true|false)`
-- Status: `sync(mode="status", id="My Bot", env="dev")`
+```
+// Preview changes first
+sync(method="preview", persona="My Bot", from="staging", to="prod")
+
+// Execute sync
+sync(method="execute", persona="My Bot", from="staging", to="prod")
+
+// Check status
+sync(method="status")
+sync(method="status", persona="My Bot")
+```
 
 ### Version / snapshot AI Employees
 
-```typescript
+```
 // Before a risky change - create a snapshot
-persona(mode="version_create", id="My Bot", message="Before adding HITL")
+persona(method="snapshot", id="abc", message="Before adding HITL")
 
 // Make changes...
-persona(mode="update", id="abc", config={...})
+persona(method="update", id="abc", config={...})
 
 // If something breaks - restore
-persona(mode="version_list", id="My Bot")
-persona(mode="version_restore", id="My Bot", version="v3")
+persona(method="history", id="abc")
+persona(method="restore", id="abc", version="v3")
 ```
 
 ## Tool reference (high-signal)
 
-### `persona` (explicit mode required)
+### `persona` (explicit method required)
+
+**`method` is required.** If omitted, the tool will ask for clarification.
 
-**Mode is required.** If omitted, the tool will ask for clarification.
+Valid methods: `list`, `get`, `create`, `update`, `delete`, `sanitize`, `schema`, `snapshot`, `history`, `restore`
 
 **List/Get:**
-```typescript
-persona(mode="list")
-persona(mode="list", query="support", status="active")
-persona(mode="get", id="abc")
-persona(mode="get", id="abc", include_workflow=true)
+```
+persona(method="list")
+persona(method="list", query="support", status="active")
+persona(method="get", id="abc")
+persona(method="get", id="abc", include_workflow=true)
+persona(method="get", id="abc", include_fingerprint=true)  // for stale-state protection
 ```
 
 **Create:**
-```typescript
-persona(mode="create", input="<what it does>", type="voice", name="My Bot", preview=false)
-persona(mode="create", from="Voice AI Starter", name="My Bot", input="...", preview=false)
+```
+persona(method="create", name="My Bot", type="voice")
+persona(method="create", name="My Bot", from="Voice AI Starter")  // from template
+persona(method="create", name="My Bot", from="source-persona-id")  // clone
 ```
 
 **Update config:**
-```typescript
-persona(mode="update", id="abc", config={widgets: [{...}]})
+```
+persona(method="update", id="abc", base_fingerprint="...", config={widgets: [{...}]})
 ```
 
-**Clone:**
-```typescript
-persona(mode="clone", from="source-id", name="My Copy", include_data=true)
+**Delete:**
+```
+persona(method="delete", id="abc", confirm=true)
 ```
 
 **Sanitize (two-step process):**
-```typescript
-persona(id="abc", sanitize=true)  // Step 1: Preview - identify PII
-persona(id="abc", sanitize=true, sanitize_examples=["Acme"], preview=false)  // Step 2: Apply
 ```
-
-**Intent (qualification for complex requests):**
-```typescript
-// GREENFIELD: New persona creation
-persona(mode="intent", input="Voice AI SDR that qualifies leads", type="voice")
-
-// BROWNFIELD: Complex modification to existing persona
-persona(mode="intent", input="Send emails with discussion items and key points", id="abc-123")
-
-// Iterative - provide answers to qualify further
-persona(mode="intent", input="...", previous_answers={gate1_q1: "inbound"}, iteration=2)
+persona(method="sanitize", id="abc")  // Step 1: Preview - identify PII
+persona(method="sanitize", id="abc", examples=["Acme"], apply=true)  // Step 2: Apply
 ```
 
-Intent mode applies to **both greenfield AND brownfield** scenarios. Use it when:
-- Creating complex new personas (multi-intent, HITL, email, taxonomy)
-- Modifying existing personas with complex changes that may have ripple effects
-- Any request where qualification questions help clarify WHY/WHAT/CONSTRAINTS
-
-Returns:
-- `status: "ready"` → `intent_spec` ready for WorkflowSpec transformation
-- `status: "needs_qualification"` → `questions` to answer before proceeding  
-- `status: "needs_llm"` → `llm_prompt` to send to LLM for IntentSpec generation
-
-For brownfield, use `workflow(mode="get")` to fetch current state, then use intent to qualify the change.
+**Version management:**
+```
+persona(method="snapshot", id="abc", message="Before update")
+persona(method="history", id="abc")
+persona(method="restore", id="abc", version="v2")
+```
 
-**Templates:**
-```typescript
-persona(mode="templates")
+**Schema:**
+```
+persona(method="schema", id="abc")  // Get input schema (dashboard columns, types)
 ```
 
-**Version management:**
-```typescript
-persona(mode="version_create", id="abc", message="Before update")
-persona(mode="version_list", id="abc")
-persona(mode="version_restore", id="abc", version="v2")
-persona(mode="version_policy", id="abc", auto_on_deploy=true)
+**Data sub-resource (requires id):**
+```
+persona(id="abc", data={method:"list"})
+persona(id="abc", data={method:"stats"})
+persona(id="abc", data={method:"stats", widget_name:"kb"})
+persona(id="abc", data={method:"upload", path:"/path/to/file.pdf"})
+persona(id="abc", data={method:"upload", path:"/file.pdf", widget_name:"upload1"})
+persona(id="abc", data={method:"upload", items:[{"Column": "value", "Doc": {file: "/path"}}]})
+persona(id="abc", data={method:"delete", file_id:"file-123"})
+persona(id="abc", data={method:"copy", from:"source-id"})
+persona(id="abc", data={method:"copy", from:"source-id", sanitize:true})
+persona(id="abc", data={method:"replicate", from:"source-id"})
+persona(id="abc", data={method:"embed"})
+persona(id="abc", data={method:"embed", enabled:true})
+persona(id="abc", data={method:"search", query:"pricing"})
 ```
 
-### `template`
+> **Important for Document Generation (Proposal Writer) personas:** Files must be uploaded to the correct widget to appear in the right repository in the UI. Without `widget_name`, files go to the default `fileUpload` widget which may not be visible in the Configuration tab.
+>
+> **Document Proposal Manager widgets:** `upload` (Content Repository), `upload1` (Service Line Documents), `upload2` (Style Guide)
+>
+> **For other templates:** Call `persona(method="get", id="abc", include_workflow=true)` and inspect `proto_config.widgets[].name` to find the exact widget names.
 
-**Primary use - Get qualifying questions:**
-```typescript
-template(questions=true)                    // All questions
-template(questions=true, category="Voice")  // Voice-specific
+**Replicate (copy by reference - fast, no file transfer):**
 ```
-
-**Reference (understand options):**
-```typescript
-template(patterns=true)
-template(pattern="intent-routing")
-template(widgets="voice")
+persona(id="target-id", data={method:"replicate", from:"source-id"})
+persona(id="target-id", data={method:"replicate", from:"source-id", widget_mappings:[{source_widget:"docs", target_widget:"documents"}]})
+persona(id="target-id", data={method:"replicate", from:"source-id", wait:false})
 ```
 
-### `action`
+> **Note:** `replicate` is much faster than copying files. It copies S3 references instead of downloading and re-uploading. Use `method:"copy"` if you need to sanitize data during transfer.
 
-```typescript
-action(id="chat_categorizer", include_docs=true)   // Get specific
-action(all=true)                                    // List all
-action(suggest="IT helpdesk with ServiceNow")      // Get recommendations
-```
+### `catalog` (method + type required)
 
-### `reference` (v2 expanded)
+**Browse platform reference data.** Replaces the old `action`, `template`, and `reference` tools.
 
-**Environments:**
-```typescript
-reference(type="envs")
-```
+Valid methods: `list`, `get`, `search`, `recommend`
+Valid types: `actions`, `templates`, `widgets`, `voices`, `patterns`, `concepts`
 
-**Actions (replaces `action` tool):**
-```typescript
-reference(type="actions")                     // List all
-reference(type="actions", id="send_email")    // Get specific
-reference(type="actions", suggest="IT helpdesk")  // Recommendations
 ```
+// Actions (workflow nodes/agents)
+catalog(method="list", type="actions")
+catalog(method="get", type="actions", id="chat_categorizer")
+catalog(method="search", type="actions", query="email")
+catalog(method="recommend", type="actions", for="IT helpdesk with ServiceNow")
 
-**Templates & Patterns:**
-```typescript
-reference(type="templates")                   // Persona templates (dynamic, tenant-specific)
-reference(type="patterns")                    // Workflow patterns
-reference(type="patterns", pattern="intent-routing")
-reference(type="widgets", persona_type="voice")
-```
+// Templates (persona templates - tenant-specific)
+catalog(method="list", type="templates")
+catalog(method="get", type="templates", id="voice-ai-starter")
 
-> **Note:** Templates are tenant-specific. Always use `reference(type="templates")` to discover available templates rather than hardcoding template IDs.
+// Patterns (workflow patterns)
+catalog(method="list", type="patterns")
+catalog(method="get", type="patterns", id="intent-routing")
+catalog(method="recommend", type="patterns", for="human in the loop")
 
-**Concepts & Guidance:**
-```typescript
-reference(concept="HITL")
-reference(guidance="categorizer-routing")
-reference(questions=true)                     // Qualifying questions
-```
+// Widgets (configuration widgets)
+catalog(method="list", type="widgets")
+
+// Voices (voice models)
+catalog(method="list", type="voices")
 
-**Debugging:**
-```typescript
-reference(mistakes=true)
-reference(checklist=true)
-reference(execution=true)
+// Concepts (platform terminology)
+catalog(method="list", type="concepts")
+catalog(method="get", type="concepts", id="HITL")
 ```
 
-### `data` (explicit mode required)
+> **Note:** Templates are tenant-specific. Always use `catalog(method="list", type="templates")` to discover available templates rather than hardcoding template IDs.
 
-**Mode is required.** If omitted, the tool will ask for clarification.
+### `workflow` (mode required)
 
-**List files:**
-```typescript
-data(persona_id="abc", mode="list")
-data(persona_id="abc", mode="list", limit=50)
-```
+Valid modes: `get`, `deploy`, `validate`, `optimize`
 
-**Get specific file:**
-```typescript
-data(persona_id="abc", mode="get", file_id="file-123")
 ```
+// Get workflow data for LLM to work with
+workflow(mode="get", persona_id="abc")
 
-**Upload/Delete:**
-```typescript
-data(persona_id="abc", mode="upload", file="/path/to/file.pdf")
-data(persona_id="abc", mode="delete", file_id="file-123")
-```
+// Validate before deploying
+workflow(mode="validate", persona_id="abc")
+workflow(mode="validate", workflow_spec={...})
 
-**Upload to specific widget (Document Generation personas):**
-```typescript
-// Document Proposal Manager widget names (verified from template):
-data(persona_id="abc", mode="upload", file="/path/to/company.pdf", widget_name="upload")      // Content Repository
-data(persona_id="abc", mode="upload", file="/path/to/service-line.pdf", widget_name="upload1") // Service Line Documents
-data(persona_id="abc", mode="upload", file="/path/to/style-guide.pdf", widget_name="upload2")  // Style Guide
-```
+// Deploy LLM-generated workflow
+workflow(mode="deploy", persona_id="abc", base_fingerprint="...", workflow_def={...})
+workflow(mode="deploy", persona_id="abc", workflow_def_path="/path/to/wf.json")  // large payloads
 
-> **Important for Document Generation (Proposal Writer) personas:** Files must be uploaded to the correct widget to appear in the right repository in the UI. Without `widget_name`, files go to the default `fileUpload` widget which may not be visible in the Configuration tab.
->
-> **Document Proposal Manager widgets:** `upload` (Content Repository), `upload1` (Service Line Documents), `upload2` (Style Guide)
->
-> **For other templates:** Call `persona(id="abc", include_workflow=true)` and inspect `proto_config.widgets[].name` to find the exact widget names.
+// Optimize existing workflow
+workflow(mode="optimize", persona_id="abc")
+```
 
-**Generate content (via Document Generation API):**
-```typescript
-// From a template
-data(persona_id="abc", mode="generate", from="customer", count=5)
-data(persona_id="abc", mode="generate", from="demo-sales-sdr")
+### `sync` (method required)
 
-// From natural language
-data(persona_id="abc", mode="generate", input="Generate 5 B2B customer profiles")
+Valid methods: `preview`, `execute`, `status`
 
-// List available templates
-data(mode="templates")
-data(mode="templates", template="customer")  // Get template details
+```
+sync(method="preview", persona="My Bot", from="staging", to="prod")
+sync(method="execute", persona="My Bot", from="staging", to="prod")
+sync(method="status")
+sync(method="status", persona="My Bot")
 ```
 
-**Available templates:** `customer`, `product`, `faq`, `employee`, `demo-sales-sdr`, `demo-support`, `demo-hr`, `countries`, `industries`, `currencies`
+### `env`
 
-**Sanitize persona data:**
-```typescript
-data(persona_id="abc", mode="sanitize")
-data(persona_id="abc", mode="sanitize", include_workflow=true)
 ```
-
-**File Stats:**
-```typescript
-data(persona_id="abc", mode="stats")                    // Get file counts
-data(persona_id="abc", mode="stats", widget_name="kb")  // Filter by widget
-// Returns: { total: 50, pending: 5, success: 40, failed: 5 }
+env()  // List available environments and default
 ```
 
-**Replicate (copy by reference - fast, no file transfer):**
-```typescript
-// Copy knowledge base from source to target (references S3 objects, no re-upload)
-data(persona_id="target-id", mode="replicate", from="source-id")
+### `toolkit_feedback`
 
-// With custom widget mappings
-data(persona_id="target-id", mode="replicate", from="source-id", 
-     widget_mappings=[{source_widget: "docs", target_widget: "documents"}])
+Valid methods: `submit`, `list`, `analyze`
 
-// Async (don't wait for completion)
-data(persona_id="target-id", mode="replicate", from="source-id", wait=false)
 ```
-
-> **Note:** `replicate` is much faster than copying files. It copies S3 references instead of downloading and re-uploading. Use `mode="copy"` if you need to sanitize data during transfer.
-
-**Embedding:**
-```typescript
-data(persona_id="abc", mode="embedding")              // Get status
-data(persona_id="abc", mode="embedding", enabled=true) // Toggle
+toolkit_feedback(method="submit", category="gap", message="Missing docs on extraction columns")
+toolkit_feedback(method="submit", category="confusion", message="...", tool="workflow")
+toolkit_feedback(method="submit", category="success", message="Workflow deploy guidance was clear")
+toolkit_feedback(method="list")
+toolkit_feedback(method="analyze")
 ```
 
 ## Resources (read-first)
@@ -463,38 +354,37 @@ Start with:
 
 **MCP provides data and schema. LLM generates workflow_def.**
 
-```typescript
+```
 // 1. Get current workflow + schema (includes deprecation_warnings!)
 result = workflow(mode="get", persona_id="abc")
 // Returns: workflow_def, generation_schema, example_workflow, requirements, deprecation_warnings
 
 // 2. LLM analyzes and generates new workflow_def
 // (LLM uses schema and examples to build valid workflow)
-// ⚠️ FIX any deprecated actions FIRST - check deprecation_warnings!
+// FIX any deprecated actions FIRST - check deprecation_warnings!
 
-// 3. Deploy LLM's result (preview first!)
-workflow(mode="deploy", persona_id="abc", workflow_def={...}, preview=true)
-workflow(mode="deploy", persona_id="abc", workflow_def={...})
+// 3. Deploy LLM's result
+workflow(mode="deploy", persona_id="abc", base_fingerprint="...", workflow_def={...})
 ```
 
-### ⚠️ CRITICAL: Check Deprecated Actions First
+### CRITICAL: Check Deprecated Actions First
 
 **BEFORE generating any workflow:**
 
 1. Check `deprecation_warnings` in `workflow(mode="get")` response
-2. Use `reference(type="actions")` to verify current versions
+2. Use `catalog(method="list", type="actions")` to verify current versions
 3. **NEVER** copy workflow patterns from existing personas (they may use deprecated actions!)
 
 **Correct workflow pattern:**
 ```
-chat_trigger → search/v2 → respond_for_external_actions → WORKFLOW_OUTPUT
+chat_trigger -> search/v2 -> respond_for_external_actions -> WORKFLOW_OUTPUT
 ```
 
 **Deprecated (DO NOT USE):**
 ```
-search/v0 → Use search/v2
-respond_with_sources → Use respond_for_external_actions
-call_llm/v0 → Use call_llm/v2
+search/v0 -> Use search/v2
+respond_with_sources/v0 -> Use respond_for_external_actions
+call_llm/v0 -> Use call_llm/v2
 ```
 
 **Common issues to check when generating:**
@@ -508,17 +398,25 @@ call_llm/v0 → Use call_llm/v2
 
 **HITL is opt-in, not forced by default.**
 
+HITL is a **flag on specific action nodes**, not a standalone workflow node. Set `disable_human_interaction: false` on the node that needs approval.
+
 | Scenario | Default | How to Add HITL |
 |----------|---------|-----------------|
-| Send email | ❌ No HITL | Get workflow → add general_hitl node before email → deploy |
-| External API | ❌ No HITL | Get workflow → add general_hitl node → deploy |
-| Create records | ❌ No HITL | Get workflow → add general_hitl node → deploy |
+| Send email | No HITL | Set `disable_human_interaction: false` on `send_email_agent` node |
+| External API | No HITL | Set `disable_human_interaction: false` on `external_action_caller` node |
+| Create records | No HITL | Set `disable_human_interaction: false` on the action node |
+
+**Counter-intuitive naming:**
+- `disable_human_interaction: false` -> HITL **ON** (requires approval)
+- `disable_human_interaction: true` -> HITL **OFF** (auto-proceeds)
 
-**Pattern:** `workflow(mode="get")` → modify workflow_def → `workflow(mode="deploy")`
+**Pattern:** `workflow(mode="get")` -> modify workflow_def -> `workflow(mode="deploy")`
+
+> **Note:** Do NOT add standalone `general_hitl` nodes to new workflows. Use the flag pattern on the agent that performs the action instead.
 
 ## Auto Builder Prompt Length Limits
 
-**⚠️ CRITICAL:** Auto Builder has strict prompt length limits (~2500 chars).
+Auto Builder has strict prompt length limits (~2500 chars).
 
 ### Good Prompt Format
 ```text
@@ -530,8 +428,8 @@ Core Capabilities:
 3. Fallback - Handle unclear requests
 
 Rules:
-• Rule 1
-• Rule 2
+- Rule 1
+- Rule 2
 ```
 
 ### Bad Prompt Format (Times Out)
@@ -539,44 +437,15 @@ Rules:
 - Example conversations embedded in prompt
 - Prompts > 2500 characters
 
-## Deprecated Tools
-
-### `workflow` → use `persona`
-
-```typescript
-// OLD (deprecated)
-workflow(input="...", type="voice", name="Bot", preview=false)
-
-// NEW
-persona(input="...", type="voice", name="Bot", preview=false)
-```
-
-### `knowledge` → use `data`
+## Deprecated Tools (still work, route internally)
 
-```typescript
-// OLD (deprecated)
-knowledge(persona_id="abc", mode="list")
-knowledge(persona_id="abc", mode="upload", file="...")
-knowledge(persona_id="abc", mode="status")
-knowledge(persona_id="abc", mode="toggle", enabled=true)
+These tool names still work for backwards compatibility but are not exposed in the tool list. Use the current equivalents instead.
 
-// NEW
-data(persona_id="abc", mode="list")
-data(persona_id="abc", mode="upload", file="...")
-data(persona_id="abc", mode="embedding")
-data(persona_id="abc", mode="embedding", enabled=true)
-```
-
-### `demo` → use `data` + `persona`
-
-```typescript
-// OLD (deprecated)
-demo(mode="generate", entity="customer", data={...})
-demo(mode="scenarios")
-demo(mode="template", entity="customer")
-
-// NEW
-data(persona_id="abc", mode="generate", from="customer", data={...})
-data(mode="templates")
-data(mode="templates", template="customer")
-```
+| Deprecated Tool | Use Instead |
+|----------------|-------------|
+| `knowledge` | `persona(id=..., data={method:...})` |
+| `demo` | `persona` + data sub-resource |
+| `data` | `persona(id=..., data={method:...})` |
+| `action` | `catalog(method=..., type="actions")` |
+| `template` | `catalog(method=..., type="templates")` |
+| `reference` | `catalog(method=..., type=...)` |