# GitHub as SSOT — Handoff for Another AI or Dev Instance

**Purpose:** Single document for any AI dev instance or human to pick up work. GitHub is the **single source of truth**; this file is the index and protocol. Read this first when joining or switching context.

---

## 1. What This Repo Is

- **Product:** LLMHosts.com — turn your home GPU into production AI infrastructure (SaaS, all pay; no open source).
- **Stack:** Python 3.12 + FastAPI (proxy), Next.js 16 + TypeScript (frontend), SQLite/Prisma. Deploy: Docker Compose + Traefik.
- **SSOT:** All task state, priorities, and execution order live in **GitHub**: issues, Project #5, milestones, labels. No duplicate trackers.

---

## 2. Where State Lives (GitHub)

| What | Where |
|------|--------|
| **Open work** | `gh issue list --state open` |
| **In progress / board** | Project #5 (LLMHosts.com Roadmap): `gh project item-list 5 --owner LookNoHandsMom` |
| **Execution order** | Issue #325 (Master execution playbook) — body + comments list order and child issues |
| **Milestones** | Conversion wave 1 (9), E2E Round 1 Alienware (10), E2E Round 2 diversity (11), POC Testing Phase (7), Phase 5 (8), MVP/Production (5,6) |
| **Labels** | priority:high/medium, type:feature/test/docs/chore, epic:*, e2e-test, testing, human, P0-blocker, P1-critical, conversion, alienware, mac-mini, multi-gpu |
| **CI** | `gh run list --limit 5` |

**First commands to run in any new session:**
```bash
gh issue list --state open --limit 25
gh pr list --state open
gh project item-list 5 --owner LookNoHandsMom --limit 30
gh run list --limit 5
git status && git log --oneline -5
```

---

## 3. Key Docs (Read Order for New Context)

1. **AGENTS.md** (repo root) — Project identity, architecture, commands, session protocol.
2. **CLAUDE.md** (repo root) — Full architecture, build/test, patterns (for Claude Code).
3. **This file** — SSOT and handoff protocol.
4. **docs/testing/README.md** — Where E2E strategy and execution live.
5. **docs/testing/MASTER-E2E-PLAN.md** — Full capability index, Round 1/2, gap analysis, §10 runner checklist.
6. **docs/testing/P5-full-test-guide.md** — Step-by-step execution (Part A, Phase 0, Part B, Part C).
7. **docs/marketing/2026-02-27-saas-conversion-profitability-playbook.md** — Conversion levers and GitHub issue index.
8. **docs/plans/2026-02-27-gpu-remit-and-user-control.md** — GPU remit, read-only, user control, per-GPU opt-in.
9. **docs/plans/2026-02-27-all-saas-all-pay.md** — All SaaS, all pay; no open source.
10. **docs/planning/github-project-5-views.md** — How to use Project #5 (views, filters, fields).

---

## 4. What Is Done vs What Is Next (as of Last Sync)

**Done (closed in GitHub):**
- Conversion micro #333–#344 (pricing, anchor, transparent, value metrics, FAE, 90s CTA, outcome CTAs, social proof, checkout, dunning, NRR, trust).
- Conversion epics #326–#332: implemented via micro; epics may stay open as containers.
- OpenClaw #345–#347 (20 searches, gaps doc).
- Research #348 (research log doc).
- Remit #350–#352 (local_only config + tunnel no-op; onboarding copy; remit_allowlist config).
- GitHub Pro #349, #353 (align, Project 5 views doc).
- **#415** — Bulletproof customer experience (ProgressReporter, preflight, dashboard SSE, remote testing, GPU Respect). Closed #416 (Ollama abstraction), #417 (GPU Respect), #418 (Just Works epic). CI: e2e-frontend timeout increased to 25m; job still non-blocking until secrets #372.
- **#419 + PR #421** — E2E CI: run smoke-only (security-headers + accessibility) so job completes under 15m; seed optional when SEED_* unset; POST /api/marketplace/route API tests added.
- **PR #429** — WCAG 2.2 AA fixes: `<Link><Button>` nesting removed (target-size), `text-gray-500/600` → `text-gray-400` on auth footer/docs sidebar/CodeBlock (contrast), hero CTA gap-6 (target-offset). Surfaced by E2E axe-core smoke suite.
- **PR #430 (closes #290 Phase 5B)** — Marketplace auto-removal: `POST /api/internal/marketplace/auto-remove` route (protected by `INTERNAL_MARKETPLACE_SECRET`) disables nodes below 30% 30-day uptime. Python `_check_and_remove_low_reputation()` in `llmhosts/marketplace/probes.py` calls it after each probe cycle. Phase 5 marketplace is now functionally complete: probes, billing (80/20 split), reputation scoring, auto-removal, Stripe Connect KYC, operator/buyer dashboards, node catalog + routing APIs. Tests: 2413 Python + 808 frontend (zero failures).

**Open / Next:**
- **#325** — Master playbook (CLOSED; reference for order). Track remaining in open issues.
- **#319** — E2E Master Plan tracking.
- **#359** — [E2E] Run Round 1 Alienware full battery (P0-blocker, human/external runner).
- **#360–#362** — [E2E] Round 2 Mac Mini, multi-GPU, large GPU (human runner).
- **#363** — [E2E] Gap analysis after Round 2 + Production readiness checklist.
- **#354–#358** — E2E automation (App Auth, dashboard routes, API Keys, CLI, Proxy); coverage added in repo; issues open until Round 1 run confirms.
- **#320–#324** — GPU remit, per-GPU opt-in, read-only, AI assistant, at-capacity fallback (backlog).
- ~~**Optional:** Dispatcher filtering by `config.remit.remit_allowlist`~~ **Done:** Dispatcher filters backends by `remit_allowlist` when non-empty (see `BackendDispatcher(remit_allowlist=...)` and `docs/plans/2026-02-27-gpu-remit-and-user-control.md`).

**Runner-owned (need real hardware):** #359, #360, #361, #362. Execution: follow docs/testing/P5-full-test-guide.md and MASTER-E2E-PLAN §10; report results and unresolved issues in GitHub (recap doc + comment on #319 or issue).

---

## 5. Sync Protocol (Keep GitHub Reflective)

- **After doing work:** Close the issue with a comment (what was done, where). If it’s part of an epic, add a comment to the epic. Update #325 with a progress comment if it’s a major batch.
- **After changing architecture or conventions:** Update AGENTS.md and CLAUDE.md; if E2E or conversion related, update playbook or MASTER-E2E-PLAN.
- **Before claiming done:** Run `pytest tests/ -q` and `cd frontend && npm run test -- --run`; ensure no regressions. For E2E runs, follow P5 guide and record results in GitHub.

---

## 6. Handoff to Another AI Dev

When switching to another AI dev instance:

1. **No local state.** Everything needed is in the repo + GitHub. No secrets in repo; API keys/passwords from project owner or env.
2. **Start here:** Read this file, then AGENTS.md, then `gh issue list --state open` and issue #325.
3. **Pick next:** Highest-priority open issue (by label/milestone) or continue from #325’s list. For E2E Round 1/2, the runner must have access to the machine (Alienware, etc.) and test account password; execution is in docs/testing/.
4. **Loop:** Do work → close/comment issues → update docs if needed → push → next item. Keep GitHub and this file in sync.

---

*Last sync: 2026-03-08 (session 051). See git log and issue #325 comments. This file is updated when SSOT structure or handoff steps change.*
