feat: add social preview, OG tags, README badges and infographic

- Generate social preview SVG + JPG (1280x640) for GitHub
- Add readme infographic showing ccpkg workflow
- Add shields.io badges (spec version, status, license, docs, discussions)
- Configure Starlight OG/Twitter card meta tags reusing social preview
- Add spec generation and freshness check scripts

Author: zircote

.github/readme-infographic.svg

@@ -1,9 +1,20 @@
 # ccpkg
 
+[![Spec Version](https://img.shields.io/badge/spec-2026--02--14-blue?style=flat-square)](https://ccpkg.dev/spec/specification.html)
+[![Status](https://img.shields.io/badge/status-draft-orange?style=flat-square)](#status)
+[![License: CC-BY-4.0](https://img.shields.io/badge/license-CC--BY--4.0-green?style=flat-square)](https://creativecommons.org/licenses/by/4.0/)
+[![Docs](https://img.shields.io/badge/docs-ccpkg.dev-818cf8?style=flat-square)](https://ccpkg.dev)
+[![GitHub Discussions](https://img.shields.io/github/discussions/zircote/ccpkg?style=flat-square&color=94a3b8)](https://github.com/zircote/ccpkg/discussions)
+
 > An open packaging format for AI coding assistant extensions.
 
 ccpkg is a self-contained archive format for packaging and distributing skills, agents, commands, hooks, MCP servers, and LSP servers as a single portable unit. One file, one install, zero post-install steps.
 
+<picture>
+  <source media="(prefers-color-scheme: dark)" srcset=".github/readme-infographic.svg">
+  <img alt="How ccpkg works: Author, Pack, Distribute, Install" src=".github/readme-infographic.svg" width="800">
+</picture>
+
 ## The Problem
 
 AI coding assistants are increasingly extensible, but sharing extensions is fragmented:

.github/social-preview.jpg

@@ -8,6 +8,34 @@ export default defineConfig({
     astroMermaid(),
     starlight({
       title: "ccpkg",
+      head: [
+        {
+          tag: "meta",
+          attrs: {
+            property: "og:image",
+            content: "https://ccpkg.dev/og-image.jpg",
+          },
+        },
+        {
+          tag: "meta",
+          attrs: { property: "og:image:width", content: "1280" },
+        },
+        {
+          tag: "meta",
+          attrs: { property: "og:image:height", content: "640" },
+        },
+        {
+          tag: "meta",
+          attrs: { name: "twitter:card", content: "summary_large_image" },
+        },
+        {
+          tag: "meta",
+          attrs: {
+            name: "twitter:image",
+            content: "https://ccpkg.dev/og-image.jpg",
+          },
+        },
+      ],
       logo: {
         light: "./src/assets/logo-light.svg",
         dark: "./src/assets/logo-dark.svg",

.github/social-preview.svg

@@ -0,0 +1,56 @@
+#!/usr/bin/env node
+
+import { mkdtempSync, readFileSync, rmSync, readdirSync } from "node:fs";
+import { resolve, dirname, join } from "node:path";
+import { tmpdir } from "node:os";
+import { fileURLToPath } from "node:url";
+import { generateSpecPages } from "./generate-spec-pages.mjs";
+
+const __dirname = dirname(fileURLToPath(import.meta.url));
+const ROOT = resolve(__dirname, "..");
+
+const config = JSON.parse(
+  readFileSync(join(__dirname, "spec-mapping.json"), "utf8"),
+);
+const committedDir = resolve(ROOT, config.outputDir);
+
+// Generate to a temp directory
+const tempDir = mkdtempSync(join(tmpdir(), "spec-freshness-"));
+
+try {
+  generateSpecPages(tempDir);
+
+  const staleFiles = [];
+
+  for (const file of readdirSync(tempDir)) {
+    const generated = readFileSync(join(tempDir, file), "utf8");
+    const committedPath = join(committedDir, file);
+
+    let committed;
+    try {
+      committed = readFileSync(committedPath, "utf8");
+    } catch {
+      staleFiles.push(`${file} (missing from ${config.outputDir})`);
+      continue;
+    }
+
+    if (generated !== committed) {
+      staleFiles.push(file);
+    }
+  }
+
+  if (staleFiles.length > 0) {
+    console.error(
+      "Spec pages are stale. Regenerate with: npm run generate:spec\n",
+    );
+    console.error("Stale files:");
+    for (const f of staleFiles) {
+      console.error(`  ${f}`);
+    }
+    process.exit(1);
+  }
+
+  console.log("All spec pages are up to date.");
+} finally {
+  rmSync(tempDir, { recursive: true, force: true });
+}