docs: Refactor documentation structure and enhance project overview

- Update MkDocs configuration with streamlined navigation and theme improvements - Revise README with comprehensive project introduction and key features - Add new documentation pages for NLP, custom prompts, and extras - Enhance index page with system architecture diagram and getting started guide - Improve overall documentation clarity and organization
2025-02-06 10:06:27 +01:00
6 changed files with 886 additions and 226 deletions
--- a/README.md
+++ b/README.md
@@ -228,10 +228,39 @@ bun run start

 ## Documentation 📚

+### Core Documentation
 - [Configuration Guide](docs/configuration.md)
 - [API Documentation](docs/api.md)
 - [Troubleshooting](docs/troubleshooting.md)

+### Advanced Features
+- [Natural Language Processing](docs/nlp.md) - AI-powered automation analysis and control
+- [Custom Prompts Guide](docs/prompts.md) - Create and customize AI behavior
+- [Extras & Tools](docs/extras.md) - Additional utilities and advanced features
+
+### Extra Tools 🛠️
+
+I've included several powerful tools in the `extra/` directory to enhance your Home Assistant experience:
+
+1. **Home Assistant Analyzer CLI** (`ha-analyzer-cli.ts`)
+   - Deep automation analysis using AI models
+   - Security vulnerability scanning
+   - Performance optimization suggestions
+   - System health metrics
+
+2. **Speech-to-Text Example** (`speech-to-text-example.ts`)
+   - Wake word detection
+   - Speech-to-text transcription
+   - Multiple language support
+   - GPU acceleration support
+
+3. **Claude Desktop Setup** (`claude-desktop-macos-setup.sh`)
+   - Automated Claude Desktop installation for macOS
+   - Environment configuration
+   - MCP integration setup
+
+See [Extras Documentation](docs/extras.md) for detailed usage instructions and examples.
+
 ## Client Integration 🔗

 ### Cursor Integration 🖱️
--- a/docs/extras.md
+++ b/docs/extras.md
@@ -0,0 +1,228 @@
+# Extras & Tools Guide 🛠️
+
+## Overview
+
+I've included several additional tools and utilities in the `extra/` directory to enhance your Home Assistant MCP experience. These tools help with automation analysis, speech processing, and client integration.
+
+## Available Tools 🧰
+
+### 1. Home Assistant Analyzer CLI
+```bash
+# Installation
+bun install -g @homeassistant-mcp/ha-analyzer-cli
+
+# Usage
+ha-analyzer analyze path/to/automation.yaml
+```
+
+Features:
+- 🔍 Deep automation analysis using AI models
+- 🚨 Security vulnerability scanning
+- 💡 Performance optimization suggestions
+- 📊 System health metrics
+- ⚡ Energy usage analysis
+- 🤖 Automation improvement recommendations
+
+### 2. Speech-to-Text Example
+```bash
+# Run the example
+bun run extra/speech-to-text-example.ts
+```
+
+Features:
+- 🎤 Wake word detection ("hey jarvis", "ok google", "alexa")
+- 🗣️ Speech-to-text transcription
+- 🌍 Multiple language support
+- 🚀 GPU acceleration support
+- 📝 Event handling and logging
+
+### 3. Claude Desktop Setup (macOS)
+```bash
+# Make script executable
+chmod +x extra/claude-desktop-macos-setup.sh
+
+# Run setup
+./extra/claude-desktop-macos-setup.sh
+```
+
+Features:
+- 🖥️ Automated Claude Desktop installation
+- ⚙️ Environment configuration
+- 🔗 MCP integration setup
+- 🚀 Performance optimization
+
+## Home Assistant Analyzer Details 📊
+
+### Analysis Categories
+
+1. **System Overview**
+   - Current state assessment
+   - Health check
+   - Configuration review
+   - Integration status
+   - Issue detection
+
+2. **Performance Analysis**
+   - Resource usage monitoring
+   - Response time analysis
+   - Optimization opportunities
+   - Bottleneck detection
+
+3. **Security Assessment**
+   - Current security measures
+   - Vulnerability detection
+   - Security recommendations
+   - Best practices review
+
+4. **Optimization Suggestions**
+   - Performance improvements
+   - Configuration optimizations
+   - Integration enhancements
+   - Automation opportunities
+
+5. **Maintenance Tasks**
+   - Required updates
+   - Cleanup recommendations
+   - Regular maintenance tasks
+   - System health checks
+
+6. **Entity Usage Analysis**
+   - Most active entities
+   - Rarely used entities
+   - Potential duplicates
+   - Usage patterns
+
+7. **Automation Analysis**
+   - Inefficient automations
+   - Improvement suggestions
+   - Blueprint recommendations
+   - Condition optimizations
+
+8. **Energy Management**
+   - High consumption detection
+   - Monitoring suggestions
+   - Tariff optimization
+   - Usage patterns
+
+### Configuration
+
+```yaml
+# config/analyzer.yaml
+analysis:
+  depth: detailed    # quick, basic, or detailed
+  models:           # AI models to use
+    - gpt-4         # for complex analysis
+    - gpt-3.5-turbo # for quick checks
+  focus:            # Analysis focus areas
+    - security
+    - performance
+    - automations
+    - energy
+  ignore:           # Paths to ignore
+    - test/
+    - disabled/
+```
+
+## Speech-to-Text Integration 🎤
+
+### Prerequisites
+1. Docker installed and running
+2. NVIDIA GPU with CUDA (optional, for faster processing)
+3. Audio input device configured
+
+### Configuration
+```yaml
+# speech-config.yaml
+wake_word:
+  enabled: true
+  words:
+    - "hey jarvis"
+    - "ok google"
+    - "alexa"
+  sensitivity: 0.5
+
+speech_to_text:
+  model: "base"     # tiny, base, small, medium, large
+  language: "en"    # en, es, fr, etc.
+  use_gpu: true     # Enable GPU acceleration
+```
+
+### Usage Example
+```typescript
+import { SpeechProcessor } from './speech-to-text-example';
+
+const processor = new SpeechProcessor({
+  wakeWord: true,
+  model: 'base',
+  language: 'en'
+});
+
+processor.on('wake_word', (timestamp) => {
+  console.log('Wake word detected!');
+});
+
+processor.on('transcription', (text) => {
+  console.log('Transcribed:', text);
+});
+
+await processor.start();
+```
+
+## Best Practices 🎯
+
+1. **Analysis Tool Usage**
+   - Run regular system analyses
+   - Focus on specific areas when needed
+   - Review and implement suggestions
+   - Monitor improvements
+
+2. **Speech Processing**
+   - Choose appropriate models
+   - Test in your environment
+   - Adjust sensitivity as needed
+   - Monitor performance
+
+3. **Integration Setup**
+   - Follow security best practices
+   - Test in development first
+   - Monitor resource usage
+   - Keep configurations updated
+
+## Troubleshooting 🔧
+
+### Common Issues
+
+1. **Analyzer CLI Issues**
+   - Verify API keys
+   - Check network connectivity
+   - Validate YAML syntax
+   - Review permissions
+
+2. **Speech Processing Issues**
+   - Check audio device
+   - Verify Docker setup
+   - Monitor GPU usage
+   - Check model compatibility
+
+3. **Integration Issues**
+   - Verify configurations
+   - Check dependencies
+   - Review logs
+   - Test connectivity
+
+## API Reference 🔌
+
+### Analyzer API
+```typescript
+import { HomeAssistantAnalyzer } from './ha-analyzer-cli';
+
+const analyzer = new HomeAssistantAnalyzer({
+  depth: 'detailed',
+  focus: ['security', 'performance']
+});
+
+const analysis = await analyzer.analyze();
+console.log(analysis.suggestions);
+```
+
+See [API Documentation](api.md) for more details. 
--- a/docs/index.md
+++ b/docs/index.md
@@ -4,22 +4,108 @@ title: Home
 nav_order: 1
 ---

-# Advanced Home Assistant MCP
+# Home Assistant MCP Documentation 🏠🤖

-Welcome to the Advanced Home Assistant Master Control Program documentation.
+Welcome to the documentation for my Home Assistant MCP (Model Context Protocol) Server. This documentation will help you get started with installation, configuration, and usage of the MCP server.

-This documentation provides comprehensive information about setting up, configuring, and using the Advanced Home Assistant MCP system.
+## What is MCP? 🤔

-## Quick Links
+MCP is a lightweight integration tool for Home Assistant that provides:

- [Getting Started](getting-started/index.md)
- [API Reference](api/index.md)
+- 🔌 REST API for device control
+- 📡 WebSocket/SSE for real-time updates
+- 🤖 AI-powered automation analysis
+- 🎤 Optional speech processing
+- 🔐 Secure authentication
+
+## Quick Links 🔗
+
+- [Quick Start Guide](getting-started/quick-start.md)
 - [Configuration Guide](getting-started/configuration.md)
- [Docker Setup](getting-started/docker.md)
+- [API Reference](api/overview.md)
+- [Tools & Extras](tools/overview.md)

-## What is MCP Server?
+## System Architecture 📊

-MCP Server is a bridge between Home Assistant and custom automation tools, enabling basic device control and real-time monitoring of your smart home environment. It provides a flexible interface for managing and interacting with your home automation setup.
+```mermaid
+flowchart TB
+    subgraph Client["Client Applications"]
+        direction TB
+        Web["Web Interface"]
+        Mobile["Mobile Apps"]
+        Voice["Voice Control"]
+    end
+
+    subgraph MCP["MCP Server"]
+        direction TB
+        API["REST API"]
+        WS["WebSocket/SSE"]
+        Auth["Authentication"]
+        
+        subgraph Speech["Speech Processing (Optional)"]
+            direction TB
+            Wake["Wake Word Detection"]
+            STT["Speech-to-Text"]
+            
+            subgraph STT_Options["STT Options"]
+                direction LR
+                Whisper["Whisper"]
+                FastWhisper["Fast Whisper"]
+            end
+            
+            Wake --> STT
+            STT --> STT_Options
+        end
+    end
+
+    subgraph HA["Home Assistant"]
+        direction TB
+        HASS_API["HASS API"]
+        HASS_WS["HASS WebSocket"]
+        Devices["Smart Devices"]
+    end
+
+    Client --> MCP
+    MCP --> HA
+    HA --> Devices
+
+    style Speech fill:#f9f,stroke:#333,stroke-width:2px
+    style STT_Options fill:#bbf,stroke:#333,stroke-width:1px
+```
+
+## Prerequisites 📋
+
+- 🚀 [Bun runtime](https://bun.sh) (v1.0.26+)
+- 🏡 [Home Assistant](https://www.home-assistant.io/) instance
+- 🐳 Docker (optional, recommended for deployment)
+- 🖥️ Node.js 18+ (optional, for speech features)
+- 🎮 NVIDIA GPU with CUDA support (optional, for faster speech processing)
+
+## Why Bun? 🚀
+
+I chose Bun as the runtime for several key benefits:
+
+- ⚡ **Blazing Fast Performance**
+  - Up to 4x faster than Node.js
+  - Built-in TypeScript support
+  - Optimized file system operations
+
+- 🎯 **All-in-One Solution**
+  - Package manager (faster than npm/yarn)
+  - Bundler (no webpack needed)
+  - Test runner (built-in testing)
+  - TypeScript transpiler
+
+- 🔋 **Built-in Features**
+  - SQLite3 driver
+  - .env file loading
+  - WebSocket client/server
+  - File watcher
+  - Test runner
+
+## Getting Started 🚀
+
+Check out the [Quick Start Guide](getting-started/quick-start.md) to begin your journey with Home Assistant MCP!

 ## Key Features

--- a/docs/nlp.md
+++ b/docs/nlp.md
@@ -0,0 +1,196 @@
+# Natural Language Processing Guide 🤖
+
+## Overview
+
+My MCP Server includes powerful Natural Language Processing (NLP) capabilities powered by various AI models. This enables intelligent automation analysis, natural language control, and context-aware interactions with your Home Assistant setup.
+
+## Available Models 🎯
+
+### OpenAI Models
+- **GPT-4**
+  - Best for complex automation analysis
+  - Natural language understanding
+  - Context window: 8k-32k tokens
+  - Recommended for: Automation analysis, complex queries
+
+- **GPT-3.5-Turbo**
+  - Faster response times
+  - More cost-effective
+  - Context window: 4k tokens
+  - Recommended for: Quick commands, basic analysis
+
+### Claude Models
+- **Claude 2**
+  - Excellent code analysis
+  - Large context window (100k tokens)
+  - Strong system understanding
+  - Recommended for: Deep automation analysis
+
+### DeepSeek Models
+- **DeepSeek-Coder**
+  - Specialized in code understanding
+  - Efficient for automation rules
+  - Context window: 8k tokens
+  - Recommended for: Code generation, rule analysis
+
+## Configuration ⚙️
+
+```bash
+# AI Model Configuration
+PROCESSOR_TYPE=openai          # openai, claude, or deepseek
+OPENAI_MODEL=gpt-3.5-turbo    # or gpt-4, gpt-4-32k
+OPENAI_API_KEY=your_key_here
+
+# Optional: DeepSeek Configuration
+DEEPSEEK_API_KEY=your_key_here
+DEEPSEEK_BASE_URL=https://api.deepseek.com/v1
+
+# Analysis Settings
+ANALYSIS_TIMEOUT=30000         # Timeout in milliseconds
+MAX_RETRIES=3                 # Number of retries on failure
+```
+
+## Usage Examples 💡
+
+### 1. Automation Analysis
+
+```bash
+# Analyze an automation rule
+bun run analyze-automation path/to/automation.yaml
+
+# Example output:
+# "This automation triggers on motion detection and turns on lights.
+#  Potential issues:
+#  - No timeout for light turn-off
+#  - Missing condition for ambient light level"
+```
+
+### 2. Natural Language Commands
+
+```typescript
+// Send a natural language command
+const response = await fetch('http://localhost:3000/api/nlp/command', {
+  method: 'POST',
+  headers: {
+    'Content-Type': 'application/json',
+    'Authorization': `Bearer ${token}`
+  },
+  body: JSON.stringify({
+    command: "Turn on the living room lights and set them to warm white"
+  })
+});
+```
+
+### 3. Context-Aware Queries
+
+```typescript
+// Query with context
+const response = await fetch('http://localhost:3000/api/nlp/query', {
+  method: 'POST',
+  headers: {
+    'Content-Type': 'application/json',
+    'Authorization': `Bearer ${token}`
+  },
+  body: JSON.stringify({
+    query: "What's the temperature trend in the bedroom?",
+    context: {
+      timeframe: "last_24h",
+      include_humidity: true
+    }
+  })
+});
+```
+
+## Custom Prompts 📝
+
+You can customize the AI's behavior by creating custom prompts. See [Custom Prompts Guide](prompts.md) for details.
+
+Example custom prompt:
+```yaml
+name: energy_analysis
+description: Analyze home energy usage patterns
+prompt: |
+  Analyze the following energy usage data and provide:
+  1. Peak usage patterns
+  2. Potential optimizations
+  3. Comparison with typical usage
+  4. Cost-saving recommendations
+  
+  Context: {context}
+  Data: {data}
+```
+
+## Best Practices 🎯
+
+1. **Model Selection**
+   - Use GPT-3.5-Turbo for quick queries
+   - Use GPT-4 for complex analysis
+   - Use Claude for large context analysis
+   - Use DeepSeek for code-heavy tasks
+
+2. **Performance Optimization**
+   - Cache frequent queries
+   - Use streaming for long responses
+   - Implement retry logic for API calls
+
+3. **Cost Management**
+   - Monitor API usage
+   - Implement rate limiting
+   - Cache responses where appropriate
+
+4. **Error Handling**
+   - Implement fallback models
+   - Handle API timeouts gracefully
+   - Log failed queries for analysis
+
+## Advanced Features 🚀
+
+### 1. Chain of Thought Analysis
+```typescript
+const result = await analyzeWithCoT({
+  query: "Optimize my morning routine automation",
+  steps: ["Parse current automation", "Analyze patterns", "Suggest improvements"]
+});
+```
+
+### 2. Multi-Model Analysis
+```typescript
+const results = await analyzeWithMultiModel({
+  query: "Security system optimization",
+  models: ["gpt-4", "claude-2"],
+  compareResults: true
+});
+```
+
+### 3. Contextual Memory
+```typescript
+const memory = new ContextualMemory({
+  timeframe: "24h",
+  maxItems: 100
+});
+
+await memory.add("User typically arrives home at 17:30");
+```
+
+## Troubleshooting 🔧
+
+### Common Issues
+
+1. **Slow Response Times**
+   - Check model selection
+   - Verify API rate limits
+   - Consider caching
+
+2. **Poor Analysis Quality**
+   - Review prompt design
+   - Check context window limits
+   - Consider using a more capable model
+
+3. **API Errors**
+   - Verify API keys
+   - Check network connectivity
+   - Review rate limits
+
+## API Reference 📚
+
+See [API Documentation](api.md) for detailed endpoint specifications. 
--- a/docs/prompts.md
+++ b/docs/prompts.md
@@ -0,0 +1,263 @@
+# Custom Prompts Guide 🎯
+
+## Overview
+
+Custom prompts allow you to tailor the AI's behavior to your specific needs. I've designed this system to be flexible and powerful, enabling everything from simple commands to complex automation analysis.
+
+## Prompt Structure 📝
+
+Custom prompts are defined in YAML format:
+
+```yaml
+name: prompt_name
+description: Brief description of what this prompt does
+version: 1.0
+author: your_name
+tags: [automation, analysis, security]
+models: [gpt-4, claude-2]  # Compatible models
+prompt: |
+  Your detailed prompt text here.
+  You can use {variables} for dynamic content.
+  
+  Context: {context}
+  Data: {data}
+  
+variables:
+  - name: context
+    type: object
+    description: Contextual information
+    required: true
+  - name: data
+    type: array
+    description: Data to analyze
+    required: true
+```
+
+## Prompt Types 🎨
+
+### 1. Analysis Prompts
+```yaml
+name: automation_analysis
+description: Analyze Home Assistant automations
+prompt: |
+  Analyze the following Home Assistant automation:
+  {automation_yaml}
+  
+  Provide:
+  1. Security implications
+  2. Performance considerations
+  3. Potential improvements
+  4. Error handling suggestions
+```
+
+### 2. Command Prompts
+```yaml
+name: natural_command
+description: Process natural language commands
+prompt: |
+  Convert the following natural language command into Home Assistant actions:
+  "{command}"
+  
+  Available devices: {devices}
+  Current state: {state}
+```
+
+### 3. Query Prompts
+```yaml
+name: state_query
+description: Answer questions about system state
+prompt: |
+  Answer the following question about the system state:
+  "{question}"
+  
+  Current states:
+  {states}
+  
+  Historical data:
+  {history}
+```
+
+## Variables and Context 🔄
+
+### Built-in Variables
+- `{timestamp}` - Current time
+- `{user}` - Current user
+- `{device_states}` - All device states
+- `{last_events}` - Recent events
+- `{system_info}` - System information
+
+### Custom Variables
+```yaml
+variables:
+  - name: temperature_threshold
+    type: number
+    default: 25
+    description: Temperature threshold for alerts
+  
+  - name: devices
+    type: array
+    required: true
+    description: List of relevant devices
+```
+
+## Creating Custom Prompts 🛠️
+
+1. Create a new file in `prompts/custom/`:
+```bash
+bun run create-prompt my_prompt
+```
+
+2. Edit the generated template:
+```yaml
+name: my_custom_prompt
+description: My custom prompt for specific tasks
+version: 1.0
+author: your_name
+prompt: |
+  Your prompt text here
+```
+
+3. Test your prompt:
+```bash
+bun run test-prompt my_custom_prompt
+```
+
+## Advanced Features 🚀
+
+### 1. Prompt Chaining
+```yaml
+name: complex_analysis
+chain:
+  - automation_analysis
+  - security_check
+  - optimization_suggestions
+```
+
+### 2. Conditional Prompts
+```yaml
+name: adaptive_response
+conditions:
+  - if: "temperature > 25"
+    use: high_temp_prompt
+  - if: "temperature < 10"
+    use: low_temp_prompt
+  - else: normal_temp_prompt
+```
+
+### 3. Dynamic Templates
+```yaml
+name: dynamic_template
+template: |
+  {% if time.hour < 12 %}
+    Good morning! Here's the morning analysis:
+  {% else %}
+    Good evening! Here's the evening analysis:
+  {% endif %}
+  
+  {analysis_content}
+```
+
+## Best Practices 🎯
+
+1. **Prompt Design**
+   - Be specific and clear
+   - Include examples
+   - Use consistent formatting
+   - Consider edge cases
+
+2. **Variable Usage**
+   - Define clear variable types
+   - Provide defaults when possible
+   - Document requirements
+   - Validate inputs
+
+3. **Performance**
+   - Keep prompts concise
+   - Use appropriate models
+   - Cache when possible
+   - Consider token limits
+
+4. **Maintenance**
+   - Version your prompts
+   - Document changes
+   - Test thoroughly
+   - Share improvements
+
+## Examples 📚
+
+### Home Security Analysis
+```yaml
+name: security_analysis
+description: Analyze home security status
+prompt: |
+  Analyze the current security status:
+  
+  Doors: {door_states}
+  Windows: {window_states}
+  Cameras: {camera_states}
+  Motion Sensors: {motion_states}
+  
+  Recent Events:
+  {recent_events}
+  
+  Provide:
+  1. Current security status
+  2. Potential vulnerabilities
+  3. Recommended actions
+  4. Automation suggestions
+```
+
+### Energy Optimization
+```yaml
+name: energy_optimization
+description: Analyze and optimize energy usage
+prompt: |
+  Review energy consumption patterns:
+  
+  Usage Data: {energy_data}
+  Device States: {device_states}
+  Weather: {weather_data}
+  
+  Provide:
+  1. Usage patterns
+  2. Inefficiencies
+  3. Optimization suggestions
+  4. Estimated savings
+```
+
+## Troubleshooting 🔧
+
+### Common Issues
+
+1. **Prompt Not Working**
+   - Verify YAML syntax
+   - Check variable definitions
+   - Validate model compatibility
+   - Review token limits
+
+2. **Poor Results**
+   - Improve prompt specificity
+   - Add more context
+   - Try different models
+   - Include examples
+
+3. **Performance Issues**
+   - Optimize prompt length
+   - Review caching strategy
+   - Check rate limits
+   - Monitor token usage
+
+## API Integration 🔌
+
+```typescript
+// Load a custom prompt
+const prompt = await loadPrompt('my_custom_prompt');
+
+// Execute with variables
+const result = await executePrompt(prompt, {
+  context: currentContext,
+  data: analysisData
+});
+```
+
+See [API Documentation](api.md) for more details. 
--- a/mkdocs.yml
+++ b/mkdocs.yml
@@ -1,249 +1,107 @@
-site_name: MCP Server for Home Assistant
-site_url: https://jango-blockchained.github.io/advanced-homeassistant-mcp
-repo_url: https://github.com/jango-blockchained/advanced-homeassistant-mcp
-site_description: Home Assistant MCP Server Documentation
-# Add this to handle GitHub Pages serving from a subdirectory
-site_dir: site/advanced-homeassistant-mcp
+site_name: Home Assistant MCP
+site_url: https://jango-blockchained.github.io/homeassistant-mcp
+repo_url: https://github.com/jango-blockchained/homeassistant-mcp
+repo_name: jango-blockchained/homeassistant-mcp
+edit_uri: edit/main/docs/

 theme:
  name: material
-  logo: assets/images/logo.png
-  favicon: assets/images/favicon.ico
-  
-  # Modern Features
  features:
-    # Navigation Enhancements
-    - navigation.tabs
-    - navigation.tabs.sticky
-    - navigation.indexes
+    - navigation.instant
+    - navigation.tracking
    - navigation.sections
    - navigation.expand
-    - navigation.path
-    - navigation.footer
-    - navigation.prune
-    - navigation.tracking
-    - navigation.instant
-    
-    # UI Elements
-    - header.autohide
-    - toc.integrate
+    - navigation.indexes
    - toc.follow
-    - announce.dismiss
-    
-    # Search Features
    - search.suggest
    - search.highlight
-    - search.share
-    
-    # Code Features
-    - content.code.annotate
-    - content.code.copy
-    - content.code.select
-    - content.tabs.link
-    - content.tooltips
-    
-  # Theme Configuration
  palette:
-    # Dark mode as primary
-    - media: "(prefers-color-scheme: dark)"
-      scheme: slate
-      primary: deep-purple
-      accent: purple
+    - scheme: default
+      primary: indigo
+      accent: indigo
      toggle:
-        icon: material/weather-sunny
-        name: Switch to light mode
-    # Light mode as secondary
-    - media: "(prefers-color-scheme: light)"
-      scheme: default
-      primary: deep-purple
-      accent: purple
-      toggle:
-        icon: material/weather-night
+        icon: material/brightness-7
        name: Switch to dark mode
-  
-  font:
-    text: Roboto
-    code: Roboto Mono
-  
+    - scheme: slate
+      primary: indigo
+      accent: indigo
+      toggle:
+        icon: material/brightness-4
+        name: Switch to light mode
  icon:
    repo: fontawesome/brands/github
-    edit: material/pencil
-    view: material/eye
+  favicon: assets/favicon.png
+  logo: assets/logo.png
+
+plugins:
+  - search
+  - mermaid2
+  - git-revision-date-localized:
+      type: date
+  - minify:
+      minify_html: true

 markdown_extensions:
-  # Modern Code Highlighting
-  - pymdownx.highlight:
-      anchor_linenums: true
-      line_spans: __span
-      pygments_lang_class: true
-  - pymdownx.inlinehilite
-  - pymdownx.snippets
-  
-  # Advanced Formatting
-  - pymdownx.critic
+  - admonition
+  - attr_list
+  - def_list
+  - footnotes
+  - meta
+  - toc:
+      permalink: true
+  - pymdownx.arithmatex
+  - pymdownx.betterem:
+      smart_enable: all
  - pymdownx.caret
+  - pymdownx.critic
+  - pymdownx.details
+  - pymdownx.emoji:
+      emoji_index: !!python/name:materialx.emoji.twemoji
+      emoji_generator: !!python/name:materialx.emoji.to_svg
+  - pymdownx.highlight
+  - pymdownx.inlinehilite
  - pymdownx.keys
  - pymdownx.mark
-  - pymdownx.tilde
-  
-  # Interactive Elements
-  - pymdownx.details
-  - pymdownx.tabbed:
-      alternate_style: true
-  - pymdownx.tasklist:
-      custom_checkbox: true
-  
-  # Diagrams & Formatting
+  - pymdownx.smartsymbols
  - pymdownx.superfences:
      custom_fences:
        - name: mermaid
          class: mermaid
          format: !!python/name:pymdownx.superfences.fence_code_format
-  - pymdownx.arithmatex:
-      generic: true
-  
-  # Additional Extensions
-  - admonition
-  - attr_list
-  - md_in_html
-  - pymdownx.emoji:
-      emoji_index: !!python/name:material.extensions.emoji.twemoji
-      emoji_generator: !!python/name:material.extensions.emoji.to_svg
-  - footnotes
-  - tables
-  - def_list
-  - abbr
+  - pymdownx.tabbed:
+      alternate_style: true
+  - pymdownx.tasklist:
+      custom_checkbox: true
+  - pymdownx.tilde

-plugins:
-  # Core Plugins
-  - search:
-      separator: '[\s\-,:!=\[\]()"/]+|(?!\b)(?=[A-Z][a-z])|\.(?!\d)|&[lg]t;'
-  - minify:
-      minify_html: true
-  - mkdocstrings
-  
-  # Advanced Features
-  - social:
-      cards: false
-  - tags
-  - offline
-  
-  # Version Management
-  - git-revision-date-localized:
-      enable_creation_date: true
-      type: date
-
-extra:
-  # Consent Management
-  consent:
-    title: Cookie consent
-    description: >- 
-      We use cookies to recognize your repeated visits and preferences, as well
-      as to measure the effectiveness of our documentation and whether users
-      find what they're searching for. With your consent, you're helping us to
-      make our documentation better.
-    actions:
-      - accept
-      - reject
-      - manage
-  
-  # Version Management
-  version:
-    provider: mike
-    default: latest
-  
-  # Social Links
-  social:
-    - icon: fontawesome/brands/github
-      link: https://github.com/jango-blockchained/homeassistant-mcp
-    - icon: fontawesome/brands/docker
-      link: https://hub.docker.com/r/jangoblockchained/homeassistant-mcp
-  
-  # Status Indicators
-  status:
-    new: Recently added
-    deprecated: Deprecated
-    beta: Beta
-  
-  # Analytics
-  analytics:
-    provider: google
-    property: !ENV GOOGLE_ANALYTICS_KEY
-    feedback:
-      title: Was this page helpful?
-      ratings:
-        - icon: material/emoticon-happy-outline
-          name: This page was helpful
-          data: 1
-          note: >-
-            Thanks for your feedback!
-        - icon: material/emoticon-sad-outline
-          name: This page could be improved
-          data: 0
-          note: >-
-            Thanks for your feedback! Please consider creating an issue to help us improve.
-
-extra_css:
-  - stylesheets/extra.css
-
-extra_javascript:
-  - javascripts/mathjax.js
-  - https://polyfill.io/v3/polyfill.min.js?features=es6
-  - https://cdn.jsdelivr.net/npm/mathjax@3/es5/tex-mml-chtml.js
-  - javascripts/extra.js
-
-copyright: Copyright &copy; 2025 jango-blockchained
-
-# Keep existing nav structure
 nav:
  - Home: index.md
  - Getting Started:
-    - Overview: getting-started/index.md
+    - Quick Start: getting-started/quick-start.md
    - Installation: getting-started/installation.md
-    - Quick Start: getting-started/quickstart.md
    - Configuration: getting-started/configuration.md
-    - Docker Setup: getting-started/docker.md
+  - Features:
+    - Core Features: features/core-features.md
+    - Speech Processing: features/speech-processing.md
+    - NLP Integration: features/nlp.md
+    - Custom Prompts: features/prompts.md
+  - Tools & Extras:
+    - Overview: tools/overview.md
+    - Analyzer CLI: tools/analyzer-cli.md
+    - Speech Examples: tools/speech-examples.md
+    - Claude Desktop: tools/claude-desktop.md
  - API Reference:
-    - Overview: api/index.md
-    - Core API: api/core.md
-    - SSE API: api/sse.md
-    - API Documentation: api.md
-  - Usage: usage.md
-  - Configuration:
-    - Overview: config/index.md
-    - System Configuration: configuration.md
-    - Security: security.md
-  - Tools:
-    - Overview: tools/index.md
-    - Device Management:
-      - List Devices: tools/device-management/list-devices.md
-      - Device Control: tools/device-management/control.md
-    - History & State:
-      - History: tools/history-state/history.md
-      - Scene Management: tools/history-state/scene.md
-    - Automation:
-      - Automation Management: tools/automation/automation.md
-      - Automation Configuration: tools/automation/automation-config.md
-    - Add-ons & Packages:
-      - Add-on Management: tools/addons-packages/addon.md
-      - Package Management: tools/addons-packages/package.md
-    - Notifications:
-      - Notify: tools/notifications/notify.md
-    - Events:
-      - Event Subscription: tools/events/subscribe-events.md
-      - SSE Statistics: tools/events/sse-stats.md
+    - Overview: api/overview.md
+    - REST API: api/rest.md
+    - WebSocket API: api/websocket.md
+    - Events: api/events.md
  - Development:
-    - Overview: development/index.md
-    - Environment Setup: development/environment.md
-    - Architecture: architecture.md
-    - Contributing: contributing.md
-    - Testing: testing.md
-    - Best Practices: development/best-practices.md
-    - Interfaces: development/interfaces.md
-    - Tool Development: development/tools.md
-    - Test Migration Guide: development/test-migration-guide.md
-    - Troubleshooting: troubleshooting.md
-    - Deployment: deployment.md
-    - Roadmap: roadmap.md
-  - Examples:
-    - Overview: examples/index.md
+    - Setup: development/setup.md
+    - Contributing: development/contributing.md
+    - Testing: development/testing.md
+  - Troubleshooting:
+    - Common Issues: troubleshooting/common-issues.md
+    - FAQ: troubleshooting/faq.md
+  - About:
+    - License: about/license.md
+    - Author: about/author.md