docs(deploy): clarify Git backup and recovery

deploy/charts/buzz/README.md

@@ -207,10 +207,17 @@ Save these. Losing any of them is data loss. See NOTES.txt printed by `helm inst
 
 1. `BUZZ_RELAY_PRIVATE_KEY` — relay identity. Rotating it = new identity (federation peers will not recognize the relay).
 2. PostgreSQL database — the canonical event store.
-3. S3 bucket — media blobs (chart default bucket: `buzz-media`).
-4. Git PVC — repo on-disk state served by the relay's git endpoint.
+3. Complete S3 bucket — the durable source of truth for media plus Git packs, manifests, and manifest pointers (chart default bucket: `buzz-media`).
+4. Git PVC — optional scratch data and a process-local pack cache. Its cache contents are not reused after a relay restart, and it is not a repository backup.
 5. Owner private key — held by the operator, not by this chart. Restore by re-installing with the same `ownerPubkey`.
 
+Stop write traffic while taking the PostgreSQL and object-store snapshots when
+possible. If the storage provider only supports ordered live snapshots, capture
+PostgreSQL before the object store. After a restore, start an isolated relay and
+perform an authenticated clone, then compare the expected refs, commits, and
+trees. A healthy pod, database row counts, object counts, or a restored Git PVC
+do not prove repository recovery.
+
 ## Honest limitations (v1)
 
 - **Bundled MinIO is eval-only.** The quickstart profile runs an in-cluster

deploy/charts/buzz/templates/NOTES.txt

@@ -47,10 +47,15 @@
   1. BUZZ_RELAY_PRIVATE_KEY — relay identity. Rotating it = identity change;
      federation peers will treat the relay as a new identity.
   2. PostgreSQL database{{ if .Values.postgresql.enabled }} ({{ .Release.Name }}-postgresql PVC){{ end }}
-  3. S3 bucket "{{ .Values.s3.bucket }}" — media blobs
-  4. Git PVC ({{ include "buzz.fullname" . }}-git) — repo on-disk state
+  3. Complete S3 bucket "{{ .Values.s3.bucket }}" — source of truth for media
+     plus Git packs, manifests, and manifest pointers
+  4. Git PVC ({{ include "buzz.fullname" . }}-git) — optional scratch and a
+     process-local pack cache; it is not a repository backup
   5. Owner private key (held by the operator, NOT the chart) — restore by
      re-installing with the same ownerPubkey.
+  Stop write traffic while taking data snapshots when possible. If only ordered
+  live snapshots are available, capture PostgreSQL before the object store.
+  Test a restore with an authenticated clone and compare refs, commits, and trees.
 
 ──────────────────────────────────────────────────────────────────────────────
   Degradation warnings

deploy/compose/README.md

@@ -46,6 +46,27 @@ keypair.
 
 Run `./run.sh backup-hint` for the backup checklist.
 
+## Backup and recovery
+
+Back up `.env`, PostgreSQL, Redis, and the complete configured MinIO/S3 bucket
+from the same maintenance window. Stop the stack while taking the data
+snapshots when possible. If the storage provider only supports ordered live
+snapshots, capture PostgreSQL before the object store. The object store is the
+durable source of truth for Git packs, manifests, and manifest pointers as well
+as media.
+
+The `buzz-git-data` volume holds only scratch data and a process-local pack
+cache. Its cache contents are not reused after a relay restart, and the volume
+is not a repository backup.
+
+A recovery test must restore the coordinated data into an isolated stack and
+perform an authenticated clone. Compare the recovered branch and tag refs,
+commits, and trees with values recorded before the backup. Container health,
+database row counts, object counts, or a restored `buzz-git-data` volume do not
+prove that a repository can be read. See
+[`docs/git-on-object-storage.md`](../../docs/git-on-object-storage.md) for the
+storage model.
+
 ## Validation
 
 Before sharing an install link publicly, verify a fresh install with:

deploy/compose/run.sh

@@ -42,11 +42,20 @@ Back up these before upgrades and on a regular schedule:
 - deploy/compose/.env, especially BUZZ_RELAY_PRIVATE_KEY, DB/Redis/S3 secrets, and BUZZ_GIT_HOOK_HMAC_SECRET
 - The owner private key if bootstrap generated one for RELAY_OWNER_PUBKEY
 - Postgres data (prefer pg_dump or a quiesced volume snapshot)
-- MinIO/S3 bucket contents for media and git objects
-- buzz-git-data volume (BUZZ_GIT_REPO_PATH=/data/git)
+- Redis data (prefer an RDB export or a quiesced volume snapshot)
+- The complete configured MinIO/S3 bucket; it is the source of truth for media
+  and Git packs, manifests, and manifest pointers
+- buzz-git-data holds only Git scratch data and a process-local pack cache;
+  backing it up is optional, its cache is not reused after a relay restart,
+  and it cannot replace the object-store backup
 - Caddy data/config volumes if using compose.caddy.yml
 
-Keep Postgres + object/git state snapshots from the same maintenance window.
+Stop the stack while taking data snapshots when possible. If the storage provider
+only supports ordered live snapshots, capture Postgres before the object store.
+Keep Postgres, Redis, and object-store snapshots from the same maintenance window.
+After a restore, start an isolated relay and perform an authenticated clone, then
+compare the expected refs, commits, and trees. A healthy container or restored
+buzz-git-data volume alone does not prove Git recovery.
 MSG
 }