v1.0.0 to v1.0.0

---

name: hello

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

version: 1.0.0

kind: workflow

required_tools: []

trigger_phrases:

- "hello"

- "hello world"

- "hi oi"

- "what is oi"

- "how does oi work"

- "help me get started"

- "setup oi"

- "oi help"

- "vodou help"

- "oi guide"

- "vodou guide"

- "help center"

- "oi information"

- "vodou information"

- "tell me about oi"

- "--"

stopping_points: required

actions: none

imported_from:

source: hand-written

---

# 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

```

**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

```

**Test an intent:**

```bash

```

### 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

```

**CLI Method:**

```bash

```

**Example:**

```bash

```

**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

```

**Examples:**

```bash

./do "remove intent mapping: performance"

```

**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

```

### 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)

# 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:**

- Verify server/tool exists: `./do list`

- Check if intent was removed

**Wrong tool executing:**

- 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)

**⏸️ 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

# 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!** 💪