# mcmqtt Documentation Site

Professional Astro/Starlight documentation for mcmqtt - the definitive platform for AI coordination.

## Features

- 🚀 **Astro/Starlight** - Fast, accessible, and SEO-optimized documentation
- ⚡ **Alpine.js Integration** - Interactive components and live demos
- 🎨 **Modern Design** - Professional theme with custom branding
- 📱 **Mobile-First** - Responsive design that works everywhere
- 🔍 **Full-Text Search** - Powered by Pagefind for instant results
- 🌐 **Multi-Language Ready** - Internationalization support built-in

## Structure

The site follows the **Diátaxis** documentation framework:

### 📚 **Tutorials** (Learning-oriented)
- Your First MQTT Connection
- Building Agent Networks  
- Real-time Data Streams
- Production Deployment

### 🛠️ **How-to Guides** (Problem-oriented)
- Spawn Dynamic Brokers
- Implement Custom Tools
- Monitor Agent Health
- Scale Horizontally
- Debug Connections

### 📖 **Reference** (Information-oriented)
- MCP Tools API
- MQTT Methods
- Broker Management
- Configuration Options
- Python API

### 🧠 **Explanation** (Understanding-oriented)
- Architecture Deep Dive
- Design Philosophy
- Performance Characteristics
- Security Model
- Technology Comparisons

### 🚀 **Fractal Agent Coordination** (Flagship Feature)
- Overview and Concepts
- Agent Swarm Management
- Browser Testing at Scale
- API Monitoring Networks
- Security Analysis Teams
- Safety & Container Isolation

## Key Pages

### Landing Page (`/`)
- Hero section with live demo
- Feature highlights
- Interactive examples
- Quick start path

### Quick Start (`/guides/quick-start/`)
- 2-minute setup guide
- Zero-config installation
- First MQTT connection
- MCP integration

### Fractal Coordination (`/coordination/overview/`)
- Revolutionary agent architecture
- Hierarchical deployment
- Container isolation
- Real-time coordination
- Production safety

## Development

```bash
# Install dependencies
npm install

# Start development server
npm run dev

# Build for production
npm run build

# Preview production build
npm run preview
```

## Customization

### Theme Colors
- Primary: `#3b82f6` (Blue)
- Accent: `#1e40af` (Dark Blue)
- Success: `#10b981` (Green)
- Warning: `#fbbf24` (Yellow)

### Typography
- Headings: Inter (system font fallback)
- Body: Inter (system font fallback)
- Code: Fira Code (monospace fallback)

### Alpine.js Components
- Interactive demos on homepage
- Live agent coordination visualization
- Performance metrics widgets
- Code example switchers

## Content Guidelines

### Voice & Tone
- **Professional** yet approachable
- **Technical accuracy** with clear explanations
- **Confidence** in mcmqtt's capabilities
- **Helpful** guidance for all skill levels

### Positioning
- mcmqtt as **the definitive AI coordination platform**
- **Revolutionary** fractal agent architecture
- **Enterprise-grade** reliability and safety
- **Zero-config** simplicity with unlimited power

### Content Types
- **Code examples** with copy buttons
- **Mermaid diagrams** for architecture
- **Callout boxes** for important notes
- **Progressive disclosure** for complex topics
- **Interactive demos** where appropriate

## SEO Optimization

- Semantic HTML structure
- Open Graph meta tags
- Twitter Card support
- Structured data (JSON-LD)
- Fast loading times
- Mobile optimization
- Comprehensive internal linking

## Analytics

Privacy-friendly analytics with:
- No external tracking
- Local storage only
- DNT header respect
- GDPR compliance

## Deployment

The site is optimized for:
- **Vercel** (recommended)
- **Netlify** 
- **GitHub Pages**
- **Any static host**

Build outputs to `dist/` directory as static files.

---

**This documentation site positions mcmqtt as the premier solution for AI coordination while remaining accessible to developers at all levels.** 🚀