@ema.co/mcp-toolkit 2026.1.25 → 2026.1.26-4

package/docs/release-impact.md

@@ -1,102 +0,0 @@
-# Release Impact Assessment
-
-## Two Versioning Contexts
-
-This repo has two audiences with different versioning needs:
-
-| Context | Versioned Via | Audience | What Changes Matter |
-|---------|---------------|----------|---------------------|
-| **npm package** | CalVer tags (`v2026.01.21`) | External MCP users | `src/*.ts`, `resources/`, `package.json` |
-| **Git repo** | Git commits | Internal developers | Everything, including `.cursor/`, `docs/` |
-
-### Cursor Rules: Out of Band
-
-`.cursor/` changes affect internal developer experience but NOT external npm users:
-- They're tracked in git history
-- No npm release needed
-- No version number changes
-- Developers pulling the repo get them automatically
-
-**If cursor rules change significantly**, consider noting in commit message or PR description.
-
----
-
-## Quick Reference
-
-| Change Type | Release Needed? | Version Bump |
-|-------------|-----------------|--------------|
-| `src/**/*.ts` (runtime code) | **Yes** | patch/minor/major |
-| `package.json` dependencies | **Yes** | patch |
-| `resources/**` (MCP resources) | **Yes** | patch |
-| `.cursor/**`, `docs/**`, `*.md` | No | - |
-| `test/**` | No | - |
-| `.github/**` | No | - |
-
-## Detailed Rules
-
-### Requires Release (affects npm package users)
-
-```
-src/**/*.ts          # Runtime TypeScript code
-package.json         # If dependencies change
-resources/**/*.json  # MCP static resources
-resources/**/*.md    # MCP resource content
-```
-
-### Does NOT Require Release
-
-```
-.cursor/**           # Cursor rules (local dev only)
-.github/**           # CI/CD workflows
-docs/**              # Documentation
-test/**              # Test files
-*.md (root)          # README, CLAUDE.md, AGENTS.md
-.ctx/**              # Agent coordination
-scripts/**           # Build/dev scripts (not runtime)
-```
-
-## Version Bump Guidelines
-
-| Change | Bump | Example |
-|--------|------|---------|
-| Breaking API change | Major | Tool renamed, param removed |
-| New feature | Minor | New tool, new mode |
-| Bug fix | Patch | Fix silent failure |
-| Docs only | None | Update README |
-| Internal refactor (no API change) | Patch | Restructure handlers |
-
-## Automated Assessment
-
-Run this to check if release is needed:
-
-```bash
-# Files changed since last release
-git diff --name-only $(git tag --sort=-v:refname | head -1)..HEAD
-
-# Check for release-requiring changes
-git diff --name-only $(git tag --sort=-v:refname | head -1)..HEAD | \
-  grep -E '^(src/.*\.ts|package\.json|resources/)' && \
-  echo "RELEASE NEEDED" || echo "No release needed"
-```
-
-## Pre-Release Checklist
-
-Before releasing, verify:
-
-- [ ] `npm run build` passes
-- [ ] `npm test` passes
-- [ ] No breaking changes without major bump
-- [ ] CHANGELOG updated (if maintaining one)
-- [ ] Version tag follows CalVer: `v2026.MM.DD[.N]`
-
-## CalVer Scheme
-
-This project uses Calendar Versioning:
-
-```
-v2026.01.21      # First release on Jan 21, 2026
-v2026.01.21.1    # Second release same day
-v2026.01.21.2    # Third release same day
-```
-
-No manual `package.json` version updates needed - CI generates from tag.

package/docs/release-process.md

@@ -1,157 +0,0 @@
-# Release Process
-
-## Lessons Learned (2026-01-16)
-
-The `feat/v1.5.0-intelligence-layer` branch was orphaned for weeks, containing 5,600+ lines of code that diverged significantly from main. This document establishes processes to prevent similar situations.
-
-## Branch Hygiene Rules
-
-### 1. No Long-Lived Feature Branches
-
-**Rule:** Feature branches should be merged or closed within **2 weeks**.
-
-**Why:** Long-lived branches diverge and become difficult to merge.
-
-**Process:**
-- If a feature takes longer than 2 weeks, break it into smaller PRs
-- If blocked, document why and set a reminder to revisit
-
-### 2. Pre-Branch Checklist
-
-Before creating a new feature branch:
-
-```bash
-# 1. Fetch latest and check for unmerged work
-git fetch origin
-git branch -r --no-merged main | grep -v HEAD
-
-# 2. If unmerged branches exist, decide:
-#    - Merge them first? OR
-#    - Explicitly abandon them?
-
-# 3. Start from latest main
-git checkout main
-git pull origin main
-git checkout -b feat/my-feature
-```
-
-### 3. Weekly Stale Branch Review
-
-Run weekly to identify abandoned branches:
-
-```bash
-# Show branches not merged to main, sorted by age
-git for-each-ref --sort=committerdate refs/remotes/origin \
-  --format='%(committerdate:short) %(refname:short)' | \
-  grep -v HEAD | grep -v main
-```
-
-### 4. Post-Merge Cleanup
-
-After merging a PR:
-
-```bash
-# Delete the remote branch
-git push origin --delete feat/my-feature
-
-# Delete local branch
-git branch -d feat/my-feature
-
-# Verify cleanup
-git remote prune origin
-```
-
-## Versioning: CalVer (Date-Based)
-
-We use **Calendar Versioning** (CalVer): `YYYY.MM.DD`
-
-| Format | Example | Notes |
-|--------|---------|-------|
-| Standard | `2026.01.17` | First release of the day |
-| Same-day | `2026.01.17.1` | Second release same day |
-| Same-day | `2026.01.17.2` | Third release same day |
-
-**No manual `package.json` updates needed!** The publish workflow auto-generates the version from the release tag.
-
-### Branch Naming Convention
-
-| Type | Pattern | Example |
-|------|---------|---------|
-| Feature | `feat/descriptive-name` | `feat/tool-consolidation-v2` |
-| Fix | `fix/descriptive-name` | `fix/fallback-detection` |
-| Chore | `chore/descriptive-name` | `chore/update-deps` |
-
-### Release Process (CalVer)
-
-1. **Check for unmerged work:**
-   ```bash
-   git branch -r --no-merged main
-   ```
-
-2. **Run full test suite:**
-   ```bash
-   npm run build && npm test
-   ```
-
-3. **Merge your PR to main**
-
-4. **Create a GitHub Release:**
-   - Go to GitHub → Releases → "Draft a new release"
-   - Create tag: `v2026.01.17` (use today's date)
-   - Write release notes
-   - Publish
-
-5. **The publish workflow automatically:**
-   - Updates `package.json` with the version from the tag
-   - Builds and tests
-   - Publishes to npm
-
-**For same-day releases:** Use `v2026.01.17.1`, `v2026.01.17.2`, etc.
-
-## Conflict Prevention
-
-### When Parallel Work Happens
-
-If two features are being developed in parallel:
-
-1. **Communicate:** Let the team know what you're working on
-2. **Small PRs:** Merge frequently to reduce divergence
-3. **Rebase often:** Keep feature branches up to date with main
-
-```bash
-# Rebase feature branch on latest main
-git fetch origin
-git rebase origin/main
-```
-
-### When Merging a Large Feature
-
-For large features (>500 lines):
-
-1. **Create a tracking issue** documenting what's being added
-2. **Break into reviewable chunks** (≤300 lines per PR)
-3. **Merge incrementally** rather than one giant PR
-
-## Automation (Future)
-
-Consider adding GitHub Actions for:
-
-1. **Stale branch alerts:** Weekly notification of branches >14 days old
-2. **PR size warnings:** Flag PRs with >500 lines changed
-3. **Unmerged branch check:** CI fails if important branches are unmerged before release
-
-## Quick Reference
-
-```bash
-# Check for unmerged branches
-git branch -r --no-merged main | grep -v HEAD
-
-# Compare branch to main
-git log main..origin/feat/branch-name --oneline
-git diff --stat main...origin/feat/branch-name
-
-# Clean up after merge
-git push origin --delete feat/branch-name
-git branch -d feat/branch-name
-git remote prune origin
-```

package/docs/staging.RULE.md

@@ -1,142 +0,0 @@
----
-description: "Guide for using Ema MCP tools - 7 active tools with explicit mode"
-alwaysApply: true
-globs: ["src/mcp/**", "src/sdk/**"]
----
-
-# Ema MCP Client Guide
-
-## Tool Overview: 7 Active Tools
-
-| Tool | Purpose | Mode Required? |
-|------|---------|----------------|
-| `env` | List environments | No (single operation) |
-| `persona` | Manage AI Employees | **YES** |
-| `data` | Manage data + generation | **YES** |
-| `action` | Actions lookup | No (flag-based) |
-| `template` | Patterns & questions | No (flag-based) |
-| `reference` | Platform concepts | No (flag-based) |
-| `sync` | Environment sync | **YES** |
-
-**Deprecated tools** (still work, but use new ones):
-- `workflow` → use `persona` instead
-- `knowledge` → use `data` instead
-- `demo` → use `data` + `persona` instead
-
-## Primary Tool: `persona`
-
-Everything for AI Employee management is in the `persona` tool. **Explicit mode required.**
-
-### `persona` Tool Modes
-
-```
-persona(mode="list")                                     // List all
-persona(mode="get", id="abc-123")                        // Get specific
-persona(mode="get", id="abc-123", include_workflow=true) // Get with workflow
-
-persona(mode="create", from="Voice AI Starter", name="My SDR", input="...", preview=false)
-persona(mode="create", type="voice", name="My SDR", input="...", preview=false)
-
-persona(mode="update", id="abc-123", proto_config={...}) // Update config
-persona(mode="clone", from="source-id", name="My Copy", include_data=true)
-persona(mode="compare", id="abc-123", compare_to="def-456")
-persona(mode="sanitize", id="abc-123")
-persona(mode="analyze", id="abc-123")                     // Show issues
-persona(mode="analyze", id="abc-123", fix=true)           // Auto-fix issues
-persona(mode="templates")                                 // List templates
-```
-
-## Explicit Mode Pattern
-
-Tools with multiple operations require **explicit `mode`**. If omitted, the tool will **clarify** what operation you want - it won't guess.
-
-### `data` Tool Modes
-
-```
-data(persona_id="abc", mode="list")                         // List files
-data(persona_id="abc", mode="get", file_id="...")           // Get specific file
-data(persona_id="abc", mode="upload", file="/path")         // Upload file
-data(persona_id="abc", mode="generate", input="...")        // Generate from NL
-data(persona_id="abc", mode="generate", from="customer", count=5)  // From template
-data(persona_id="abc", mode="delete", file_id="...")        // Delete file
-data(persona_id="abc", mode="sanitize")                     // Sanitize PII
-data(persona_id="abc", mode="embedding")                    // Embedding status
-data(persona_id="abc", mode="embedding", enabled=true)      // Toggle embedding
-data(mode="templates")                                       // List templates
-data(mode="templates", template="customer")                  // Get template details
-```
-
-### `sync` Tool Modes
-
-```
-sync(id="...", target="dev", mode="run")    // Sync persona to target
-sync(all=true, target="dev", mode="run")    // Sync all tagged
-sync(id="...", mode="status")               // Get sync status
-sync(mode="config")                         // Get sync config
-```
-
-## Document Generation
-
-Generate content via the Ema Document Generation API:
-
-```
-// From a template
-data(persona_id="abc", mode="generate", from="customer", count=5)
-data(persona_id="abc", mode="generate", from="demo-sales-sdr")
-
-// From natural language
-data(persona_id="abc", mode="generate", input="Generate 5 B2B customer profiles for SaaS")
-
-// List available templates
-data(mode="templates")
-```
-
-**Available templates:**
-- Reference: `countries`, `industries`, `currencies`
-- Demo kits: `demo-sales-sdr`, `demo-support`, `demo-hr`
-- Entities: `customer`, `product`, `faq`, `employee`
-
-## Clarification Behavior
-
-If you call `persona()`, `data()`, or `sync()` without explicit mode, you get a clarification response:
-
-```json
-{
-  "status": "clarification_needed",
-  "message": "What operation would you like to perform?",
-  "options": ["list", "get", "create", "update", ...],
-  "hint": "Specify mode='...' for direct execution"
-}
-```
-
-This prevents unintended operations (e.g., silent no-ops) and ensures explicit user intent.
-
-## Key Rules
-
-1. **ONE CALL** - Put everything in `input`, explicit `name`, let MCP handle the rest
-2. **EXPLICIT MODE** - For `data` and `sync`, always specify `mode`
-3. **STOP after success** - Don't make follow-up "fix" calls
-4. **preview=false** - Required to actually deploy (default is preview)
-
-## Migration from Deprecated Tools
-
-| Old | New |
-|-----|-----|
-| `workflow(input="...")` | `persona(input="...")` |
-| `knowledge(mode="list")` | `data(mode="list")` |
-| `knowledge(mode="upload")` | `data(mode="upload")` |
-| `knowledge(mode="status")` | `data(mode="embedding")` |
-| `knowledge(mode="toggle")` | `data(mode="embedding", enabled=...)` |
-| `demo(mode="generate")` | `data(mode="generate", from="...")` |
-| `demo(mode="scenarios")` | `data(mode="templates")` |
-| `demo(mode="template")` | `data(mode="templates", template="...")` |
-
-## Anti-Patterns
-
-```
-❌ Making multiple calls to create one AI Employee
-❌ Omitting `name` parameter for new personas  
-❌ Using deprecated tools (workflow, knowledge, demo)
-❌ Calling data() without mode and expecting it to guess
-❌ preview=true then complaining it didn't deploy
-```

package/docs/test-persona-creation.md

@@ -1,196 +0,0 @@
-# Persona Creation Test Guide
-
-This guide tests the workflow tool's ability to create and configure AI Employees (personas).
-
-## Architecture
-
-### Greenfield (New Personas)
-1. **Create** persona from template (provides valid workflow structure)
-2. **Fetch** the created persona (get template's structure)
-3. **Update** proto_config only (voice settings, welcome message, etc.)
-4. **Customize workflow later** via modify mode if needed
-
-### Brownfield (Existing Personas)
-1. **Fetch** existing persona and workflow
-2. **Decompile** workflow_def → WorkflowSpec (typed representation)
-3. **Transform** spec based on user intent (LLM-native)
-4. **Compile** back to workflow_def
-5. **Update** persona with transformed workflow
-
-## Prerequisites
-
-1. **Rebuild the code**: 
-   ```bash
-   cd /path/to/ema-mcp-toolkit
-   npm run build
-   ```
-
-2. **Restart the MCP server** (Cursor caches code):
-   - `Cmd+Shift+P` → "Developer: Reload Window"
-
-3. Access to Ema dev environment
-
----
-
-## Test Cases
-
-### Test 1: Create Voice AI Employee (Greenfield)
-
-**Goal:** Create a new Voice AI persona from template with configured settings.
-
-**Command:**
-```
-workflow(
-  input="Voice AI sales development representative for Ema. Handles discovery calls, qualifies prospects, explains value propositions.",
-  name="SP-TEST-VOICE-GREENFIELD",
-  type="voice",
-  preview=false,
-  env="dev"
-)
-```
-
-**Expected Result:**
-- `status: "deployed"`
-- `deployed_to.created: true`
-- `deployed_to.persona_id` returned
-- `next_steps` explains how to customize workflow
-
-**Verify:**
-```
-persona(id="<persona_id>", include_workflow=true, env="dev")
-```
-
-**Check:**
-- [ ] Persona exists with correct name
-- [ ] `proto_config.widgets` contains `conversationSettings` with:
-  - [ ] `welcomeMessage` - generated greeting
-  - [ ] `identityAndPurpose` - from description
-- [ ] `workflow_def` has template workflow (trigger node + possibly more from template)
-
----
-
-### Test 2: Create Chat AI Employee (Greenfield)
-
-**Command:**
-```
-workflow(
-  input="IT helpdesk chatbot that answers employee questions about password resets, VPN setup, and software installation.",
-  name="SP-TEST-CHAT-GREENFIELD",
-  type="chat",
-  preview=false,
-  env="dev"
-)
-```
-
-**Expected Result:**
-- `status: "deployed"`
-- `deployed_to.created: true`
-
-**Verify:**
-```
-persona(id="<persona_id>", include_workflow=true, env="dev")
-```
-
----
-
-### Test 3: Modify Existing Workflow (Brownfield)
-
-**Prerequisites:** Create a persona first (Test 1 or 2).
-
-**Goal:** Add functionality to an existing persona's workflow.
-
-**Command:**
-```
-workflow(
-  persona_id="<persona_id_from_test_1>",
-  input="add a search node that queries the knowledge base before responding",
-  preview=true,
-  env="dev"
-)
-```
-
-**Expected Result:**
-- `mode: "modify"`
-- Shows proposed changes
-- `modified_workflow` with new nodes
-
-**Deploy the changes:**
-```
-workflow(
-  persona_id="<persona_id>",
-  input="add a search node that queries the knowledge base before responding",
-  preview=false,
-  env="dev"
-)
-```
-
----
-
-### Test 4: Analyze Workflow
-
-**Command:**
-```
-workflow(persona_id="<persona_id>", env="dev")
-```
-
-**Expected Result:**
-- `mode: "analyze"`
-- `issues` array (may be empty if healthy)
-- `metrics` with node_count, edge_count
-
----
-
-### Test 5: Preview Only (No Deploy)
-
-**Goal:** Verify preview mode returns workflow without deploying.
-
-**Command:**
-```
-workflow(
-  input="Customer support voice AI that handles billing inquiries",
-  type="voice"
-)
-```
-
-**Expected Result:**
-- `status: "preview"`
-- `workflow_def` returned
-- `proto_config` with voice settings populated
-- NO persona created
-
----
-
-## Cleanup
-
-After testing, delete test personas via the Ema UI or leave them for inspection.
-
-Test persona names:
-- SP-TEST-VOICE-GREENFIELD
-- SP-TEST-CHAT-GREENFIELD
-
----
-
-## Troubleshooting
-
-### "Internal Server Error"
-- Usually means workflow format is wrong
-- Check if MCP server has latest code (restart Cursor)
-
-### "Widget name is empty"
-- Old code issue - restart MCP server
-
-### "Workflow name does not match"
-- Old code tried to replace workflow - now we don't touch workflow in greenfield
-
-### proto_config not updated
-- Check that greenfield flow only updates proto_config, not workflow
-- Widget merging should preserve template structure
-
----
-
-## Key Code Locations
-
-- **Greenfield flow**: `src/mcp/handlers-consolidated.ts` (search for "GREENFIELD")
-- **Brownfield/modify flow**: `src/mcp/handlers-consolidated.ts` (search for "modify")
-- **Workflow transformer**: `src/sdk/workflow-transformer.ts` (decompile/compile)
-- **Proto config generation**: `src/sdk/workflow-generator.ts` (buildProtoConfig)