# User Success Journeys

> Every journey ends with: "It just works." No exceptions.

These journeys define the customer experiences LLMHosts must deliver. They are the north star for every feature, architecture decision, and test plan.

---

## Journey Index

| # | Journey | Primary Persona | Key Feature | Status |
|---|---------|----------------|-------------|--------|
| [01](01-first-install-windows.md) | First Install (Windows, RTX 4090) | Solo Dev Sarah | `llmhosts up` autopilot | Verified 2026-03-08 |
| [02](02-first-install-macos.md) | First Install (macOS, Apple Silicon) | Solo Dev Sarah | Auto-install Ollama + model | Designed |
| [03](03-cursor-power-user.md) | Cursor IDE Power User | Solo Dev Sarah | Port conflict resolution | Verified 2026-03-08 |
| [04](04-multi-machine.md) | Multi-Machine Developer | Solo Dev Sarah | Relay tunnel | Designed (needs relay M4) |
| [05](05-team.md) | Team / Small Company | Team Lead Tomas | Hive GPU pooling | Designed |
| [06](06-graceful-degradation.md) | Graceful Degradation | All | Always-start guarantee | Verified 2026-03-08 |
| [07](07-marketplace-operator.md) | Marketplace Operator (Pro) | Power User | Earn from spare GPU | Built (Phase 5 complete) |
| [08](08-relay-tunnel.md) | Relay Tunnel E2E | Solo Dev Sarah | Self-hosted relay | Planned (ADR-009) |

---

## Journey → Feature Traceability

```
Journey 1 (First Install Windows)
  → F-003 Ollama Auto-Discovery
  → F-010 `llmhosts serve` / `llmhosts up`
  → F-012 Hardware Detection
  → Port detection + IPv6 bridge (PR #436)
  → Windows h11 HTTP parser (PR #436)

Journey 2 (First Install macOS)
  → F-003 Ollama Auto-Discovery
  → Auto-install Ollama + model pull (PR #415)
  → Apple Silicon 4GB VRAM offset

Journey 3 (Cursor Power User)
  → Connect-based port detection (PR #436)
  → Specific binding (127.0.0.1 not 0.0.0.0)
  → IPv6 TCP bridge ([::1]:PORT → 127.0.0.1:PORT)

Journey 4 (Multi-Machine)
  → F-013 Tunnel (`llmhosts tunnel` / relay)
  → ADR-009 Self-hosted relay
  → Device Code Auth (RFC 8628)
  → Relay milestones M1-M5 (#439-#443)

Journey 5 (Team)
  → Hive Mode GPU pooling
  → F-018 Multi-Device Mesh
  → Team spend dashboard

Journey 6 (Graceful Degradation)
  → Progressive enhancement architecture
  → Proxy always starts (even without internet/tunnel/engine)
  → Automatic reconnection with exponential backoff

Journey 7 (Marketplace Operator)
  → Phase 5 marketplace (PRs #394-#396, #404-#406, #430)
  → Reputation scoring engine
  → Stripe Connect billing
  → Auto-removal (<30% uptime)

Journey 8 (Relay Tunnel)
  → ADR-009 complete flow
  → WSS + yamux + Noise NK
  → Zero-config relay connection
  → device.llmhosts.com URL
```

---

## Cross-Reference: Journey → Test Plan

| Journey | E2E Test Coverage |
|---------|------------------|
| 1 | `docs/testing/P5-full-test-guide.md` Part B (host scenarios) |
| 2 | Round 2: Mac Mini (`#360`) |
| 3 | Verified manually 2026-03-08 (Cursor IDE + 17 ports) |
| 4 | Relay M5 E2E validation (#443) |
| 5 | Team E2E (future) |
| 6 | `docs/testing/P5-full-test-guide.md` Part B (reconnect, concurrent) |
| 7 | `docs/roadmap/phase5-acceptance.md` (load test, probes, uptime) |
| 8 | Relay M4-M5 E2E (#442, #443) |

---

## Canonical Source

These individual journey files are the expanded, standalone versions. The original consolidated document lives at `docs/gpu-as-api/user-success-journeys.md`.
