# DashCaddy AI-Native Vision

## The Vision
DashCaddy should be inherently optimized for AI agents to control it.
Users should be able to self-host anything using natural language.

## Core Principles
1. **AI as first-class citizen** — not a bolt-on chatbot, but where the API itself is designed for AI consumption
2. **Natural language → deployment** — "host a Plex server" → running container + reverse proxy + DNS + health check
3. **Agent-friendly API** — structured responses, semantic error codes, state machines, idempotent operations
4. **MCP-native** — DashCaddy should expose itself as an MCP server so any AI agent can control it

## Architecture Layers

### Layer 1: Natural Language Intent Router (NEW)
`POST /api/v1/ai/intent` — Takes natural language, returns structured action plan
- "I want to stream movies" → { category: media-streaming, recommended: [plex, sonarr, radarr] }
- "Set up a password manager" → { category: file-sync, recommended: [vaultwarden] }
- "Block ads on my network" → { category: home-network, recommended: [adguard] }
- "Why is Plex down?" → diagnostics query → { action: health-check, service: plex }

### Layer 2: MCP Server (NEW)
Expose DashCaddy as a Model Context Protocol server so ANY AI agent (Claude, GPT, Gemini, Hermes) can:
- List services, containers, health status
- Deploy/stop/restart apps
- Manage DNS records and Caddyfile routes
- Run diagnostics and get structured results
- Create backups and restore

### Layer 3: Structured Action API (EXISTING — needs enhancement)
366 existing routes already cover the CRUD surface. Enhancement needed:
- Consistent response envelopes (already have `ok()` / `errorResponse()`)
- All error responses include machine-readable codes (DC-086 done — 80 codes)
- Idempotency keys for mutating operations
- Operation receipts (UUID + status tracking)

### Layer 4: Semantic Service Catalog (EXISTING — DC-104)
76 templates with categories, auto-categorization, search.
Enhancement: Add intent tags ("movie streaming", "password manager", "ad blocking")

### Layer 5: Diagnostic Engine (NEW)
`POST /api/v1/ai/diagnose` — Structured troubleshooting
- "Why is X slow?" → checks: CPU, memory, network, disk I/O, container logs
- Returns structured findings with severity + suggested fix
- Can auto-apply fixes with user approval

### Layer 6: Deployment Orchestrator (PARTIAL — DC-103 + wizard)
"Deploy Plex" → full automation chain:
1. Pull image
2. Create container with optimal config
3. Generate Caddyfile route (DC-106)
4. Create DNS record
5. Add to services list
6. Start health monitoring
7. Configure notifications
8. Return ready-to-use URL