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>

docs/checklist.md

@@ -0,0 +1,90 @@
+# Guided bootstrap checklist
+
+A single-page, ordered checklist covering the entire path from bare
+machine to a working GitOps loop. It's meant to be worked through **with
+Claude**, one item at a time — ask Claude to walk you through this list,
+and it will run each step with you, wait for your output, confirm it
+worked, and only then move to the next one. See `CLAUDE.md` at the repo
+root for how Claude is primed to do this.
+
+Each item names the doc it's drawn from, in case you want the full
+explanation before or after running it. Replace `<NODE_IP>`,
+`YOUR_GITHUB_USERNAME`, and the MetalLB IP addresses with your real values
+throughout — Claude will remind you if you paste a command still
+containing a placeholder, and will ask you for the IP addresses directly
+in Phase 5 rather than guessing them.
+
+## Phase 1 — Prerequisites ([`01`](01-prerequisites.md))
+
+- [ ] Target machine chosen, reachable on the network, with a stable
+      (ideally DHCP-reserved) IP address
+- [ ] Talos amd64 ISO downloaded, machine booted from it, sitting at the
+      boot screen
+- [ ] `talosctl version --client` runs successfully
+- [ ] `kubectl version --client` runs successfully
+- [ ] `argocd version --client` runs successfully
+- [ ] Repo forked on GitHub and cloned locally as **your own copy**
+
+## Phase 2 — Talos bootstrap ([`02`](02-talos-bootstrap.md), [`talos/README.md`](../talos/README.md))
+
+- [ ] `talosctl gen config gitops-starter https://<NODE_IP>:6443 --output-dir _out --config-patch-control-plane @talos/patch-controlplane.yaml` run — `_out/controlplane.yaml`, `worker.yaml`, `talosconfig` exist
+- [ ] `TALOSCONFIG` exported (or `talosctl config endpoint`/`node` set) to `_out/talosconfig`
+- [ ] `talosctl apply-config --insecure --nodes <NODE_IP> --file _out/controlplane.yaml` run, node rebooted
+- [ ] `talosctl bootstrap --nodes <NODE_IP>` run — **exactly once**
+- [ ] `talosctl kubeconfig --nodes <NODE_IP> .` run, `KUBECONFIG` pointed at the result
+- [ ] `kubectl get nodes` shows one node, `Ready`
+
+## Phase 3 — Argo CD install ([`03`](03-installing-argocd.md), [`argocd/README.md`](../argocd/README.md))
+
+- [ ] `kubectl create namespace argocd`
+- [ ] `kubectl apply --server-side -n argocd -f https://raw.githubusercontent.com/argoproj/argo-cd/stable/manifests/install.yaml`
+- [ ] `kubectl -n argocd wait --for=condition=Available --timeout=300s deployment --all` completes
+- [ ] Initial admin password retrieved
+- [ ] `kubectl -n argocd port-forward svc/argocd-server 8080:443` running in its own terminal
+- [ ] `argocd login localhost:8080 --username admin --password <pw> --insecure` succeeds
+
+## Phase 4 — Hand the cluster to Git ([`04`](04-app-of-apps.md))
+
+- [ ] `spec.source.repoURL` fixed in all three placeholder files: run
+      `grep -rl YOUR_GITHUB_USERNAME .` to find them
+      (`argocd/app-of-apps/app-of-apps.yaml`, `apps/demo.yaml`, `apps/metallb.yaml`)
+- [ ] Edit committed and pushed to your fork's `main` branch
+- [ ] `kubectl apply -f argocd/app-of-apps/app-of-apps.yaml`
+- [ ] `argocd app list` shows `app-of-apps`, `Synced`/`Healthy`
+- [ ] `argocd app list` shows `demo` and `metallb`, appeared automatically, both `Synced`/`Healthy`
+- [ ] `kubectl -n demo get pods,svc` shows the demo app's Pod running
+      (Service `EXTERNAL-IP` still `<pending>` — expected for now)
+
+## Phase 5 — MetalLB: real IP addresses ([`05`](05-metallb.md))
+
+- [ ] **Ask Claude** to help pick: a MetalLB pool range, an address for
+      Argo CD's UI, and an address for the demo app — all based on your
+      actual LAN/DHCP setup
+- [ ] `apps/metallb/templates/ipaddresspool.yaml` edited to your real pool range
+- [ ] `apps/demo/service.yaml` edited to your real demo app address
+- [ ] `docs/network.md` updated with the pool range and both addresses (Argo CD's added once patched, below)
+- [ ] Committed, pushed, and synced (`argocd app sync metallb demo`)
+- [ ] `kubectl -n demo get svc demo` shows a real `EXTERNAL-IP`; page loads at `http://<that-address>`
+- [ ] `argocd-server` Service patched to `LoadBalancer` with your chosen Argo CD address (`kubectl -n argocd patch svc argocd-server ...`)
+- [ ] Argo CD UI reachable at `https://<that-address>` with no port-forward running
+
+## Phase 6 — Prove the loop ([`06`](06-your-first-change.md))
+
+- [ ] Edited the `<h1>` text in `apps/demo/configmap.yaml`
+- [ ] Committed and pushed
+- [ ] `argocd app sync demo` (or waited for auto-poll) shows the change applied
+- [ ] Refreshed the browser — new text visible
+- [ ] (Optional) Triggered self-heal: hand-edited the ConfigMap with `kubectl patch`, confirmed Argo CD reverted it
+
+## You're done when
+
+Every box above is checked, you've watched a change you made in a text
+editor show up in a browser without ever running `kubectl apply` yourself
+for it, and you can explain in your own words what happened between "git
+push" and the page updating. If you can't yet, that's the sign to ask
+Claude for a walkthrough of whichever phase felt shaky before calling this
+finished.
+
+From here: [`07-adding-new-apps.md`](07-adding-new-apps.md) to add
+something of your own, or [`08-growing-up.md`](08-growing-up.md) for the
+bigger next steps (more nodes, ingress, secrets management).