# Grounding Hub

> The single place to understand what LLMHosts delivers, to whom, and how we know it works.

This directory consolidates every user journey, success criterion, persona, design principle, and edge case into one navigable structure. All future work must align with these documents.

---

## Quick Navigation

| Need | Go to |
|------|-------|
| What does the user experience? | [journeys/](journeys/) |
| How do we know it works? | [success-criteria/](success-criteria/) |
| Who are we building for? | [personas/](personas/) |
| What rules govern our design? | [principles/](principles/) |
| What weird stuff have we seen? | [edge-cases/](edge-cases/) |

---

## Directory Structure

```
docs/grounding/
├── README.md                          ← you are here
├── journeys/
│   ├── README.md                      ← journey index + cross-reference map
│   ├── 01-first-install-windows.md    ← RTX 4090, Cursor, port conflicts
│   ├── 02-first-install-macos.md      ← Apple Silicon, unified memory
│   ├── 03-cursor-power-user.md        ← IDE port-squatting, IPv6 bridge
│   ├── 04-multi-machine.md            ← home GPU from laptop (relay)
│   ├── 05-team.md                     ← 5-person startup, Hive pooling
│   ├── 06-graceful-degradation.md     ← resilience, always-start guarantee
│   ├── 07-marketplace-operator.md     ← earn from spare GPU cycles
│   └── 08-relay-tunnel.md             ← relay-specific journey (ADR-009)
├── success-criteria/
│   ├── README.md                      ← master criteria index
│   ├── product-level.md               ← PRD success metrics (15K users, $19K MRR)
│   ├── feature-level.md               ← F-001 through F-020+ acceptance criteria
│   ├── phase-level.md                 ← Phase 1-5 acceptance criteria
│   ├── relay-level.md                 ← ADR-009 relay success criteria
│   └── performance-targets.md         ← latency, throughput, binary size targets
├── personas/
│   ├── README.md                      ← persona index + JTBD summary
│   ├── solo-dev-sarah.md              ← Free → Pro, tunnel conversion trigger
│   ├── team-lead-tomas.md             ← Team $49/seat, Hive activation
│   ├── privacy-first-priya.md         ← Local-only, PII detection
│   └── enterprise-eva.md              ← SOC2, SSO, audit logs
├── principles/
│   └── README.md                      ← 6 design principles + brand values
└── edge-cases/
    └── README.md                      ← master edge case catalog
```

---

## Source Documents

This hub consolidates content from 22 documentation artifacts across 7 tiers:

| Tier | Source | What it contributes |
|------|--------|-------------------|
| **Journey** | `docs/gpu-as-api/user-success-journeys.md` | 7 user journeys, edge cases table |
| **Criteria** | `docs/business/prd.md` §5 | Feature acceptance criteria (F-001 → F-020+) |
| **Criteria** | `docs/roadmap/phase5-acceptance.md` | Phase 5A/B marketplace criteria |
| **Criteria** | `docs/architecture/adr-009-relay-tunnel.md` | Relay success criteria + performance targets |
| **Persona** | `docs/business/personas-jtbd.md` | 4 personas, JTBD framework, priority matrix |
| **Vision** | `.hive/soul.md` | Behavioral guidelines, values, tone |
| **Vision** | `.hive/identity.md` | Product identity, architecture summary |
| **Architecture** | `docs/architecture/user-flows.md` | 5 Mermaid flowcharts |
| **Testing** | `docs/testing/MASTER-E2E-PLAN.md` | Full capability index, round strategy |
| **Testing** | `docs/testing/P5-full-test-guide.md` | Step-by-step execution guide |
| **Business** | `docs/business/lean-canvas.md` | Market gap, UVP, revenue model |
| **Code** | `llmhosts/up.py` | 5-phase pipeline implementation |
| **Code** | `frontend/public/install.sh` | Zero-friction installer (Linux/macOS) |
| **Code** | `frontend/public/install.ps1` | Zero-friction installer (Windows) |
| **Ops** | `docs/SSOT-AND-HANDOFF.md` | Handoff protocol, read order |
| **Ops** | `AGENTS.md` | Universal grounding document |

---

## Governance

1. **Any new feature** must map to at least one journey and one persona
2. **Any architecture decision** must include success criteria aligned to journeys
3. **Any PR** should reference which journey it serves in the description
4. **Quarterly review**: audit all journeys against real user feedback, update edge cases
5. **Cascade rule**: changes here propagate to `AGENTS.md`, `CLAUDE.md`, and `docs/SSOT-AND-HANDOFF.md`
