# Epic: Onboarding (CLI-First, Tiered Install)

## DESCRIPTION
Zero-friction developer onboarding with LIGHTWEIGHT install tiers. Core (`pip install llmhosts`, ~50MB) delivers value in <1 minute. Smart tier adds ML routing. Full tier adds everything. Docker alternative. npx scaffolder for JS/TS devs. Proxy speaks both OpenAI AND Anthropic API formats.

**COURSE CORRECTION (2026-02-14)**: Added lightweight install tiers to solve "3-5GB pip install" problem. Core is 50MB. Smart adds ONNX-based ML (~150MB). Full adds PyTorch (~2GB). npx scaffolder for Phase 2. Anthropic API dialect added. See ADR-008 (REVISED).

## BACKLOG ITEMS

### OB-001: Python Package -- Core Tier (PyPI)
- **Priority**: P0
- **Phase**: 1
- **Status**: BACKLOG
- **Description**: Publishable `llmhosts` package (~50MB). Includes: CLI, FastAPI proxy (OpenAI + Anthropic dialects), rule-based router, TUI dashboard, web dashboard, BYOK management, cache (exact hash). NO ML dependencies (no PyTorch, no sentence-transformers). pyproject.toml with extras for `[smart]` and `[full]`.
- **Acceptance**: `pip install llmhosts` succeeds on Python 3.10+ in <1 minute. `llmhosts --version` works. Proxy serves both `/v1/chat/completions` and `/v1/messages`.
- **Dependencies**: None

### OB-011: Python Package -- Smart Tier
- **Priority**: P0
- **Phase**: 1
- **Status**: BACKLOG
- **Description**: `pip install llmhosts[smart]` (~150MB). Adds: sentence-transformers via ONNX Runtime (not PyTorch), kNN router (FAISS), ModernBERT classifier, vCache verified semantic caching. Install time <3 minutes.
- **Acceptance**: `pip install llmhosts[smart]` succeeds. Three-tier router Tiers 1+2 active. vCache active. No PyTorch installed.
- **Dependencies**: OB-001

### OB-012: Python Package -- Full Tier
- **Priority**: P1
- **Phase**: 1
- **Status**: BACKLOG
- **Description**: `pip install llmhosts[full]` (~2GB). Adds: full PyTorch, FAISS-GPU, Qwen-0.5B router support, vLLM integration support. For power users with GPU.
- **Acceptance**: `pip install llmhosts[full]` succeeds. All three router tiers active. vLLM integration available.
- **Dependencies**: OB-011

### OB-002: `llmhosts serve` Command
- **Priority**: P0
- **Phase**: 1
- **Status**: BACKLOG
- **Description**: Single command starts everything: proxy on localhost:4000 (OpenAI + Anthropic), Ollama discovery, BYOK fallback, TUI dashboard, web dashboard. Detects installed tier and shows appropriate capabilities. Shows first-run instructions including `llmhosts tunnel` for Phase 2.
- **Acceptance**: `llmhosts serve` -> proxy running + dashboard visible in <5 seconds. Prints API endpoints for both dialects.
- **Dependencies**: OB-001, proxy, Ollama discovery

### OB-013: `llmhosts tunnel` Command
- **Priority**: P0
- **Phase**: 2
- **Status**: BACKLOG
- **Description**: THE killer feature command. Auto-detects Tailscale or Cloudflare Tunnel. Creates secure HTTPS endpoint for remote access. `--public` flag for shareable URL with rate limiting + API key auth. Guides installation if neither tool found.
- **Acceptance**: User runs `llmhosts tunnel` -> gets HTTPS URL -> accesses home GPU from anywhere in <30 seconds.
- **Dependencies**: CF-016

### OB-003: Docker Alternative
- **Priority**: P1
- **Phase**: 1
- **Status**: BACKLOG
- **Description**: `docker run -p 4000:4000 --gpus all llmhost/llmhost` as alternative. Pre-built with `[full]` tier. Volume mounts for config. GPU passthrough.
- **Acceptance**: Docker run starts identical experience. Config persists. GPU accessible.
- **Dependencies**: OB-001

### OB-014: npx Scaffolder (Phase 2)
- **Priority**: P1
- **Phase**: 2
- **Status**: BACKLOG
- **Description**: `npx create-llmhosts my-ai-cloud` for JS/TS developers. Interactive wizard: "GPU?", "Cloud providers?", generates docker-compose.yml + config. Separate npm package.
- **Acceptance**: JS/TS developer runs npx command -> answers questions -> gets working docker-compose setup.
- **Dependencies**: OB-003

### OB-004: BYOK Quick Setup (CLI)
- **Priority**: P0
- **Phase**: 1
- **Status**: BACKLOG
- **Description**: `llmhosts keys add openai sk-xxx` / `llmhosts keys add anthropic sk-xxx`. Validates. Stores encrypted locally. Cloud routing available immediately.
- **Acceptance**: Key added in <30 seconds. Validation catches invalid keys. Keys encrypted at rest.
- **Dependencies**: CF-003

### OB-005: Cloud-First Hybrid Onboarding
- **Priority**: P0
- **Phase**: 1
- **Status**: BACKLOG
- **Description**: Value starts immediately via cloud API routing (BYOK). Local Ollama discovered in parallel. Traffic shifts to local as models become available. Never a "waiting for setup" state.
- **Acceptance**: User with only BYOK gets responses immediately. User with Ollama gets local routing immediately. Mixed users see gradual shift.
- **Dependencies**: CB-001, CF-001, CF-003

### OB-006: Model Recommendation Flow
- **Priority**: P1
- **Phase**: 1
- **Status**: BACKLOG
- **Description**: If no local models found: hardware-aware suggestion. "You have 12GB VRAM. Run: `ollama pull llama3.2:8b`." Also suggests `pip install llmhosts[smart]` if on core tier.
- **Acceptance**: Suggestions appear in dashboard. Recommendations match hardware. Tier upgrade suggested when appropriate.
- **Dependencies**: CF-002, CF-005

### OB-007: Web Signup (Phase 2)
- **Priority**: P1
- **Phase**: 2
- **Status**: BACKLOG
- **Description**: Web signup for cloud dashboard, multi-device mesh coordination, Pro tier features. NOT required for local use.
- **Acceptance**: User creates account, links local instance, preferences sync.
- **Dependencies**: Auth system

### OB-008: Security Trust Page
- **Priority**: P1
- **Phase**: 1
- **Status**: BACKLOG
- **Description**: /security page: what LLMHosts does, what it does NOT access, data flow, open source links. Addresses "is this mining crypto?" concern.
- **Acceptance**: Clear security explainer. Links to source code. Data flow diagram.
- **Dependencies**: Documentation

### OB-009: Post-Install Verification
- **Priority**: P0
- **Phase**: 1
- **Status**: BACKLOG
- **Description**: `llmhosts doctor` -- verify: Ollama reachable, cloud keys valid, proxy responding, cache operational, installed tier capabilities. Shows upgrade recommendations.
- **Acceptance**: Green checkmarks per component. Fix suggestions. Tier upgrade suggestions.
- **Dependencies**: OB-002

### OB-010: Multi-Device Setup Guide
- **Priority**: P1
- **Phase**: 2
- **Status**: BACKLOG
- **Description**: Guide for `llmhosts tunnel` setup + multi-device mesh. Shows how to access home GPU from laptop.
- **Acceptance**: User follows guide -> accesses home GPU from laptop. Dashboard shows both devices.
- **Dependencies**: CF-016, CF-017
