# Architecture Decision Records (ADR) Index

## META
- format: Lightweight ADR (decision, context, options, rationale)
- status: PROPOSED | ACCEPTED | REVISED | SUPERSEDED
- created: 2026-02-13
- updated: 2026-02-14 (COURSE CORRECTION v3.0: ADR-001, 004, 008 REVISED; ADR-002 SUPERSEDED)

## INDEX

| ADR | Title | Status | Decision |
|-----|-------|--------|----------|
| [ADR-001](adr-001-orchestrator-model.md) | Orchestrator Model Selection | **REVISED** (2026-02-14) | ~~kNN-only~~ → **Three-tier hybrid router** (kNN + ModernBERT + Qwen-0.5B), <1GB VRAM |
| [ADR-002](adr-002-inference-engine.md) | Inference Engine Selection | **SUPERSEDED** (2026-02-14) | ~~vLLM + exo + Ollama~~ → **Ollama-primary** ("Ollama Inside"), vLLM real upgrade path, exo LAN-only |
| [ADR-003](adr-003-api-proxy.md) | API Proxy Layer | PROPOSED | LiteLLM with custom Conductor routing strategy + Anthropic dialect adapter |
| [ADR-004](adr-004-security-overlay.md) | Security & Networking Overlay | **REVISED** (2026-02-14) | Phased: **localhost** (Phase 1) → **Tailscale/Cloudflare auto-detect** (`llmhosts tunnel`, Phase 2) → **Headscale** (Hive only, Phase 3) |
| [ADR-005](adr-005-frontend-framework.md) | Frontend Framework | PROPOSED | Next.js + TailwindCSS + shadcn/ui |
| [ADR-006](adr-006-tool-protocol.md) | Tool Integration Protocol | PROPOSED | Model Context Protocol (MCP) |
| [ADR-007](adr-007-container-strategy.md) | Container & Orchestration Strategy | PROPOSED | Docker Compose (dev/small) + K3s (scale) |
| [ADR-008](adr-008-cli-first-distribution.md) | CLI-First Distribution Strategy | **REVISED** (2026-02-14) | Tiered pip install: `llmhosts` (~50MB) / `[smart]` (~150MB) / `[full]` (~2GB) + Docker + npx scaffolder |
| [ADR-009](adr-009-relay-tunnel.md) | Self-Hosted Relay Tunnel | **ACCEPTED** (2026-03-08) | Rust WebSocket relay (yamux + Noise NK) ships in pip wheel via maturin. Replaces Tailscale/Cloudflare as primary tunnel. |
| [ADR-010](adr-010-llmhosts-core-inference-engine.md) | LLMHosts Core Inference Engine | **ACCEPTED** (2026-03-09) | Custom Rust inference engine (CubeCL + cudarc). Replaces Ollama dependency. PagedAttention, continuous batching, phase-split serving, AI-curated models. Supersedes ADR-002. |

## REVISION & SUPERSESSION LOG

| Date | ADR | Old Decision | New Decision | Reason |
|------|-----|-------------|-------------|--------|
| 2026-02-14 (pivot) | ADR-001 | Nemotron-Orchestrator-8B | kNN embedding router | Debate-001 Hole 5: 8B model is bottleneck |
| 2026-02-14 (correction) | ADR-001 | Pure kNN embedding router | **Three-tier hybrid** (kNN + ModernBERT + Qwen-0.5B) | Debate-002: pure kNN kills intelligence. Three-tier fits in <1GB VRAM alongside inference. |
| 2026-02-14 (pivot) | ADR-002 | Three-engine (vLLM + exo + Ollama) | Ollama-primary, vLLM opt-in, exo LAN-only | Debate-001 Holes 6-7: exo WAN dead, model distribution problematic |
| 2026-02-14 (pivot) | ADR-004 | OpenZiti zero-trust overlay | Headscale/WireGuard mesh | Debate-001 Hole 8: OpenZiti operationally disproportionate |
| 2026-02-14 (correction) | ADR-004 | Headscale for all networking | **Phased**: localhost → Tailscale/Cloudflare auto-detect → Headscale (Hive only) | Debate-002: Headscale overkill for personal access. `llmhosts tunnel` IS the killer feature. |
| 2026-02-14 (pivot) | ADR-008 | Platform-first (website + Docker) | `pip install llmhosts` monolithic | Debate-001 Holes 10-13: CLI-first adoption |
| 2026-02-14 (correction) | ADR-008 | Monolithic pip install (3-5GB) | **Tiered install**: core ~50MB, smart ~150MB (ONNX), full ~2GB | Debate-002 Hole 1: monolithic pip is 3-5GB, breaks "value in 3 minutes" |
| 2026-03-08 | ADR-004 | Tailscale/Cloudflare primary (Phase 2), Headscale (Phase 3) | **Self-hosted Rust relay** primary; Tailscale/Cloudflare as fallback only; Headscale deprecated | ADR-009: Tailscale ToS prohibits commercial use; Cloudflare = third-party dependency; relay = first-party moat |
| 2026-03-09 | ADR-002 | Ollama-primary ("Ollama Inside"), vLLM opt-in | **Custom Rust engine (LLMHosts Core)**: CubeCL + cudarc, PagedAttention, continuous batching, phase-split, AI model curation | ADR-010: Vendor dependency blocks product quality ceiling; own the full stack for market leadership |
