diff --git a/assets/og.png b/assets/og.png
new file mode 100644
index 0000000..c9f5cad
Binary files /dev/null and b/assets/og.png differ
diff --git a/assets/og.svg b/assets/og.svg
new file mode 100644
index 0000000..e4f94ae
--- /dev/null
+++ b/assets/og.svg
@@ -0,0 +1,41 @@
+<svg xmlns="http://www.w3.org/2000/svg" width="1280" height="640" viewBox="0 0 1280 640">
+  <defs>
+    <linearGradient id="bg" x1="0" y1="0" x2="1" y2="1">
+      <stop offset="0" stop-color="#0f1d24"/><stop offset="1" stop-color="#0a1318"/>
+    </linearGradient>
+    <radialGradient id="glow" gradientUnits="userSpaceOnUse" cx="295" cy="320" r="430">
+      <stop offset="0" stop-color="#18383a" stop-opacity="0.55"/><stop offset="1" stop-color="#0d1a20" stop-opacity="0"/>
+    </radialGradient>
+    <linearGradient id="steel" x1="0" y1="0" x2="0" y2="1">
+      <stop offset="0" stop-color="#d6dde3"/><stop offset=".5" stop-color="#929cab"/><stop offset="1" stop-color="#515a68"/>
+    </linearGradient>
+    <linearGradient id="brass" x1="0" y1="0" x2="0" y2="1">
+      <stop offset="0" stop-color="#f0d287"/><stop offset=".55" stop-color="#d3a349"/><stop offset="1" stop-color="#a9822f"/>
+    </linearGradient>
+  </defs>
+
+  <rect width="1280" height="640" fill="url(#bg)"/>
+  <rect width="1280" height="640" fill="url(#glow)"/>
+
+  <!-- faint concentric rings echoing the cylinder -->
+  <g fill="none" stroke="#ffffff" stroke-opacity="0.04" stroke-width="2">
+    <circle cx="295" cy="320" r="212"/><circle cx="295" cy="320" r="288"/><circle cx="295" cy="320" r="366"/>
+  </g>
+
+  <!-- the icon -->
+  <g transform="translate(115,140) scale(3.6)">
+    <path fill="url(#steel)" fill-rule="evenodd" stroke="#3c434e" stroke-width="0.8"
+          d="M10 50 a40 40 0 1 0 80 0 a40 40 0 1 0 -80 0 Z M35 50 a15 15 0 1 0 30 0 a15 15 0 1 0 -30 0 Z M44.4 22 a5.6 5.6 0 1 0 11.2 0 a5.6 5.6 0 1 0 -11.2 0 Z M68.6 36 a5.6 5.6 0 1 0 11.2 0 a5.6 5.6 0 1 0 -11.2 0 Z M68.6 64 a5.6 5.6 0 1 0 11.2 0 a5.6 5.6 0 1 0 -11.2 0 Z M44.4 78 a5.6 5.6 0 1 0 11.2 0 a5.6 5.6 0 1 0 -11.2 0 Z M20.2 64 a5.6 5.6 0 1 0 11.2 0 a5.6 5.6 0 1 0 -11.2 0 Z M20.2 36 a5.6 5.6 0 1 0 11.2 0 a5.6 5.6 0 1 0 -11.2 0 Z"/>
+    <circle cx="50" cy="22" r="5.6" fill="url(#brass)"/><circle cx="50" cy="22" r="2" fill="#7c5c22"/>
+    <path d="M42 58 L42 44 L50 51.5 L58 44 L58 58" fill="none" stroke="#3f3110" stroke-width="7" stroke-linecap="round" stroke-linejoin="round"/>
+    <path d="M42 58 L42 44 L50 51.5 L58 44 L58 58" fill="none" stroke="url(#brass)" stroke-width="4.2" stroke-linecap="round" stroke-linejoin="round"/>
+  </g>
+
+  <!-- text -->
+  <text x="548" y="214" font-family="Menlo, 'DejaVu Sans Mono', monospace" font-size="22" letter-spacing="5" fill="#d3a349">ARRANGE &#183; ACT &#183; INSPECT</text>
+  <text x="543" y="348" font-family="'Helvetica Neue', Helvetica, Arial, sans-serif" font-size="122" font-weight="800" fill="#eef2f1">Mokkit<tspan fill="#d3a349">.</tspan></text>
+  <rect x="549" y="378" width="188" height="4" rx="2" fill="#d3a349"/>
+  <text x="548" y="448" font-family="'Helvetica Neue', Helvetica, Arial, sans-serif" font-size="31" fill="#a9b7bc">Tests that read like a story &#8212;</text>
+  <text x="548" y="490" font-family="'Helvetica Neue', Helvetica, Arial, sans-serif" font-size="31" fill="#a9b7bc">plain, compilable C#. No DSL.</text>
+  <text x="548" y="556" font-family="Menlo, 'DejaVu Sans Mono', monospace" font-size="23" fill="#d3a349">mokkit.net</text>
+</svg>
diff --git a/docs/astro.config.mjs b/docs/astro.config.mjs
index b89a6cb..7d69b67 100644
--- a/docs/astro.config.mjs
+++ b/docs/astro.config.mjs
@@ -15,6 +15,10 @@ export default defineConfig({
         // PNG fallbacks for browsers that don't use the SVG favicon, plus the Apple touch icon.
         { tag: 'link', attrs: { rel: 'icon', href: '/favicon-32.png', type: 'image/png', sizes: '32x32' } },
         { tag: 'link', attrs: { rel: 'apple-touch-icon', href: '/favicon.png', sizes: '180x180' } },
+        // Social-preview card for shared links.
+        { tag: 'meta', attrs: { property: 'og:image', content: 'https://mokkit.net/og.png' } },
+        { tag: 'meta', attrs: { name: 'twitter:image', content: 'https://mokkit.net/og.png' } },
+        { tag: 'meta', attrs: { name: 'twitter:card', content: 'summary_large_image' } },
       ],
       social: [
         { icon: 'github', label: 'GitHub', href: 'https://github.com/GrafGenerator/mokkit' },
diff --git a/docs/public/og.png b/docs/public/og.png
new file mode 100644
index 0000000..c9f5cad
Binary files /dev/null and b/docs/public/og.png differ
diff --git a/docs/scripts/gen-icon.mjs b/docs/scripts/gen-icon.mjs
index ef13b77..428dca7 100644
--- a/docs/scripts/gen-icon.mjs
+++ b/docs/scripts/gen-icon.mjs
@@ -6,19 +6,26 @@ import { fileURLToPath } from 'node:url';
 import { dirname, join } from 'node:path';
 
 const root = join(dirname(fileURLToPath(import.meta.url)), '..', '..');
-const svg = readFileSync(join(root, 'assets', 'icon.svg'));
+const icon = readFileSync(join(root, 'assets', 'icon.svg'));
+const og = readFileSync(join(root, 'assets', 'og.svg'));
 
-const jobs = [
+// Square, transparent icons/favicons.
+const squares = [
   ['assets/icon.png', 128],            // NuGet PackageIcon
   ['assets/icon-256.png', 256],        // higher-res spare (social, README)
   ['docs/public/favicon.png', 180],    // apple-touch + PNG fallback
   ['docs/public/favicon-32.png', 32],  // classic favicon fallback
 ];
-
-for (const [rel, size] of jobs) {
-  await sharp(svg, { density: 512 })
+for (const [rel, size] of squares) {
+  await sharp(icon, { density: 512 })
     .resize(size, size, { fit: 'contain', background: { r: 0, g: 0, b: 0, alpha: 0 } })
     .png()
     .toFile(join(root, rel));
   console.log(`wrote ${rel} (${size}px)`);
 }
+
+// Open Graph / social-preview banner (1280x640), rendered 2x then downsampled for crisp text.
+for (const rel of ['assets/og.png', 'docs/public/og.png']) {
+  await sharp(og, { density: 192 }).resize(1280, 640).png().toFile(join(root, rel));
+  console.log(`wrote ${rel} (1280x640)`);
+}