From 7515dac246630d0f36bca7b5b90ef30fdee837a6 Mon Sep 17 00:00:00 2001
From: kenpat <kenpat7177@gmail.com>
Date: Thu, 18 Jun 2026 21:08:36 +0000
Subject: [PATCH] Add build guide: AI-assisted and manual paths

---
 build-guide/README.md | 52 +++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 52 insertions(+)
 create mode 100644 build-guide/README.md

diff --git a/build-guide/README.md b/build-guide/README.md
new file mode 100644
index 0000000..749e17f
--- /dev/null
+++ b/build-guide/README.md
@@ -0,0 +1,52 @@
+# KiteStacks Build Guide
+
+This guide walks you through rebuilding the entire KiteStacks homelab from scratch on a blank machine. Two paths are available — choose the one that fits how you work.
+
+---
+
+## Choose Your Path
+
+### Path A — With AI (Claude Code)
+You provide the high-level goals, Claude Code writes the configs, debugs the errors, and explains every decision. Fastest path. Best for learning while doing.
+
+→ [Build with AI](./with-ai/README.md)
+
+### Path B — Manual (No AI)
+Step-by-step instructions you follow yourself. Every command, every config, every file. Best for deep understanding and exam prep (answering "how does this work" in interviews).
+
+→ [Build Manually](./without-ai/README.md)
+
+---
+
+## Prerequisites (Both Paths)
+
+Before starting either path, have the following ready:
+
+| Requirement | Details |
+|-------------|---------|
+| A Linux machine | Ubuntu 24.04+ or CachyOS/Arch recommended. At least 16GB RAM, 500GB SSD |
+| A Cloudflare account | Free tier is fine. You need a domain pointed to Cloudflare |
+| A domain name | Any registrar works — point nameservers to Cloudflare |
+| A Hetzner account (optional) | For the cloud replica (kscloud1). CAX11 or CX22 works |
+| A Tailscale account | Free tier — needed for the private overlay network |
+| Docker + Docker Compose | Install before starting either path |
+
+---
+
+## High-Level Build Order
+
+Regardless of which path you take, build in this order:
+
+```
+1. Docker + networking foundation
+2. Cloudflare Tunnel (cloudflared)
+3. Authentik (SSO identity provider)
+4. Core services (Portainer, Forgejo, BookStack)
+5. Monitoring (Prometheus, Node Exporter, Grafana)
+6. Application services (Karakeep, Kavita, OSTicket)
+7. AI services (Open WebUI, LiteLLM)
+8. Portal (homepage + metrics API)
+9. kscloud1 cloud replica
+```
+
+Each layer depends on the one before it. Don't skip ahead.