From d7da4b09f7775276231d0241cfe2700d247728ee Mon Sep 17 00:00:00 2001
From: Lukasz Kasprzak <lukas@labunix.xyz>
Date: Thu, 30 Jul 2026 08:56:34 +0200
Subject: sources: store the snapshot as one compressed archive

Replace the ~1600 raw per-provider files (24 MB) with a single solid
sources/snapshot.tar.gz (6 MB); manifest.tsv + README stay uncompressed
for browsing. The extracted per-provider dirs are now git-ignored;
snapshot-sources.sh gains pack/unpack, and the README documents the
unpack -> refresh -> pack cycle. Distribution-ready: one archive, not a
file tree.
---
 .gitignore                  |  14 ++++++++++++++
 scripts/snapshot-sources.sh |  20 +++++++++++++++++++-
 sources/README.md           |  15 ++++++++++++---
 sources/snapshot.tar.gz     | Bin 0 -> 6417566 bytes
 4 files changed, 45 insertions(+), 4 deletions(-)
 create mode 100644 sources/snapshot.tar.gz

diff --git a/.gitignore b/.gitignore
index e3ae1fd..0e4cf7b 100644
--- a/.gitignore
+++ b/.gitignore
@@ -10,3 +10,17 @@ scripts/.oracle-cache/
 scripts/.wujek-cache/
 sources/*.log
 sources/.*.log
+
+# extracted source snapshot (the committed archive is sources/snapshot.tar.gz;
+# `tar xzf sources/snapshot.tar.gz -C sources` to unpack for regeneration)
+sources/catholic-resources/
+sources/missalemeum/
+sources/litcal/
+sources/getbible/
+
+# OS / editor cruft
+.DS_Store
+*~
+*.swp
+.idea/
+.vscode/
diff --git a/scripts/snapshot-sources.sh b/scripts/snapshot-sources.sh
index e9d6f63..4c8c56c 100755
--- a/scripts/snapshot-sources.sh
+++ b/scripts/snapshot-sources.sh
@@ -11,7 +11,9 @@
 # span or add providers by editing the ranges below and re-running.
 #
 # Usage:  sh scripts/snapshot-sources.sh [provider ...]
-#         providers: cr litcal getbible missalemeum   (default: all)
+#         providers: cr litcal getbible missalemeum   (default: all four)
+#         pack   -- roll the fetched dirs into sources/snapshot.tar.gz (committed)
+#         unpack -- restore the per-provider dirs from sources/snapshot.tar.gz
 set -eu
 
 ROOT=$(cd "$(dirname "$0")/.." && pwd)
@@ -95,6 +97,20 @@ snap_missalemeum() {
 	done
 }
 
+# The committed artifact is sources/snapshot.tar.gz (the raw per-provider dirs
+# are git-ignored). `pack` rolls the fetched dirs into it; `unpack` restores
+# them from it for a regeneration/audit run.
+pack_archive() {
+	echo "packing sources/snapshot.tar.gz ..."
+	tar czf "$SNAP/snapshot.tar.gz" -C "$SNAP" catholic-resources missalemeum litcal getbible
+	echo "  wrote $SNAP/snapshot.tar.gz ($(du -h "$SNAP/snapshot.tar.gz" | cut -f1))"
+}
+unpack_archive() {
+	echo "unpacking sources/snapshot.tar.gz ..."
+	tar xzf "$SNAP/snapshot.tar.gz" -C "$SNAP"
+	echo "  extracted per-provider dirs into $SNAP/"
+}
+
 which=${*:-cr litcal getbible missalemeum}
 for p in $which; do
 	case "$p" in
@@ -102,6 +118,8 @@ for p in $which; do
 		litcal) snap_litcal ;;
 		getbible) snap_getbible ;;
 		missalemeum) snap_missalemeum ;;
+		pack) pack_archive ;;
+		unpack) unpack_archive ;;
 		*) echo "unknown provider: $p" >&2 ;;
 	esac
 done
diff --git a/sources/README.md b/sources/README.md
index b177c3d..f746d29 100644
--- a/sources/README.md
+++ b/sources/README.md
@@ -7,9 +7,18 @@ re-audited offline** if those sites change, move, or disappear — the project's
 25-year-longevity aim. Reading references are facts, not creative works; this is
 a provenance cache, not redistribution of anyone's edition.
 
-Refresh or extend with `sh scripts/snapshot-sources.sh [provider ...]`
-(idempotent: existing non-empty files are skipped). Every file is recorded in
-`manifest.tsv` (path, url, sha256, bytes). First archived **2026-07-29**.
+The data ships as a single compressed archive, **`sources/snapshot.tar.gz`**
+(~6 MB); `manifest.tsv` (path, url, sha256, bytes) and this README stay
+uncompressed for browsing. First archived **2026-07-29**.
+
+```sh
+# unpack the archived data (into git-ignored per-provider dirs):
+sh scripts/snapshot-sources.sh unpack        # or: tar xzf sources/snapshot.tar.gz -C sources
+# refresh/extend from the live sites (idempotent — skips files already present):
+sh scripts/snapshot-sources.sh               # all four providers
+# re-roll the archive after refreshing:
+sh scripts/snapshot-sources.sh pack          # or: tar czf sources/snapshot.tar.gz -C sources <dirs>
+```
 
 ## What's here
 
diff --git a/sources/snapshot.tar.gz b/sources/snapshot.tar.gz
new file mode 100644
index 0000000..4cfa879
Binary files /dev/null and b/sources/snapshot.tar.gz differ
-- 
cgit v1.3