Welcome to Vodou - Your Complete Help Center 🚀

⚠️ CRITICAL: AI Agent Instructions

This skill is Vodou's primary help center and user guide. When users ask for help, information, or guidance about Vodou, you MUST:

1. Load this skill first when users ask:
   • "what is oi"
   • "how does oi work"
   • "help with oi"
   • "oi help"
   • "hello"
   • Any question about Vodou functionality
2. MANDATORY: Display the overview and content BEFORE the stopping point
   • ALWAYS present the complete "What is Vodou? - Complete Overview" section (lines 62-146) to users FIRST
   • This includes: The Big Picture, Triple-Layer Intelligence System, What Makes Vodou Unique, Real-World Performance, How Vodou Works, Key Benefits, and What You Can Do with Vodou
   • DO NOT skip directly to the stopping point menu
   • Users need the foundation before choosing what to learn more about
3. THEN display the stopping point menu - After showing the overview content, present "STOPPING POINT 1" with the complete numbered menu (1-9) with all options. DO NOT summarize or skip this menu!
4. Use stopping points to guide users to detailed information based on their needs
5. Reference supporting documents in references/ and assets/ directories for detailed information
6. Follow the progressive disclosure pattern - start broad, go deep on demand

🤖 For AI Agents: Available Skills & Learning Resources

Important Skills Available:

• hello (this skill) - Primary help center and user guide
• mastery - CRITICAL FOR AI AGENTS: Advanced Vodou techniques with BYPASS MODE for quick learning
  • BYPASS MODE: When you need to learn Vodou mastery for your own knowledge, read all 10 reference/asset files immediately (bypass stopping points)
  • Location: skills/vodou-core/mastery/
  • Command: ./do "oi mastery" or ./do "mastery"
  • For AI Learning: Load mastery skill and read all files in references/ and assets/ directories for complete knowledge
  • For Users: Present mastery with progressive disclosure and stopping points

This skill contains the authoritative information about Vodou. Use it as your primary reference.

📖 What is Vodou? - Complete Overview

The Big Picture

Vodou is a revolutionary platform that transforms AI agents from sequential tool users into intelligent workflow orchestrators. It's the world's first Universal Intelligence Orchestrator with a Triple-Layer Intelligence System:

The Triple-Layer Intelligence System

🧠 Layer 1: Expert Workflow Intelligence (Skills)

• Skills system provides curated knowledge and proven patterns
• Interactive guidance with stopping points for user control
• Best practices built-in for every workflow
• 29+ skills for expert guidance from Vodou help to security audits

⚡ Layer 2: Parallel Intelligence Orchestration (MCP Tools)

• Execute 5-10 MCP tools simultaneously in 3-5 seconds
• Automatic result correlation and context sharing
• 3-7x faster than sequential execution (15-30 seconds vs 3-5 seconds)
• Connect to ANY MCP server (1000+ tools available)

🔧 Layer 3: Background Script Execution (Automation)

• Execute long-running scripts with background job management
• Real-time status monitoring and output streaming
• Process control with unique job IDs and cancellation
• Sync/async execution with npm/yarn integration

What Makes Vodou Unique

No other platform combines all three layers with full customization:

• Traditional tools: Sequential only, limited access, no background execution, no customization
• Other MCP platforms: Limited tool access, no expert guidance, no script management, limited customization
• Generic AI: No parallel execution, no expert workflows, no automation layer, no customization

Vodou = Expert Intelligence + Parallel Speed + Background Automation + Infinite Extensibility + Full Customization

Every layer is customizable:

• Skills: Create custom expert workflows for your domain
• MCP Tools: Connect to any tool, API, or service
• Scripts: Automate any process with job management
• Intents: Create natural language shortcuts for your workflows

Fully Customizable - All Three Layers

Every layer of Vodou is fully customizable to fit your needs:

🧠 Layer 1: Custom Skills

• Create your own skills with expert workflows tailored to your domain
• Custom stopping points for your specific decision points
• Domain-specific guidance for your industry, tools, or processes
• Share skills with your team or community
• Example: ./do "create oi skill" - Build custom skills for your workflows

⚡ Layer 2: Custom MCP Servers & Intents

• Install ANY MCP server from GitHub, npm, pip, or custom builds
• Create custom intent mappings to route your keywords to any tool
• Connect to your tools - databases, APIs, cloud services, internal systems
• Parallel execution works with any MCP-compatible tool
• Example: ./do "install https://github.com/user/custom-mcp-server" - Add new capabilities instantly

🔧 Layer 3: Custom Scripts & Jobs

• Register custom scripts for your specific automation needs
• Background job management for any long-running process
• Custom job monitoring with real-time output streaming
• Process control for any script or command
• Example: ./do "run script" - Execute your custom automation scripts

The Power of Customization:

• Skills: Build expert workflows for your specific domain
• MCP Tools: Connect to any tool, API, or service that speaks MCP
• Scripts: Automate any process with full job management
• Intents: Create natural language shortcuts for your workflows
• All layers work together - Custom skills can orchestrate custom MCP tools and scripts

Vodou adapts to YOU - not the other way around.

Real-World Performance

Traditional Sequential Approach:

# Step 1: Check CPU (3 seconds)
# Step 2: Check memory (3 seconds)  
# Step 3: Check disk (3 seconds)
# Step 4: Analyze code (5 seconds)
# Total: 14+ seconds + manual correlation

Vodou Parallel Approach:

./do "cpu memory disk network"
# All execute simultaneously
# Total: 4 seconds + automatic correlation
# Result: 3.5x faster with comprehensive analysis

How Vodou Works

1. You ask in natural language: ./do "cpu memory disk"
2. Vodou detects your intent and finds the right tools
3. Vodou executes multiple tools in parallel
4. Vodou correlates results automatically
5. You get comprehensive results in seconds

Key Benefits

• 🚀 Speed: 3-7x faster than sequential execution
• 🧠 Intelligence: Expert guidance through skills
• 🌐 Extensibility: Access to 1000+ tools
• 💰 Efficiency: 90% token reduction, 85% cost savings
• 🎯 Control: You stay in control with stopping points
• 🔧 Customization: Fully customizable - create custom skills, connect custom MCP servers, automate custom scripts

What You Can Do with Vodou

• System Monitoring: ./do "cpu memory disk network" (parallel execution)
• Script Execution: ./do "run script" (background job management)
• Code Analysis: ./do "deep think about my codebase structure" (enhanced AI thinking)
• Web Auditing: ./do "run seo audit on my website" (browser automation)
• Development Workflows: ./do "implement feature with testing" (skills orchestration)
• Browser Automation: ./do "take screenshot of website" (MCP tools)
• Deep Thinking: ./do "deep think about database optimization" (persistent thinking)
• Job Monitoring: ./do "script status job_12345" (background process tracking)
• Session Management: Long-running operations with persistent MCP server sessions
• Multi-Step Workflows: Complex operations that span multiple tool calls with session persistence

And much more! Vodou connects to 10 specialized MCP servers with 60+ tools, 24 expert skills, plus script execution and session management. All three layers are fully customizable - create your own skills, connect your own MCP servers, and automate your own scripts.

🎯 STOPPING POINT 1: What Would You Like to Learn More About?

Now that you understand what Vodou is, what would you like to explore in detail?

Choose a topic:

1. ⚡ Quick Start Guide - Get up and running in 5 minutes: installation, setup, and your first commands
2. 🔌 MCP Servers Deep Dive - Learn everything about MCP servers: what they are, how they work, how to use them, and how to install new ones
3. 🎓 Skills System Guide - Understand Vodou's skills system: what skills are, how they work, and how to create your own
4. 🔧 Scripts & Background Jobs - Learn about script execution, background job management, and how to register and use scripts
5. 🛠️ Advanced Topics - Master orchestration, parallel execution, custom workflows, and power user techniques
6. ❓ Troubleshooting - Solve common problems, errors, and issues
7. 📊 Architecture & Examples - See how Vodou works under the hood and real-world workflow examples
8. 🎯 Intents & Natural Language - Learn about intent mappings, how to create custom intents, and natural language routing for both MCP servers and Skills
9. 📚 All Reference Guides - Access all detailed documentation and guides

Please tell me which number (1-9) interests you, or say "all" for everything!

⚡ Section 1: Quick Start - Get Running Fast

Quick Summary

Get Vodou up and running in 5 minutes:

1. Install: ./install.sh
2. Configure: Set up your .env file with Vodou credentials from app.vodou.ai
3. Start: ./start-vodou-services.sh
4. Get Started: ./do "hello" (Vodou help center - recommended first command!)
5. Test Parallel: ./do "cpu memory disk" (parallel execution!)
6. Test Script Execution: ./do "run script" (background job management!)

⏸️ STOPPING POINT: Would you like the detailed quick start guide?

If yes, I'll provide:

• Step-by-step installation
• Configuration details
• First commands
• Common first-time issues

Say "yes" for detailed quick start, or choose another topic (1-9).

See also: references/quick-start.md for complete step-by-step guide

🔌 Section 2: MCP Servers - The Foundation

Quick Summary

MCP (Model Context Protocol) is a standardized way for AI agents to interact with tools. MCP Servers are programs that provide specific capabilities (like system monitoring, code analysis, browser automation).

Key Points:

• Vodou connects to 10 specialized MCP servers automatically
• Each server provides specialized tools
• You use them through natural language: ./do "cpu memory disk"
• Vodou executes multiple tools in parallel automatically

Your Connected MCP Servers in Vodou

System Monitoring & Performance:

• mcp-monitor: CPU, memory, disk, network monitoring (6 tools)

AI Enhancement & Thinking:

• Vodou-Enhanced-Thinking: Persistent thinking sessions with context enrichment (6 tools)
• Vodou-Sequential-Thinking: Step-by-step problem solving with branching (1 powerful tool) Development & Documentation:
• context7: Real-time library documentation & code examples (2 tools)
• uml-mcp: Diagram generation (UML, Mermaid, D2) (1 tool)
• browser-tools-stdio: Browser automation & web auditing (14 tools)

Vodou Core Infrastructure:

• vodou-core (built-in skills): Skills system engine (3 tools)
• Vodou-script-executor: Background script execution & job management (4 tools)
  • execute_script: Run registered scripts (sync or background)
  • script_status: Monitor background job status and progress
  • script_output: View live script output (real-time tail)
  • cancel_script: Stop running background scripts with process control
• Vodou-session-manager: Long-running session management (5 tools)

⏸️ STOPPING POINT: Would you like to learn more about MCP servers?

If yes, I'll provide:

• Complete guide to MCP servers
• How to use them effectively
• How to install new servers
• Development guide

Say "yes" for detailed MCP servers guide, or choose another topic (1-9).

See also: references/mcp-servers-guide.md for complete reference

Detailed MCP Server Capabilities

1. mcp-monitor - Your system health dashboard

• Monitor CPU, memory, disk usage in real-time
• Track network interfaces and traffic
• Get detailed process information
• Essential for performance troubleshooting

2. Vodou-Enhanced-Thinking - AI thinking persistence

• Create thinking sessions that persist across conversations
• Analyze thinking quality with gap detection
• Add thoughts incrementally with full context
• Perfect for complex problem-solving

3. Vodou-Sequential-Thinking - Structured reasoning

• Break down complex problems step-by-step
• Branch and revise thinking paths
• Generate and verify hypotheses
• Ideal for planning and design tasks

4. context7 - Always-current documentation

• Get up-to-date library documentation
• Access version-specific code examples
• Prevents outdated AI responses
• Supports all major frameworks

5. uml-mcp - Visual diagram generation

• Create UML, sequence, class diagrams
• Generate Mermaid and D2 diagrams
• Multiple output formats (PNG, SVG, PDF)
• Interactive playground links

6. browser-tools-stdio - Web automation suite

• Take screenshots of any website
• Run Lighthouse audits (SEO, performance, accessibility)
• Check console logs and network errors
• Debug web applications

7. vodou-core (built-in skills) - Skills engine

• Powers Vodou's entire skills system
• Lists, loads, and searches skills
• Core infrastructure component

8. Vodou-script-executor - Background script execution & job management

• Background Job Management: Execute scripts independently with unique job IDs
• Real-time Monitoring: Track job status, progress, and elapsed time
• Live Output Streaming: View script output in real-time with configurable tail
• Process Control: Cancel running jobs with graceful termination (SIGTERM→SIGKILL)
• Sync/Async Execution: Automatic background detection based on script duration
• npm/yarn Integration: Execute package scripts with full job management
• Environment Loading: Automatic .env file loading for script execution
• Database Tracking: Persistent job history with completion status and exit codes

9. Vodou-session-manager - Long-running session management & orchestration

• Session Creation: Create persistent MCP server sessions for long-running operations
• Process Management: Spawn and manage detached MCP processes with HTTP/SSE transport
• Session Reuse: Automatically reuse existing sessions for efficiency and resource optimization
• Persistent Operations: Keep MCP servers alive across multiple tool calls for complex workflows
• Resource Cleanup: Automatic cleanup of idle sessions, processes, and connections
• Database Tracking: Persistent session history, call logging, and performance monitoring
• Lifecycle Management: Session timeouts, expiration handling, and graceful shutdown
• Multi-Server Support: Manage sessions across multiple MCP servers simultaneously

🎓 Section 3: Skills - The Intelligence Layer

Quick Summary

Skills are expert guides that teach AI agents (and you) how to accomplish tasks effectively. They're like having a senior developer available 24/7.

Key Points:

• Skills provide step-by-step guidance
• They include best practices and proven patterns
• They can ask questions and adapt to your needs
• Skills are checked FIRST before other operations

Built-in Vodou Skills (24 Skills Available)

Core Skills:

• hello: This help center (you're here!)
• mastery: Advanced Vodou techniques - Parallel execution, orchestration, intent management, work logging, and more
  • 🤖 AI Agent Note: mastery has a BYPASS MODE - when you need to learn Vodou mastery for your own knowledge, read all 10 reference/asset files immediately (see AI Agent Instructions above)
  • Command: ./do "oi mastery" or ./do "mastery"
• skill-development: Guide to creating skills
• mcp-installer: Installing MCP servers
• mcp-builder: Build custom MCP servers

Development & Code Quality:

• code-review: Expert code review workflows
• qa-testing: QA testing best practices
• project-wizard: Project setup and configuration
• parallel-code-analysis: Parallel code analysis patterns
• tdd-workflow: Test-driven development workflows
• systematic-debugging: Systematic debugging approaches

Thinking & Analysis:

• deep-thinking: Deep thinking and analysis workflows
• implementation-planning: Implementation planning guidance

Browser & Documentation:

• browser-tools: Browser automation workflows
• context7-docs: Documentation and context management

Memory & Learning:

• self-learning: Self-learning capabilities

Utilities:

• user-flow-control: User flow control patterns
• flow-demo: Flow demonstration examples
• installation-test-kit: Installation testing
• uml-diagram: UML diagram generation
• docker-compose-dev: Docker compose development workflows

⏸️ STOPPING POINT: Would you like to learn more about skills?

If yes, I'll provide:

• Complete guide to skills
• How skills work
• How to create your own skills
• Best practices

Say "yes" for detailed skills guide, or choose another topic (1-9).

See also: references/skills-guide.md for complete reference

🔧 Section 4: Scripts & Background Jobs

Quick Summary

Scripts are registered commands that can be executed through Vodou's script execution system. They support both synchronous and background execution with full job tracking, status monitoring, and output capture.

Key Points:

• Scripts are registered in the script_registry database table
• Can execute synchronously (quick tasks) or in background (long-running)
• Full job tracking with unique job IDs
• Real-time status monitoring and output streaming
• Process control with cancellation support
• Works with npm/yarn scripts, shell commands, and custom scripts

Vodou Script Executor

Vodou-script-executor is the MCP server that powers script execution:

Core Tools:

• execute_script: Run registered scripts (sync or background)
• script_status: Monitor background job status and progress
• script_output: View live script output (real-time tail)
• cancel_script: Stop running background scripts with process control

Key Features:

• Automatic Background Detection: Scripts with background_execution=true or estimated duration > 300 seconds run in background
• Job Tracking: Unique job IDs for each execution, tracked in script_jobs table
• Output Capture: Separate stdout and stderr log files for background jobs
• Real-time Monitoring: Check status and view output while scripts run
• Process Control: Cancel running jobs with graceful termination (SIGTERM → SIGKILL)
• Environment Loading: Automatic .env file loading for script execution
• Database Persistence: Job history persists across Vodou restarts

Using Scripts

Execute a Script:

# Natural language (via intent) — must match a script intent keyword you registered
./do "nightly backup"
./do "run script"

# Direct MCP call
./vodou-core call Vodou-script-executor execute_script '{
  "server_name": "my-project",
  "script_name": "backup"
}'

Monitor Background Jobs:

# Check job status
./do "script status job_12345"
./vodou-core call Vodou-script-executor script_status '{"job_id": "job_12345"}'

# View live output
./do "script output job_12345"
./vodou-core call Vodou-script-executor script_output '{"job_id": "job_12345", "tail_lines": 100}'

# Cancel running job
./do "cancel script job_12345"
./vodou-core call Vodou-script-executor cancel_script '{"job_id": "job_12345"}'

Script Execution Modes

Synchronous Execution:

• Scripts without background_execution flag
• Scripts with estimated duration < 300 seconds
• Returns output immediately
• Blocks until completion
• Best for quick operations

Background Execution:

• Scripts with background_execution=true
• Scripts with estimated duration > 300 seconds
• Returns job ID immediately
• Runs independently in background
• Best for long-running operations

Script Registration

Scripts are registered in the script_registry table:

INSERT INTO script_registry (
  server_name,
  script_name,
  command,
  working_directory,
  background_execution,
  estimated_duration,
  description
) VALUES (
  'my-project',
  'backup',
  './scripts/backup.sh',
  '/path/to/project',
  1,
  600,
  'Nightly backup script'
);

Intent Mappings for Scripts

Scripts can be mapped to natural language keywords:

INSERT INTO intent_mappings (
  intent_keyword,
  server_name,
  tool_name,
  priority
) VALUES (
  'nightly backup',
  'Vodou-script-executor',
  'execute_script',
  10
);

Then use via natural language:

./do "nightly backup"

Common Script Use Cases

1. Long-running / scheduled scripts:

./do "nightly backup"
# Check status: ./do "script status job_12345"

2. Build Tasks:

./do "run build script"
# Executes npm/yarn build scripts
# Can run in background for long builds

3. Data Processing:

./do "process data"
# Long-running data processing scripts
# Monitor progress with script_status

4. Testing:

./do "run tests"
# Execute test suites
# Background execution for comprehensive tests

Job Management

Job Status States:

• running: Script is currently executing
• completed: Script finished successfully
• failed: Script exited with error
• cancelled: Script was cancelled by user

Job Information:

• Job ID (unique identifier)
• Server name and script name
• Status and exit code
• Start time and elapsed time
• Output file paths (stdout/stderr)
• Process ID (PID)

⏸️ STOPPING POINT: Would you like to learn more about scripts?

If yes, I'll provide:

• Complete guide to script execution
• How to register scripts
• Background job management
• Best practices

Say "yes" for detailed scripts guide, or choose another topic (1-9).

See also: references/scripts-guide.md for complete reference

🛠️ Section 5: Advanced Topics

Quick Summary

Advanced Vodou capabilities:

• Parallel Execution: Run multiple tools simultaneously (3-7x faster)
• Workflow Orchestration: Tools direct what executes next
• Intent Mappings: Create custom shortcuts
• Work Logging: Track your work with metadata

🤖 AI Agent Note: The mastery skill contains complete advanced documentation with BYPASS MODE for AI agent learning. When you need to learn Vodou mastery for your own knowledge, load mastery and read all 10 reference/asset files immediately (bypass stopping points).

⏸️ STOPPING POINT: Would you like to learn advanced techniques?

If yes, I'll provide:

• Parallel execution best practices
• Orchestration patterns
• Custom intent mappings
• Work logging guide

Say "yes" for advanced topics, or choose another topic (1-9).

See also: ./do "oi mastery" for comprehensive advanced guide

❓ Section 6: Troubleshooting

Quick Summary

Common problems and quick fixes:

• "Command not found": Check you're in Vodou directory, verify script exists
• "Failed to connect": Restart services, check credentials, verify Docker
• "Timeout errors": Use background execution, break into smaller parts
• "No such tool": Check ./do list, install missing servers

⏸️ STOPPING POINT: Are you experiencing a problem?

If yes, I'll help you:

• Diagnose the issue
• Provide specific solutions
• Guide you through fixes

Say "yes" for troubleshooting help, or choose another topic (1-9).

See also: references/troubleshooting.md for complete troubleshooting guide

📊 Section 7: Architecture & Examples

Quick Summary

How Vodou works:

• User query → Intent detection → Tool selection → Parallel execution → Results
• Supports stdio, HTTP, WebSocket, SSE protocols
• Database stores configurations, intent mappings, work logs

Real-world examples:

• System monitoring: 3-4 seconds for 4 tools (vs 12+ seconds sequential)
• Code analysis: 5-8 seconds comprehensive (vs 15+ minutes manual)
• Security audit: 2-3 minutes complete (vs 30+ minutes manual)

⏸️ STOPPING POINT: Would you like to see architecture details and examples?

If yes, I'll provide:

• System architecture diagrams
• Data flow explanations
• Real-world workflow examples
• Performance comparisons

Say "yes" for architecture & examples, or choose another topic (1-9).

See also:

• assets/architecture-diagram.md for architecture
• assets/workflow-examples.md for examples

🎯 Section 8: Intents - Natural Language Routing

Quick Summary

Intents are natural language keywords that map to MCP server tools, Skills, OR Scripts. They let you use simple phrases like "cpu", "hello", or "run script" instead of remembering server/tool names, skill names, or script commands.

Key Points:

• Intents map keywords to server::tool combinations (MCP servers)
• Intents can also map keywords to vodou-core::vc_load_skill (Skills)
• Intents can also map keywords to Vodou-script-executor::execute_script (Scripts)
• Vodou automatically detects intents in your queries
• You can create custom intents for your workflows
• Priority system determines which intent is used when multiple match

How Intents Work

1. Intent Detection

• When you type ./do "cpu", Vodou looks up "cpu" in the intent database
• Finds mapping: cpu → mcp-monitor::get_cpu_info (MCP server tool)
• Executes the tool automatically
• When you type ./do "hello", Vodou looks up "hello" in the intent database
• Finds mapping: hello → vodou-core::vc_load_skill with skill_name: "hello" (Skill)
• Loads the skill automatically

2. Three Types of Intents

MCP Server Intents:

• Map to specific tools: keyword → server::tool
• Example: cpu → mcp-monitor::get_cpu_info
• Execute tools directly

Skill Intents:

• Map to skills: keyword → vodou-core::vc_load_skill
• Include skill_name in tool_parameters
• Example: hello → vodou-core::vc_load_skill with {"skill_name": "hello"}
• Load expert guidance and workflows

Script Intents:

• Map to scripts: keyword → Vodou-script-executor::execute_script
• Include server_name and script_name in tool_parameters
• Example: nightly backup → Vodou-script-executor::execute_script with {"server_name": "my-project", "script_name": "backup"}
• Execute registered scripts (sync or background)

3. Natural Language

• Use simple keywords instead of complex commands
• Vodou handles the routing automatically
• Multiple intents can execute in parallel

4. Priority System

• Higher priority intents are preferred when multiple match
• Default priority is 1, common intents use 10
• You can set custom priorities

Viewing Existing Intents

List all intents:

# Natural language (recommended)
./do "show me all intent mappings"

# CLI command
sqlite3 vodou-core.db "SELECT keyword, server_name, tool_name, priority FROM intent_mappings ORDER BY priority DESC;"

Filter by category:

./do "show me intent mappings for docker"
./do "show me intent mappings for browser"
./do "show me intent mappings for system"

View specific intent:

sqlite3 vodou-core.db "SELECT keyword, server_name, tool_name, priority FROM intent_mappings WHERE keyword LIKE '%cpu%';"

Test an intent:

./vodou-core intent-signal "check my cpu usage"

Creating New Intents

For MCP Server Tools:

Natural Language Method (Recommended):

# Format: keyword → MCP-server-name::tool-name priority X
./do "add intent mapping: keyword → server::tool priority X"

Format Breakdown:

Visual Example:

./do "add intent mapping: health → mcp-monitor::get_cpu_info priority 15"
                          ^^^^^^   ^^^^^^^^^^^  ^^^^^^^^^^^^  ^^^^^^^^^^
                          keyword  MCP server   tool name     priority

Examples:

# Add MCP server tool intent
./do "add intent mapping: performance → mcp-monitor::get_cpu_info priority 10"

# Add with different priority
./do "add intent mapping: speed → mcp-monitor::get_cpu_info priority 5"

# Add for custom workflow
./do "add intent mapping: morning-routine → mcp-monitor::get_host_info priority 15"

CLI Method:

sqlite3 vodou-core.db "INSERT INTO intent_mappings (keyword, server_name, tool_name, priority) VALUES (<keyword>, <server>, <tool>, '[priority]');"

Example:

sqlite3 vodou-core.db "INSERT INTO intent_mappings (keyword, server_name, tool_name, priority) VALUES ("backup", "filesystem", "backup_files", '10');"

For Skills:

Natural Language Method:

./do "add intent mapping: keyword → vodou-core::vc_load_skill priority X"
# Then configure tool_parameters with skill_name (see below)

Direct Database Method (Recommended for Skills):

sqlite3 vodou-core.db "INSERT INTO intent_mappings 
(keyword, server_name, tool_name, execution_type, priority, tool_parameters) VALUES 
('my-keyword', 'vodou-core', 'vc_load_skill', 'mcp', 10, 
 '{\"skill_name\": \"my-skill-name\"}');"

Examples:

# Add skill intent via database
sqlite3 vodou-core.db "INSERT INTO intent_mappings 
(keyword, server_name, tool_name, execution_type, priority, tool_parameters) VALUES 
('mastery', 'vodou-core', 'vc_load_skill', 'mcp', 10, 
 '{\"skill_name\": \"mastery\"}');"

# This makes: ./do "mastery" load the mastery skill

Intent Format

For MCP Server Tools:

• keyword: The natural language trigger (e.g., "cpu", "performance")
• server::tool: Server name and tool name separated by ::
• priority: Number (higher = higher priority, default: 1)

Format:

keyword → server::tool priority X

For Skills:

• keyword: The natural language trigger (e.g., "hello", "mastery")
• server: Always vodou-core (built-in skills)
• tool: Always load_skill
• tool_parameters: JSON with {"skill_name": "skill-name"}
• priority: Number (higher = higher priority, default: 1)

Format:

keyword → vodou-core::vc_load_skill priority X
tool_parameters: {"skill_name": "skill-name"}

Managing Intents

Remove an intent:

# Natural language
./do "remove intent mapping: keyword"

# CLI
sqlite3 vodou-core.db "DELETE FROM intent_mappings WHERE keyword = 'keyword';"

Examples:

./do "remove intent mapping: performance"
sqlite3 vodou-core.db "DELETE FROM intent_mappings WHERE keyword = 'old_keyword';"

Update an intent:

• Remove the old one, then add a new one with updated settings
• Or use direct database access (advanced)

Intent Best Practices

1. Use Clear Keywords

• ✅ Good: "cpu", "memory", "backup"
• ❌ Avoid: "thing", "stuff", "doit"

2. Set Appropriate Priorities

• 10: Common, frequently used intents
• 5: Less common but useful
• 1: Default, fallback intents
• 15+: Custom workflows, shortcuts

3. Group Related Intents

• Create intents that work well together
• Use similar keywords for related tools
• Consider parallel execution patterns

4. Test Your Intents

./vodou-core intent-signal "your test query"

Common Intent Patterns

MCP Server Tool Intents:

System Monitoring:

cpu → mcp-monitor::get_cpu_info (priority: 10)
memory → mcp-monitor::get_memory_info (priority: 10)
disk → mcp-monitor::get_disk_info (priority: 10)
network → mcp-monitor::get_network_info (priority: 10)

Deep Thinking & Analysis:

deep think → Vodou-Enhanced-Thinking::start_thinking_session (priority: 10)
think → Vodou-Sequential-Thinking::sequentialthinking (priority: 10)

Script Execution & Job Management:

run script → Vodou-script-executor::execute_script (priority: 10)
script status → Vodou-script-executor::script_status (priority: 10)
script output → Vodou-script-executor::script_output (priority: 10)
cancel script → Vodou-script-executor::cancel_script (priority: 10)

Session Management & Long-Running Operations:

create session → Vodou-session-manager::create_session (priority: 10)
list sessions → Vodou-session-manager::list_sessions (priority: 10)
session status → Vodou-session-manager::session_status (priority: 10)
close session → Vodou-session-manager::close_session (priority: 10)

Browser Automation:

screenshot → browser-tools-stdio::takeScreenshot (priority: 10)
console → browser-tools-stdio::getConsoleErrors (priority: 10)

Skill Intents:

Help & Guidance:

hello → vodou-core::vc_load_skill (priority: 10)
  tool_parameters: {"skill_name": "hello"}

oi mastery → vodou-core::vc_load_skill (priority: 10)
  tool_parameters: {"skill_name": "mastery"}

create oi skill → vodou-core::vc_load_skill (priority: 10)
  tool_parameters: {"skill_name": "skill-development"}

Installation & Setup:

install mcp server → vodou-core::vc_load_skill (priority: 10)
  tool_parameters: {"skill_name": "mcp-installer"}

Script Intents:

Example script intents:

nightly backup → Vodou-script-executor::execute_script (priority: 10)
  tool_parameters: {"server_name": "my-project", "script_name": "backup"}

Build & Deployment:

run build → Vodou-script-executor::execute_script (priority: 10)
  tool_parameters: {"server_name": "my-project", "script_name": "build"}

run tests → Vodou-script-executor::execute_script (priority: 10)
  tool_parameters: {"server_name": "my-project", "script_name": "test"}

Intent Visibility

When you use an intent, Vodou shows:

• Which intent mapping was used
• Available related intents
• Priority information

Example output:

./do "cpu"
# 📋 INTENT MAPPING USED: cpu → mcp-monitor::get_cpu_info (priority: 10)
# 🔧 AVAILABLE INTENTS: memory, disk, network, analyze, ...

Advanced: Intent Orchestration

Intents can include orchestration directives:

# Create orchestrated intent (advanced)
./do "add intent mapping: system-health → mcp-monitor::get_host_info priority 15"
# Then configure orchestration in tool_parameters (database)

See:

• docs-DEV/database-schema.md for orchestration configuration (internal)
• docs-DEV/database-driven-orchestration.md for complete Database-Driven Orchestration guide (Pattern 4 & 5, including triple-layer orchestration) (internal)

Troubleshooting Intents

Intent not found:

• Check spelling: sqlite3 vodou-core.db "SELECT keyword, server_name, tool_name, priority FROM intent_mappings ORDER BY priority DESC;"
• Verify server/tool exists: ./do list
• Check if intent was removed

Wrong tool executing:

• Check priority: sqlite3 vodou-core.db "SELECT keyword, server_name, tool_name, priority FROM intent_mappings WHERE keyword LIKE '%keyword%';"
• Multiple intents may match
• Higher priority wins

Intent not working:

• Verify server is connected: ./do list (for MCP tools)
• Verify skill exists: ./do "available skills" (for skills)
• Check server health: ./do "status server-name" (for MCP tools)
• Test the intent: ./vodou-core intent-signal "query"

⏸️ STOPPING POINT: Would you like to:

• See examples of creating specific intents?
• Learn about intent orchestration?
• Troubleshoot an intent issue?
• Go back to the main help menu?

Say "yes" for more details, or choose another topic (1-9).

See also:

• docs-DEV/database-schema.md - Intent database schema (internal)
• docs/cli-reference.md - Complete intent command reference
• docs-DEV/universal-tool-routing.md - Tool routing details (internal)

📚 Section 9: All Reference Guides

Complete Documentation Library

Reference Guides (in references/ directory):

• what-is-oi.md - Complete Vodou overview and architecture
• mcp-servers-guide.md - Everything about MCP servers
• skills-guide.md - Skills system complete guide
• scripts-guide.md - Scripts and background jobs complete guide
• quick-start.md - Step-by-step quick start
• troubleshooting.md - Complete troubleshooting guide
• intents-guide.md - Complete intents and natural language routing guide

Assets (in assets/ directory):

• architecture-diagram.md - System architecture diagrams
• workflow-examples.md - Real-world use cases and examples

⏸️ STOPPING POINT: Which reference guide would you like?

Options:

1. What is Vodou? (complete overview)
2. MCP Servers Guide
3. Skills Guide
4. Scripts & Background Jobs Guide
5. Quick Start Guide
6. Troubleshooting Guide
7. Architecture Diagrams
8. Workflow Examples
9. All of the above

Say the number (1-9) or name the guide you want.

🎯 Quick Reference

Essential Commands

# Discovery
./do "available skills"        # Available skills
./do list                       # All connected servers (11 total)
./do "show me all intent mappings"  # View all intents (MCP tools + Skills + Scripts)

# Execution Examples
./do "cpu memory disk"          # Parallel system monitoring
./do "run script"               # Background script execution
./do "script status job_12345"  # Monitor background jobs
./do "script output job_12345"  # View live script output
./do "cancel script job_12345"  # Stop running background jobs
./do "take screenshot"          # Browser automation
./do "deep think about X"       # Enhanced thinking sessions
./do "start thinking session"   # Persistent thinking
./do "save this to memory"      # Vodou memory system

# Script Execution
./do "nightly backup"           # Example: execute registered script by intent keyword
./do "run build"                # Execute build script
./do "run tests"                # Execute test script

# Session Management
./do "create session browser"   # Create long-running MCP session
./do "list sessions"            # View all active sessions
./do "session status sess_123"  # Check session status
./do "close session sess_123"   # Close specific session

# Intent Management
./do "show me all intent mappings"  # List all intents (MCP tools + Skills + Scripts)
./do "add intent mapping: keyword → server::tool priority X"  # Add MCP tool intent
./do "remove intent mapping: keyword"  # Remove intent
sqlite3 vodou-core.db "SELECT keyword, server_name, tool_name, priority FROM intent_mappings ORDER BY priority DESC;"                # CLI: List intents
sqlite3 vodou-core.db "INSERT INTO intent_mappings (keyword, server_name, tool_name, priority) VALUES (<keyword>, <server>, <tool>, '[priority]');"  # CLI: Add MCP tool intent
# Note: Skill and Script intents require database insertion (see Section 8)

# Help
./do "hello"                    # This help center
./do "oi mastery"              # Advanced techniques

Getting Help

• This help center: ./do "hello"
• Advanced guide: ./do "oi mastery"
• Available tools: ./do list
• Troubleshooting: See Section 5 above

🎉 Welcome to Vodou!

You now have:

• ✅ Understanding of what Vodou is
• ✅ Knowledge of core concepts
• ✅ Access to detailed guides
• ✅ Quick reference commands

Remember: Vodou is here to help you work faster and smarter. Don't be afraid to experiment!

Next steps:

• Try: ./do "cpu memory disk" to see parallel execution
• Explore: ./do "available skills" to see available skills
• Learn: ./do "oi mastery" for advanced techniques
• Help: ./do "hello" anytime for this guide

Welcome to the future of AI-powered work! 🚀

🆘 Need More Help?

Quick Help:

• ./do "hello" - This help center
• ./do "oi mastery" - Advanced techniques
• ./do list - See available tools

Detailed Guides:

• Check references/ directory for complete documentation
• Check assets/ directory for diagrams and examples

Still Stuck?

• See Section 5 (Troubleshooting) above
• Check references/troubleshooting.md
• Review error messages carefully

You've got this! 💪