feat: add blog infrastructure

.vscode/settings.json

@@ -25,6 +25,7 @@
     "dotenv",
     "esbuild",
     "evals",
+    "frontmatter",
     "gptoss",
     "gsutil",
     "hyperscaler",
@@ -38,6 +39,7 @@
     "kimi",
     "kimik",
     "lefthook",
+    "llms",
     "maxage",
     "minimaxm",
     "mooncake",

AGENTS.md

@@ -34,13 +34,15 @@ pnpm test:e2e             # Cypress E2E tests
 ```
 packages/
 ├── app/                  # Next.js frontend (@semianalysisai/inferencex-app)
+│   ├── content/blog/     # MDX blog posts (frontmatter + content)
 │   └── src/
 │       ├── app/          # Pages, layouts, API routes (/api/v1/*)
+│       │   └── blog/     # Blog list + [slug] post pages, OG image generation
 │       ├── components/   # Tab sections: inference/, evaluation/, historical-trends/,
-│       │                 #   throughput-calculator/, reliability/, gpu-specs/, ui/
+│       │                 #   throughput-calculator/, reliability/, gpu-specs/, blog/, ui/
 │       ├── hooks/api/    # React Query hooks (use-benchmarks, use-availability, etc.)
-│       └── lib/          # Utilities, constants, d3-chart/, chart-utils, data-mappings
-├── constants/            # Shared constants (GPU keys, model mappings)
+│       └── lib/          # Utilities, constants, d3-chart/, chart-utils, blog, data-mappings
+├── constants/            # Shared constants (GPU keys, model mappings, SEO)
 └── db/                   # DB layer, ETL, migrations, queries, ingest scripts
 ```
 
@@ -66,6 +68,15 @@ API routes (`packages/app/src/app/api/v1/`):
 
 **API routes return raw DB data** — no presentation logic. Frontend handles all transformations.
 
+Static content routes (no DB):
+
+- `/blog` — blog listing (statically generated from MDX files in `content/blog/`)
+- `/blog/[slug]` — blog post page with MDX rendering and OG image generation
+- `/feed.xml` — RSS 2.0 feed
+- `/llms.txt` — LLM-readable site index
+- `/llms-full.txt` — full article content for LLM ingestion
+- `/sitemap.xml` — dynamic sitemap (includes blog posts)
+
 ## Code Style & Tooling
 
 - **Linter**: oxlint — `pnpm lint` / `pnpm lint:fix`
@@ -87,7 +98,7 @@ All interactive elements should have `track()` from `@/lib/analytics` (autocaptu
 
 **Convention**: `[section]_[action]` — e.g., `latency_zoom_reset`, `calculator_bar_selected`, `tab_changed`
 
-**Prefixes**: `latency_`, `interactivity_`, `gpu_timeseries_`, `inference_`, `calculator_`, `evaluation_`, `reliability_`, `tab_`, `selector_`
+**Prefixes**: `latency_`, `interactivity_`, `gpu_timeseries_`, `inference_`, `calculator_`, `evaluation_`, `reliability_`, `tab_`, `selector_`, `blog_`, `social_`
 
 ## Tab Structure
 
@@ -118,6 +129,25 @@ Order: `inference` → `evaluation` → `historical` → `calculator` → `relia
 6. Add disagg caveat banner in `ChartDisplay.tsx` for per-GPU or per-MW metrics (animated amber `border-l-2` banner pattern)
 7. Expose in UI state: `InferenceContext.tsx`
 
+### Add a new blog post
+
+1. Create `packages/app/content/blog/<slug>.mdx` with frontmatter: `title`, `subtitle`, `date` (required), `tags`, `modifiedDate` (optional)
+2. Write content using Markdown + custom MDX components (`Figure`, `Blur`)
+3. No code changes needed — the post automatically appears in the blog list, sitemap, RSS feed, llms.txt, and gets a generated OG image
+
+See [Blog](./docs/blog.md) for content format, available MDX components, and design details.
+
+### Modify blog components
+
+- Blog library (posts, headings, reading time): `src/lib/blog.ts`
+- Blog list page: `src/app/blog/page.tsx`
+- Blog post page: `src/app/blog/[slug]/page.tsx`
+- MDX components: `src/components/blog/mdx-components.tsx`
+- TOC sidebar: `src/components/blog/blog-toc.tsx`
+- OG image generation: `src/app/blog/[slug]/og-image-render.tsx`
+- RSS feed: `src/app/feed.xml/route.ts`
+- SEO constants: `packages/constants/src/seo.ts`
+
 ### Add a new model or GPU
 
 **First ask for the PR / GitHub Actions run URL** — see [Adding Entities](./docs/adding-entities.md) for the full workflow. Never ask other questions before getting the URL.
@@ -144,6 +174,7 @@ Detailed design rationale (the "why" and "how", not the "what") lives in [docs/]
 - **[Testing](./docs/testing.md)** — Requirements, quality standards, pre-commit checklist
 - **[Data Transforms](./docs/data-transforms.md)** — BenchmarkRow → AggDataEntry → InferenceData pipeline, hardware key construction, derived metrics
 - **[State Ownership](./docs/state-ownership.md)** — Context provider state map, availability filtering cascade, comparison dates, URL params
+- **[Blog](./docs/blog.md)** — MDX content system, SEO features, TOC sidebar, reading progress, analytics events
 
 ## Claude AI Agents
 

docs/blog.md

@@ -0,0 +1,117 @@
+# Blog Infrastructure
+
+## Why MDX + Static Generation
+
+Blog posts are MDX files in `packages/app/content/blog/`, compiled at build time via `next-mdx-remote`. This was chosen over a CMS or database because:
+
+- **No runtime dependency**: Posts are part of the repo, versioned in git, reviewed in PRs. No CMS outage can break the blog.
+- **MDX flexibility**: Authors can embed custom React components (`Figure`, `Blur`) alongside Markdown. This matters for image-heavy technical articles with captions, paywall teasers, and code blocks.
+- **Static generation**: `generateStaticParams()` pre-renders all post pages. No server-side rendering at request time.
+
+Syntax highlighting uses Shiki with dual light/dark themes (CSS class-based switching, not runtime theme detection).
+
+## Content Format
+
+```yaml
+# Frontmatter (required: title, subtitle, date)
+title: string
+subtitle: string
+date: YYYY-MM-DD
+modifiedDate?: YYYY-MM-DD # Used in sitemap and JSON-LD
+tags?: string[] # Used for filtering on /blog and in RSS categories
+```
+
+Slug is derived from the filename (e.g., `my-post.mdx` -> `my-post`), not from frontmatter. Reading time is calculated at 265 WPM.
+
+## MDX Components Available to Authors
+
+| Component                                      | Usage                            | Notes                                                                             |
+| ---------------------------------------------- | -------------------------------- | --------------------------------------------------------------------------------- |
+| `# / ## / ###`                                 | Headings with auto-generated IDs | IDs are deduped: second `## Details` under `## Results` becomes `results-details` |
+| `[text](url)`                                  | Links                            | Internal links use `<Link>`, external get `target="_blank"`                       |
+| `![alt](src)`                                  | Images                           | Rendered via `next/image` with lazy loading (first image is eager)                |
+| `<Figure src="..." alt="..." caption="..." />` | Captioned figures                | Uses `<img>` (not `next/image`) for external URLs                                 |
+| `<Blur>...</Blur>`                             | Paywall teaser blur overlay      | Content is blurred, unselectable, and not clickable                               |
+
+Heading ID deduplication: if two headings share a slug, the second gets prefixed with its parent heading's slug (e.g., `overview-details`). If no parent exists, a level suffix is appended (`intro-2`).
+
+## Blog Library (`src/lib/blog.ts`)
+
+| Function                  | Purpose                                                   |
+| ------------------------- | --------------------------------------------------------- |
+| `getAllPosts()`           | All posts sorted newest-first                             |
+| `getPostBySlug(slug)`     | Single post meta + raw MDX content                        |
+| `getAdjacentPosts(slug)`  | `{ prev, next }` — prev is older, next is newer           |
+| `extractHeadings(rawMdx)` | h1-h3 headings with unique IDs (strips code blocks first) |
+| `slugify(raw)`            | URL-safe slug generation                                  |
+| `getReadingTime(content)` | Word count / 265, minimum 1 minute                        |
+
+## SEO Features
+
+### Dynamic OG Images (`/blog/[slug]/opengraph-image.tsx`)
+
+1200x630px images generated at build time with `next/og` (Satori). Design: decorative tile sidebar + dark content panel with title, subtitle, date, and logo. Title font size scales (56-72px) based on length for readability at thumbnail sizes.
+
+### RSS Feed (`/feed.xml`)
+
+RSS 2.0 with Dublin Core and Atom extensions. Includes all posts with title, link, description, creator, pubDate, categories. Cached 1 hour.
+
+### LLM Discovery (`/llms.txt`, `/llms-full.txt`)
+
+- `/llms.txt`: Site description + article index with titles, URLs, and subtitles
+- `/llms-full.txt`: Full raw MDX content of every post, for LLM context ingestion
+
+### Sitemap Integration
+
+Blog index at priority 0.8 (weekly), individual posts at priority 0.7 (monthly, uses `modifiedDate` if present).
+
+### JSON-LD
+
+- `/blog` page: `Blog` schema
+- `/blog/[slug]` page: `BlogPosting` schema (headline, author, publisher, dates, wordCount, timeRequired)
+
+## UI Components
+
+### Table of Contents (`blog-toc.tsx`)
+
+Two modes based on available viewport space:
+
+- **Sidebar** (>= 240px right of content): Fixed position, follows scroll via imperative DOM updates in a scroll handler. Active heading tracked via `IntersectionObserver` with `rootMargin: '0px 0px -80% 0px'`. Falls back to last heading when scrolled to page bottom.
+- **Inline** (narrow screens): Collapsible `<details>` card.
+
+The sidebar position is calculated relative to the `[data-blog-section]` element and updated on scroll/resize.
+
+### Reading Progress Bar (`reading-progress-bar.tsx`)
+
+Fixed-top 0.5px bar tracking scroll position within the `<article>` element. Fires milestone events at 25/50/75/100% thresholds (each fires only once per page load).
+
+### Heading Links (`heading-link.tsx`)
+
+Copy-to-clipboard button shown on heading hover. State cycle: idle -> copied ("Link copied" text) -> fade out -> idle.
+
+### Post Navigation (`blog-post-nav.tsx`)
+
+Previous (older) / Next (newer) post links with title display. Uses `getAdjacentPosts()`.
+
+## Analytics Events
+
+All blog analytics use the `blog_` prefix per the `[section]_[action]` convention:
+
+| Event                                            | Trigger                      |
+| ------------------------------------------------ | ---------------------------- |
+| `blog_post_clicked`                              | Click post card on list page |
+| `blog_toc_clicked`                               | Click TOC heading            |
+| `blog_read_milestone`                            | Scroll past 25/50/75/100%    |
+| `blog_heading_link_copied`                       | Copy heading link            |
+| `blog_nav_prev` / `blog_nav_next`                | Click prev/next post         |
+| `blog_back_clicked`                              | Click back to articles       |
+| `blog_tag_filtered`                              | Click tag filter             |
+| `social_share_twitter` / `social_share_linkedin` | Click share buttons          |
+
+## Adding a New Blog Post
+
+1. Create `packages/app/content/blog/<slug>.mdx` with required frontmatter (`title`, `subtitle`, `date`)
+2. Add optional `tags` and `modifiedDate` frontmatter
+3. Write content using standard Markdown + available MDX components
+4. The post automatically appears in: blog list, sitemap, RSS feed, llms.txt, OG image generation
+5. No code changes needed — just the MDX file

docs/index.md

@@ -14,3 +14,4 @@ Design rationale and non-obvious conventions. See [CLAUDE.md](../CLAUDE.md) for
 - [Testing](./testing.md) — Requirements, quality standards, pre-commit checklist
 - [Data Transforms](./data-transforms.md) — Full pipeline from BenchmarkRow to RenderableGraph: type hierarchy, hardware key construction, derived metrics, memoization strategy
 - [State Ownership](./state-ownership.md) — Which context owns which state, availability filtering cascade, comparison date mechanics, URL param sync
+- [Blog](./blog.md) — MDX content system, SEO features (OG images, RSS, llms.txt, JSON-LD), TOC sidebar, reading progress, heading links, analytics events