# Hello

> Comprehensive help center and user guide for Vodou - your complete guide to understanding and using Vodou effectively

- Skill: `vodouai/hello` (Agent Skill, multi-file: 17 files)
- Install (CLI): `npx skillmds@latest add vodouai/hello`
- Raw SKILL.md: https://api.skillmd.com/api/skills/vodouai/hello/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Coding & Dev Tools
- Author: VodouAI (https://skillmd.com/u/vodouai)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/vodouai/hello

---


# 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:**
```bash
# 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:**
```bash
./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](https://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:**
```bash
# 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:**
```bash
# 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:**

```sql
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:**

```sql
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:**
```bash
./do "nightly backup"
```

### Common Script Use Cases

**1. Long-running / scheduled scripts:**
```bash
./do "nightly backup"
# Check status: ./do "script status job_12345"
```

**2. Build Tasks:**
```bash
./do "run build script"
# Executes npm/yarn build scripts
# Can run in background for long builds
```

**3. Data Processing:**
```bash
./do "process data"
# Long-running data processing scripts
# Monitor progress with script_status
```

**4. Testing:**
```bash
./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:**
```bash
# 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:**
```bash
./do "show me intent mappings for docker"
./do "show me intent mappings for browser"
./do "show me intent mappings for system"
```

**View specific intent:**
```bash
sqlite3 vodou-core.db "SELECT keyword, server_name, tool_name, priority FROM intent_mappings WHERE keyword LIKE '%cpu%';"
```

**Test an intent:**
```bash
./vodou-core intent-signal "check my cpu usage"
```

### Creating New Intents

**For MCP Server Tools:**

**Natural Language Method (Recommended):**
```bash
# Format: keyword → MCP-server-name::tool-name priority X
./do "add intent mapping: keyword → server::tool priority X"
```

**Format Breakdown:**
| Component | Example | Description |
|-----------|---------|-------------|
| `keyword` | `health` | The trigger phrase you'll type |
| `MCP-server-name` | `mcp-monitor` | The MCP server providing the tool |
| `tool-name` | `get_cpu_info` | The specific tool to execute |
| `priority` | `15` | Higher number = preferred when multiple match (1-15+) |

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

**Examples:**
```bash
# 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:**
```bash
sqlite3 vodou-core.db "INSERT INTO intent_mappings (keyword, server_name, tool_name, priority) VALUES (<keyword>, <server>, <tool>, '[priority]');"
```

**Example:**
```bash
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:**
```bash
./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):**
```sql
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:**
```bash
# 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:**
```bash
# Natural language
./do "remove intent mapping: keyword"

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

**Examples:**
```bash
./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**
```bash
./vodou-core intent-signal "your test query"
```

### Common Intent Patterns

**MCP Server Tool Intents:**

**System Monitoring:**
```bash
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:**
```bash
deep think → Vodou-Enhanced-Thinking::start_thinking_session (priority: 10)
think → Vodou-Sequential-Thinking::sequentialthinking (priority: 10)
```

**Script Execution & Job Management:**
```bash
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:**
```bash
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:**
```bash
screenshot → browser-tools-stdio::takeScreenshot (priority: 10)
console → browser-tools-stdio::getConsoleErrors (priority: 10)
```

**Skill Intents:**

**Help & Guidance:**
```bash
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:**
```bash
install mcp server → vodou-core::vc_load_skill (priority: 10)
  tool_parameters: {"skill_name": "mcp-installer"}
```

**Script Intents:**

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

**Build & Deployment:**
```bash
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:**
```bash
./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:**
```bash
# 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

```bash
# 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 mast

…(truncated)