Add cascade-delete finalizer to stateless apps; document the distinction

apps/demo.yaml

@@ -24,6 +24,13 @@ kind: Application
 metadata:
   name: demo
   namespace: argocd
+  # Without this finalizer, deleting this Application object only makes
+  # Argo CD forget about its resources — the namespace, Deployment, and
+  # Service would keep running, orphaned and unmanaged. This finalizer
+  # makes deletion cascade: remove apps/demo.yaml from Git, and everything
+  # this Application deployed is actually torn down too.
+  finalizers:
+    - resources-finalizer.argocd.argoproj.io
 spec:
   project: default
 

apps/longhorn.yaml

@@ -16,6 +16,13 @@ kind: Application
 metadata:
   name: longhorn
   namespace: argocd
+  # Deliberately NO resources-finalizer.argocd.argoproj.io here, unlike
+  # apps/demo.yaml and apps/metallb.yaml. Longhorn's CRDs (Volumes, Replicas,
+  # Engines) represent real data, not just running Pods — cascade-deleting
+  # this Application would tell Longhorn to tear down every volume and
+  # replica in the cluster along with it. Removing apps/longhorn.yaml from
+  # Git should be a rare, deliberate act, confirmed by hand
+  # (see docs/09-growing-up.md), never an accidental one-line prune.
 spec:
   project: default
 

apps/metallb.yaml

@@ -18,6 +18,13 @@ kind: Application
 metadata:
   name: metallb
   namespace: argocd
+  # Without this finalizer, deleting this Application object only makes
+  # Argo CD forget about its resources — MetalLB's Pods, CRDs, and our
+  # BGPPeer/BGPAdvertisement would keep running, orphaned. This finalizer
+  # makes deletion cascade properly. Safe here because MetalLB holds no
+  # data of its own — contrast with apps/longhorn.yaml below.
+  finalizers:
+    - resources-finalizer.argocd.argoproj.io
 spec:
   project: default
 

docs/08-adding-new-apps.md

@@ -88,6 +88,33 @@ addresses listed in [`docs/network.md`](network.md), and add a row for it
 there once it's up — that file only stays useful if every app that gets an
 address shows up in it.
 
+## Removing an app
+
+The reverse of adding one: delete `apps/<name>.yaml` and `apps/<name>/`,
+commit, and push. The app-of-apps notices the missing Application manifest
+and prunes the `Application` object itself — but that alone does **not**
+delete what that Application deployed. Argo CD only cascades an
+Application's deletion into deleting its managed resources (namespace,
+Deployment, Service, everything) if that Application carries this
+finalizer:
+
+```yaml
+metadata:
+  finalizers:
+    - resources-finalizer.argocd.argoproj.io
+```
+
+Without it, the resources are simply orphaned — still running, but no
+longer tracked by Argo CD or described anywhere in Git. `apps/demo.yaml`
+and `apps/metallb.yaml` both carry this finalizer. `apps/longhorn.yaml`
+deliberately does **not** — see the comment in that file for why cascading
+a storage layer's deletion is a different, much higher-stakes decision than
+cascading a stateless app's.
+
+> **Ask Claude:** "what would happen right now if I deleted
+> `apps/longhorn.yaml` and it had this finalizer?" before you ever add one
+> to an app that holds real data.
+
 ## Checklist
 
 - [ ] New app's manifests live in `apps/<name>/`