Initial commit: GitOps Starter Pack

A teaching-first, single-cluster GitOps setup: Talos Linux + Argo CD with
an app-of-apps layout, MetalLB pre-installed for real LoadBalancer IPs on
bare metal, a demo app, and a progressive docs/ walkthrough with a
CLAUDE.md tutor persona and guided bootstrap checklist.

Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>

README.md

@@ -0,0 +1,108 @@
+# GitOps Starter Pack
+
+A minimal, real, working GitOps setup for a single Kubernetes cluster —
+built to teach, not just to run. If you've never touched Kubernetes,
+GitOps, Talos, or Argo CD before, this is meant to get you from a bare
+machine to a working cluster you actually understand, not just one you
+copy-pasted into existence.
+
+## Who this is for
+
+You're comfortable with computers: the command line, SSH, servers,
+networking, editing config files. You have **never** used Kubernetes,
+GitOps, Argo CD, or Talos, and none of the jargon is familiar yet. This
+repo assumes that, exactly. Every cloud-native term is defined in plain
+English the first time it appears, and a full glossary lives at
+[`docs/glossary.md`](docs/glossary.md).
+
+## The mental model, briefly
+
+Traditionally, you configure a server by SSHing in and changing things by
+hand. Nothing records *why* it looks the way it does except your memory and
+shell history. This repo takes a different approach:
+
+1. **Kubernetes** runs your applications, and you tell it the state you
+   want ("one copy of this running") rather than the steps to get there —
+   it keeps making that true, continuously.
+2. **Talos Linux** is the operating system underneath — built for nothing
+   but running Kubernetes, configured the same declarative way, with no
+   SSH or shell to log into.
+3. **Argo CD** watches this Git repository and keeps the cluster matching
+   whatever it finds here. You stop running `kubectl apply` by hand; you
+   edit a file, commit, push, and Argo CD applies it for you.
+4. **App-of-apps** is how this repo is organized so that adding a new app
+   later is "add a file," never a new procedure.
+5. **MetalLB** gives apps in this cluster real IP addresses on your own
+   network — something a cloud provider would normally do for you, and
+   bare metal doesn't have on its own.
+
+Git becomes the one place that's actually true. If you want the full
+picture with diagrams before doing anything, start with
+[`docs/00-what-is-all-this.md`](docs/00-what-is-all-this.md).
+
+## What's in here
+
+```
+talos/    → Talos machine config + bootstrap guide (the OS layer)
+argocd/   → Argo CD install + the one manifest you apply by hand
+apps/     → Everything Argo CD manages from here on — demo app, MetalLB,
+            and wherever you add new apps
+docs/     → The numbered, progressive guide you should actually read
+```
+
+## Prerequisites
+
+- One machine (physical or VM) to become your cluster node
+- `talosctl`, `kubectl`, and the `argocd` CLI installed locally
+- A GitHub account, and your own fork of this repo
+
+Full detail, with install commands: [`docs/01-prerequisites.md`](docs/01-prerequisites.md).
+
+## The path through this repo
+
+Read these in order. Each is short — one concept per file.
+
+1. [`docs/00-what-is-all-this.md`](docs/00-what-is-all-this.md) — the mental model and architecture, before touching a terminal
+2. [`docs/01-prerequisites.md`](docs/01-prerequisites.md) — install the tools, get a target machine ready
+3. [`docs/02-talos-bootstrap.md`](docs/02-talos-bootstrap.md) — turn that machine into a Kubernetes node
+4. [`docs/03-installing-argocd.md`](docs/03-installing-argocd.md) — install Argo CD into the cluster
+5. [`docs/04-app-of-apps.md`](docs/04-app-of-apps.md) — apply the one manifest that hands control to Git
+6. [`docs/05-metallb.md`](docs/05-metallb.md) — give apps real IP addresses on your network
+7. [`docs/06-your-first-change.md`](docs/06-your-first-change.md) — edit a file, push, watch it deploy itself
+8. [`docs/07-adding-new-apps.md`](docs/07-adding-new-apps.md) — add something of your own
+9. [`docs/08-growing-up.md`](docs/08-growing-up.md) — next steps: more nodes, ingress, secrets management
+10. [`docs/glossary.md`](docs/glossary.md) — every term, plain English, for reference throughout
+11. [`docs/network.md`](docs/network.md) — the running log of every real IP address in your cluster, kept current as you go
+
+Prefer a single condensed list you can work through step by step with
+Claude, checking items off as you go? Use
+[`docs/checklist.md`](docs/checklist.md) instead — see the next section.
+
+## Learning this with Claude
+
+This repo is meant to be read with an AI assistant open alongside it. The
+root [`CLAUDE.md`](CLAUDE.md) primes Claude to act as a patient tutor for
+this exact repo — teaching concepts in order, explaining *why* before
+*how*, and checking your understanding rather than just handing you
+commands. Throughout the docs, you'll see call-outs like:
+
+> **Ask Claude:** ...
+
+Take those. They mark places where pausing to ask a follow-up question
+pays off more than plowing ahead.
+
+If you'd rather be walked through the whole bootstrap interactively,
+start a conversation with Claude in this repo and say something like
+*"walk me through the checklist in docs/checklist.md"* — it will go
+step by step, wait for your output at each one, and help you debug before
+moving on.
+
+## A note on scope
+
+This repo deliberately does **not** ship ingress, TLS/cert-manager, or
+secrets management in v1 — they're real next steps, documented in
+[`docs/08-growing-up.md`](docs/08-growing-up.md), left out so the core
+loop stays small enough to fully understand first. This repo is also
+**public** — never commit plaintext secrets, credentials, or private keys
+to it; see that same doc for how to handle secrets properly once you need
+them.