diff --git a/.github/social-preview.html b/.github/social-preview.html
new file mode 100644
index 0000000..6e0eff4
--- /dev/null
+++ b/.github/social-preview.html
@@ -0,0 +1,32 @@
+<!doctype html>
+<html><head><meta charset="utf-8"><style>
+html,body{margin:0;padding:0;background:#0D1117}
+svg{display:block}
+</style></head><body>
+<svg xmlns="http://www.w3.org/2000/svg" width="1280" height="640" viewBox="0 0 1280 640" font-family="Segoe UI, Helvetica, Arial, sans-serif">
+  <rect width="1280" height="640" fill="#0D1117"/>
+  <!-- vault door -->
+  <g fill="none" stroke="#2DD4BF" stroke-width="10" stroke-linejoin="round" stroke-linecap="round">
+    <rect x="820" y="150" width="340" height="340" rx="36"/>
+    <circle cx="990" cy="320" r="108"/>
+    <circle cx="990" cy="320" r="26"/>
+    <path d="M990 294 V212 M990 346 V428 M964 320 H882 M1016 320 H1098"/>
+    <path d="M850 490 V520 M1130 490 V520" stroke-width="12"/>
+  </g>
+  <!-- volume segments on the dial -->
+  <g fill="#2DD4BF" opacity="0.55">
+    <rect x="1066" y="244" width="24" height="24" rx="5"/>
+    <rect x="890" y="372" width="24" height="24" rx="5"/>
+  </g>
+  <text x="80" y="290" font-size="112" font-weight="700" fill="#FFFFFF">BatchVault</text>
+  <text x="84" y="360" font-size="40" fill="#C9D1D9">Archive, split and restore with proof</text>
+  <g font-size="28" font-weight="600" text-anchor="middle">
+    <rect x="84" y="420" width="190" height="52" rx="26" fill="none" stroke="#2DD4BF" stroke-width="2"/>
+    <text x="179" y="456" fill="#2DD4BF">Python 3.11+</text>
+    <rect x="294" y="420" width="120" height="52" rx="26" fill="none" stroke="#2DD4BF" stroke-width="2"/>
+    <text x="354" y="456" fill="#2DD4BF">CLI</text>
+    <rect x="434" y="420" width="190" height="52" rx="26" fill="none" stroke="#2DD4BF" stroke-width="2"/>
+    <text x="529" y="456" fill="#2DD4BF">AES-256</text>
+  </g>
+</svg>
+</body></html>
diff --git a/.github/social-preview.png b/.github/social-preview.png
new file mode 100644
index 0000000..39badc3
Binary files /dev/null and b/.github/social-preview.png differ