diff --git a/.github/social-preview.html b/.github/social-preview.html
new file mode 100644
index 0000000..ec41a73
--- /dev/null
+++ b/.github/social-preview.html
@@ -0,0 +1,32 @@
+<!-- The repository's social preview, 1280 × 640: designed on the Claude Design canvas (page "OG images"). GitHub has no API for it: upload social-preview.png in Settings → General → Social preview. -->
+<!doctype html><html><head><meta charset="utf-8"><link rel="stylesheet" href="https://fonts.googleapis.com/css2?family=Young+Serif&family=Hanken+Grotesk:wght@400;500;600;700&family=DM+Mono:wght@400;500&display=swap"><style>body{margin:0;width:1280px;height:640px;overflow:hidden;font-family:"Hanken Grotesk",sans-serif;-webkit-font-smoothing:antialiased}</style></head><body>
+<div style="position: relative; width: 1280px; height: 640px; overflow: hidden; background: #F3F1EC; color: #141413;">
+  <div aria-hidden="true" style="position: absolute; inset: 0; background-image: radial-gradient(rgba(20,20,19,.16) 1.6px, transparent 1.9px); background-size: 14px 14px; -webkit-mask-image: radial-gradient(ellipse 48% 70% at 80% 50%, #000 25%, transparent 78%); mask-image: radial-gradient(ellipse 48% 70% at 80% 50%, #000 25%, transparent 78%);"></div>
+  <div style="position: absolute; left: 700px; top: 0; width: 580px; height: 640px;">
+<div style="position: absolute; left: 0; top: 70px; z-index: 3; padding: 22px 28px; border-radius: 24px; background: #141413; color: #F3F1EC; box-shadow: 0 30px 50px -30px rgba(20,20,19,.7); font-family: 'DM Mono', monospace; font-size: 26px; line-height: 1.7; white-space: pre; transform: rotate(-2deg);"><span style="color: #8A857B;">$</span> npm i @polyxd/react
+<span style="color: #8A857B;">$</span> npx polyxd check <span style="color: #6FD39A;">✓</span></div><div style="position: absolute; left: 170px; top: 230px; z-index: 1; width: 424px; height: 880px; box-sizing: border-box; padding: 15.0px; border-radius: 73.0px; background: linear-gradient(135deg, #5C5A55 0%, #2B2A28 18%, #151514 50%, #2B2A28 82%, #4A4844 100%); box-shadow: inset 0 0 0 1px rgba(255,255,255,.16), 0 40px 70px -30px rgba(20,20,19,.6); transform: rotate(4deg);">
+  <div style="position: relative; width: 100%; height: 100%; border-radius: 58.1px; overflow: hidden; background: #FFFFFF;">
+    <div style="position: absolute; left: 0; top: 0; width: 224px; height: 483.2px; transform: scale(1.7593); transform-origin: 0 0; display: flex; flex-direction: column;">
+      <div style="position: relative; flex-shrink: 0; height: 30px;"><i style="position: absolute; left: 50%; top: 8px; width: 70px; height: 18px; margin-left: -35px; border-radius: 99px; background: #000000;"></i><i style="position: absolute; left: 22px; top: 13px; width: 20px; height: 6px; border-radius: 3px; background: #141413; opacity: .8;"></i><i style="position: absolute; right: 20px; top: 12px; width: 16px; height: 8px; border-radius: 2px; background: #141413; opacity: .8;"></i></div>
+      <div style="flex-grow: 1; display: flex; flex-direction: column; gap: 14px; padding: 8px 16px 16px; background: #FEF7FF; color: #1D1B20; font-family: 'Hanken Grotesk', sans-serif;">
+  <span style="font-size: 24px; font-weight: 500;">Send money</span>
+  <span style="display: flex; gap: 14px; padding-left: 4px;"><span style="width: 44px; height: 44px; border-radius: 99px; background: #EADDFF; display: grid; place-items: center; font-size: 15px; font-weight: 600; box-shadow: 0 0 0 2px #FEF7FF, 0 0 0 4px #6750A4;">PR</span><span style="width: 44px; height: 44px; border-radius: 99px; background: #EADDFF; display: grid; place-items: center; font-size: 15px; font-weight: 600;">AO</span><span style="width: 44px; height: 44px; border-radius: 99px; background: #EADDFF; display: grid; place-items: center; font-size: 15px; font-weight: 600;">RL</span></span>
+  <span style="text-align: center; font-size: 40px; font-weight: 400; letter-spacing: -.01em;">£40.00</span>
+  <span style="height: 42px; display: grid; place-items: center; border-radius: 99px; background: #6750A4; color: #FFFFFF; font-size: 15px; font-weight: 600;">Continue</span>
+</div>
+    </div>
+  </div>
+</div>
+  </div>
+  <div style="position: absolute; left: 64px; top: 56px; bottom: 52px; width: 600px; display: flex; flex-direction: column;">
+    <div style="display: flex; align-items: center; gap: 10px;"><svg width="52" height="52" viewBox="0 0 32 32" style="display: block; flex-shrink: 0;" aria-hidden="true"><path d="M13 6H19C22.864 6 26 9.136 26 13V19C26 22.864 22.864 26 19 26H13C9.136 26 6 22.864 6 19V13C6 9.136 9.136 6 13 6Z" fill="#FF6E40"></path><path d="M8.5 14H8.5C9.88 14 11 15.12 11 16.5V25.5C11 26.88 9.88 28 8.5 28H8.5C7.12 28 6 26.88 6 25.5V16.5C6 15.12 7.12 14 8.5 14Z" fill="#FF6E40"></path><path d="M16 11.2H16C20.224 11.2 20.8 11.776 20.8 16V16C20.8 20.224 20.224 20.8 16 20.8H16C11.776 20.8 11.2 20.224 11.2 16V16C11.2 11.776 11.776 11.2 16 11.2Z" fill="#FFFFFF"></path><circle cx="17.2" cy="15.6" r="2.4" fill="#141413"></circle></svg><span style="font-family: 'Young Serif', Georgia, serif; font-weight: 400; font-size: 40px; letter-spacing: -.01em; line-height: 1;">polyxd</span></div>
+    <div style="flex-grow: 1;"></div>
+    <div style="display: flex; flex-direction: column; gap: 18px;">
+      <div style="display: flex; align-items: center; gap: 12px; font-family: 'DM Mono', monospace; font-size: 24px; letter-spacing: .04em; text-transform: uppercase; color: #5E5A52;"><span style="flex-shrink: 0; width: 12px; height: 12px; border-radius: 99px; background: #FF6E40;"></span>Open source · Apache-2.0</div>
+      <h1 style="margin: 0; font-family: 'Young Serif', Georgia, serif; font-weight: 400; font-size: 84px; line-height: 1.02; letter-spacing: -.015em;">Every ask gets a screen.</h1>
+      <p style="margin: 0; max-width: 600px; font-size: 28px; line-height: 1.3; color: #5E5A52;">An open spec, renderers and a verifier, drawn in your design system.</p>
+    </div>
+    <div style="margin-top: 26px; font-family: 'DM Mono', monospace; font-size: 24px; color: #5E5A52;">github.com/visualfart/polyxd</div>
+  </div>
+</div>
+</body></html>
\ No newline at end of file
diff --git a/.github/social-preview.png b/.github/social-preview.png
new file mode 100644
index 0000000..3551d5b
Binary files /dev/null and b/.github/social-preview.png differ
diff --git a/apps/site/og/README.md b/apps/site/og/README.md
index 29c26dd..fed81a2 100644
--- a/apps/site/og/README.md
+++ b/apps/site/og/README.md
@@ -11,6 +11,9 @@ One 1200 × 630 card per page of polyxd.com, shown when a link is shared.
   has none. The four demo products' cards go to `apps/demos/public/<name>/og.png`, where their
   pages already point; `apps/demos/scripts/og.ts` renders the same cards there too.
 
+The repository's own social preview (1280 × 640) is `.github/social-preview.png`, from
+`.github/social-preview.html`; GitHub only takes it as an upload in the repo's settings.
+
 Nothing on a card is smaller than 24px, since a feed shows it at about half size.
 
 To change a card, edit it in `cards/` (and on the canvas), then run: