From ebb70168ad50c406f511a859e6212d0f9d2a98f8 Mon Sep 17 00:00:00 2001
From: Brian Love <brian@liveloveapp.com>
Date: Sat, 16 May 2026 21:28:01 -0700
Subject: [PATCH 01/20] docs(gtm): spec for content-pillar-pages as blog (Spec
 5)

Blog infrastructure at cacheplane.ai/blog plus one seed pillar post
("Build a streaming chat UI in Angular with LangGraph") written in
Brian Love's voice. Flat /blog/[slug] routes, date-prefixed MDX,
RSS, OG, sitemap, new blog:* analytics namespace.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
---
 .../2026-05-17-content-pillar-pages-design.md | 591 ++++++++++++++++++
 1 file changed, 591 insertions(+)
 create mode 100644 docs/superpowers/specs/gtm/2026-05-17-content-pillar-pages-design.md

diff --git a/docs/superpowers/specs/gtm/2026-05-17-content-pillar-pages-design.md b/docs/superpowers/specs/gtm/2026-05-17-content-pillar-pages-design.md
new file mode 100644
index 000000000..770a4e0b7
--- /dev/null
+++ b/docs/superpowers/specs/gtm/2026-05-17-content-pillar-pages-design.md
@@ -0,0 +1,591 @@
+---
+workstream: content-pillar-pages
+status: approved
+owner: brian
+phase: 2
+spec: docs/superpowers/specs/gtm/2026-05-17-content-pillar-pages-design.md
+plan: docs/superpowers/plans/gtm/2026-05-17-content-pillar-pages.md
+parent: docs/superpowers/specs/gtm/2026-05-13-gtm-meta-design.md
+---
+
+# Spec 5 — Content Pillar Pages (Design)
+
+> Phase 2 ecosystem deliverable. Stand up `/blog` on cacheplane.ai as a long-form SEO surface — flat URLs, MDX-driven, RSS-fed, OG-imaged, analytics-instrumented. Ship one seed pillar post written in Brian Love's existing blog voice. Remaining pillar posts land as follow-up commits against the same infra.
+
+## 1. Goal
+
+Two outcomes:
+
+1. **A production-grade blog infrastructure** on `cacheplane.ai/blog` that reuses the existing MDX renderer + design system + analytics pipeline. Frontmatter-driven, flat URLs, RSS feed, per-post OG image, sitemap inclusion, dedicated `blog:*` analytics namespace.
+2. **The first pillar post — "Build a streaming chat UI in Angular with LangGraph"** — drafted in Brian Love's existing voice (sourced from `~/repos/brianflove/src/content/posts/2026-*.md`). The seed post is the highest-leverage SEO target for the developer-track funnel.
+
+Phase 2 exit criterion (per `gtm.md`) is "6 pillar pages indexed, organic traffic baseline captured." Spec 5 satisfies the infrastructure half plus 1 of the 6 posts. The remaining 5 land as follow-up content commits against the same infra — each a focused review.
+
+## 2. Context
+
+- Parent: `docs/superpowers/specs/gtm/2026-05-13-gtm-meta-design.md` §6 (Phase 2: Ecosystem path).
+- Reference layout: `~/repos/dawn/apps/web/{app/blog,content/blog}` — date-prefixed MDX filenames, flat URLs, RSS, tags. Adopted wholesale.
+- Voice reference: `~/repos/brianflove/src/content/posts/2026-*.md` — Brian's existing blog. The seed post must match this voice.
+- Reused infra already in the cacheplane website:
+  - `next-mdx-remote/rsc` MDX pipeline with custom components (`Callout`, `Steps`, `Tabs`, `Card`, `CodeGroup`, `Pre`).
+  - `rehype-pretty-code` (tokyo-night), `rehype-slug`, `remark-gfm`.
+  - `createPageMetadata()` for OG + canonical.
+  - `getSitemapRoutes()` for sitemap.
+  - Default `opengraph-image.tsx` at the route level via `next/og` `ImageResponse`.
+- `docs:*` analytics namespace is the established pattern; `blog:*` is the parallel namespace this spec introduces.
+
+## 3. Scope
+
+**In scope:**
+
+- **Routes:**
+  - `/blog` — index page (date-sorted, featured post on top, post grid below, tag chips).
+  - `/blog/[slug]` — dynamic post route reusing `<MdxRenderer>`. Renders title, date, author byline, body, tags, "more posts" links at bottom.
+  - `/blog/[slug]/opengraph-image.tsx` — per-post 1200×630 OG card with post title + author. Falls back to the default site OG card if the post can't be resolved.
+  - `/blog/rss.xml` — RSS 2.0 feed, `Content-Type: application/rss+xml`.
+- **Content:** `apps/website/content/blog/YYYY-MM-DD-<slug>.mdx`. Date-prefixed filenames so the directory listing matches publish order. Slug derived from filename minus the date prefix.
+- **Frontmatter shape** (required keys bolded):
+  - **`title`** — string, 60-80 chars
+  - **`description`** — string, 130-180 chars (used in `<meta>`, RSS `<description>`, social previews)
+  - **`date`** — ISO `YYYY-MM-DD`
+  - `tags` — `string[]`, lowercase kebab-case
+  - **`author`** — registry key (`brian` in v1)
+  - `featured` — boolean, optional. The first `featured: true` post in date-desc order becomes the featured slot on `/blog`. If none, the most recent post is featured.
+  - `draft` — boolean, optional. When true, the post is skipped by `getAllPosts()` in production builds and from RSS + sitemap. (Internal preview path TBD; out of scope here. Drafts simply don't appear in listings; a direct URL still works for review.)
+- **Author registry** at `apps/website/src/lib/blog-authors.ts` with one entry (`brian`) — name, role, optional `bio`, optional `twitter`, optional `github`, optional `avatar` path. The byline renders gracefully without avatar/twitter/github fields.
+- **Analytics:** add two new event names to `events.ts` and `taxonomy.md`:
+  - `blog:cta_click` — tracked CTAs inside post bodies (e.g., links to `/pricing`, `/contact`). Properties: `surface: 'blog'`, `cta_id?: CtaId`, `destination_url?: string`.
+  - `blog:copy_code_click` — copy-button click on a code block. Properties: `surface: 'blog'`, `code_lang?: string`.
+  - Add `'blog'` to the `AnalyticsSurface` union.
+- **Nav:** add a `Blog` link to the site nav. Position between `Pricing` and the `GitHub` icon (or wherever the navbar's existing convention puts secondary links).
+- **Sitemap:** `getSitemapRoutes()` includes `/blog` plus every published `/blog/[slug]`. Sorted desc by date. `changeFrequency: 'weekly'` for the index, `'monthly'` for individual posts. Priority 0.7 for both.
+- **Seed pillar post** at `apps/website/content/blog/2026-05-17-build-a-streaming-chat-ui-in-angular-with-langgraph.mdx`. ~2,500 words. Written in Brian Love's voice (see §6 for voice rules and outline).
+- **Unit tests:**
+  - `apps/website/src/lib/blog.spec.ts` — `getAllPosts()` returns posts sorted desc; `getPostBySlug()` returns a known seed post; frontmatter parsing populates required fields; missing-required-field frontmatter throws a helpful error.
+  - `apps/website/src/components/blog/PostCard.spec.tsx` — renders title, date, and tag chips for a given post.
+- **Verification:** `nx run website:build` green; manual smoke at `localhost:3000/blog` and `/blog/[seed-slug]`; RSS feed validates as XML.
+
+**Out of scope (deferred to follow-ups):**
+
+- Posts 2-6 of the 6-post pillar set. Each lands as a separate commit/PR against this infra.
+- `/blog/tags/[tag]` per-tag pages. v1 has tag chips on the index that filter client-side (or just link nowhere). Per-tag pages are a follow-up.
+- A draft preview workflow (e.g., `?preview=token` to render `draft: true` posts on production).
+- Blog-specific MDX components (e.g., `<Tweet>`, `<Aside>`). v1 reuses the docs-flavor MDX components. Add post-specific ones in follow-ups if a post requires them.
+- A blog-specific design refresh. v1 reuses the existing tokens + section styling.
+- Comment threads, claps, reactions. Out for v1.
+- A newsletter-on-publish hook (e.g., Loops trigger). Out for v1.
+
+**Success criteria:**
+
+- `/blog` renders with the seed post visible.
+- `/blog/[seed-slug]` renders the full post with author byline, syntax-highlighted code, and OG-image-driven `<meta>` tags.
+- `/blog/rss.xml` returns a valid RSS 2.0 XML document containing the seed post.
+- Sitemap includes the new routes.
+- `nx run website:build` green; `nx run website:test` (via `npx vitest run` from `apps/website/`) green for the new tests.
+- The seed post passes a manual content review by Brian (post-merge content edits are expected and welcome).
+
+## 4. Architecture
+
+```
+content/blog/YYYY-MM-DD-<slug>.mdx       (date-prefixed filenames, source of truth)
+   │
+   ▼ getAllPosts() / getPostBySlug()  ──── frontmatter parse + body
+   │
+   ├──▶ /blog               (index page)
+   │       Featured: most recent `featured: true` post (or latest)
+   │       Grid:     all other published posts, date-desc
+   │
+   ├──▶ /blog/[slug]        (dynamic route, MdxRenderer)
+   │       Title + AuthorByline + date + body + tags
+   │
+   ├──▶ /blog/[slug]/opengraph-image.tsx    (per-post OG card)
+   │       1200×630 PNG via `next/og` ImageResponse, reads frontmatter
+   │
+   ├──▶ /blog/rss.xml       (RSS 2.0 feed)
+   │       sorted desc by date, all published posts
+   │
+   └──▶ sitemap.ts          (every published /blog/[slug] + /blog)
+```
+
+Posts NEVER trigger lifecycle signals or cockpit telemetry. They emit only `$pageview` + the two new `blog:*` events.
+
+## 5. Components
+
+### 5.1 `apps/website/src/lib/blog.ts` (new)
+
+Server-only utility module. Reads MDX files synchronously at request time (build-time on static routes).
+
+```typescript
+// SPDX-License-Identifier: MIT
+import fs from 'fs';
+import path from 'path';
+import matter from 'gray-matter';
+
+const BLOG_DIR = path.join(process.cwd(), 'apps/website/content/blog');
+// Fallback path for when CWD is the website app itself (during dev/test).
+const BLOG_DIR_FALLBACK = path.join(process.cwd(), 'content/blog');
+
+export interface PostFrontmatter {
+  title: string;
+  description: string;
+  date: string;            // ISO YYYY-MM-DD
+  tags?: string[];
+  author: string;          // key into blog-authors.ts
+  featured?: boolean;
+  draft?: boolean;
+}
+
+export interface Post {
+  slug: string;            // filename without date prefix and .mdx
+  date: string;
+  frontmatter: PostFrontmatter;
+  content: string;         // raw MDX body
+  filename: string;
+}
+
+const FILENAME_RE = /^(\d{4}-\d{2}-\d{2})-(.+)\.mdx$/;
+
+function resolveBlogDir(): string {
+  if (fs.existsSync(BLOG_DIR)) return BLOG_DIR;
+  if (fs.existsSync(BLOG_DIR_FALLBACK)) return BLOG_DIR_FALLBACK;
+  return BLOG_DIR; // best effort; downstream readdir will throw helpfully
+}
+
+function readPost(filename: string): Post | null {
+  const match = filename.match(FILENAME_RE);
+  if (!match) return null;
+  const [_, date, slug] = match;
+  const full = path.join(resolveBlogDir(), filename);
+  const { data, content } = matter(fs.readFileSync(full, 'utf8'));
+  const fm = data as Partial<PostFrontmatter>;
+  if (!fm.title || !fm.description || !fm.date || !fm.author) {
+    throw new Error(`Blog post ${filename} missing required frontmatter (title, description, date, author).`);
+  }
+  return {
+    slug,
+    date,
+    frontmatter: fm as PostFrontmatter,
+    content,
+    filename,
+  };
+}
+
+export function getAllPosts(opts: { includeDrafts?: boolean } = {}): Post[] {
+  const dir = resolveBlogDir();
+  const files = fs.readdirSync(dir).filter((f) => f.endsWith('.mdx'));
+  const posts: Post[] = [];
+  for (const f of files) {
+    const post = readPost(f);
+    if (!post) continue;
+    if (post.frontmatter.draft && !opts.includeDrafts) continue;
+    posts.push(post);
+  }
+  return posts.sort((a, b) => (a.date < b.date ? 1 : -1));
+}
+
+export function getPostBySlug(slug: string): Post | null {
+  return getAllPosts({ includeDrafts: true }).find((p) => p.slug === slug) ?? null;
+}
+
+export function getFeaturedPost(): Post | null {
+  const posts = getAllPosts();
+  return posts.find((p) => p.frontmatter.featured) ?? posts[0] ?? null;
+}
+
+export function getAllTags(): { tag: string; count: number }[] {
+  const tags = new Map<string, number>();
+  for (const p of getAllPosts()) {
+    for (const t of p.frontmatter.tags ?? []) {
+      tags.set(t, (tags.get(t) ?? 0) + 1);
+    }
+  }
+  return [...tags.entries()].map(([tag, count]) => ({ tag, count }));
+}
+```
+
+### 5.2 `apps/website/src/lib/blog-authors.ts` (new)
+
+```typescript
+// SPDX-License-Identifier: MIT
+export interface Author {
+  name: string;
+  role?: string;
+  bio?: string;
+  twitter?: string;       // handle without @
+  github?: string;        // handle without @
+  avatar?: string;        // path under /public, e.g. '/authors/brian.jpg'
+}
+
+export const blogAuthors: Record<string, Author> = {
+  brian: {
+    name: 'Brian Love',
+    role: 'Founder, Cacheplane',
+    bio: 'Angular consultant and open-source maintainer. Building agent UI for Angular teams.',
+    github: 'blove',
+  },
+} as const;
+
+export function getAuthor(key: string): Author {
+  return blogAuthors[key] ?? { name: key };
+}
+```
+
+### 5.3 `apps/website/src/app/blog/page.tsx` (new)
+
+Server component. Composition:
+
+```tsx
+import { Container, Section, Eyebrow } from '@/components/ui/*';
+import { FeaturedPostCard } from '@/components/blog/FeaturedPostCard';
+import { PostCard } from '@/components/blog/PostCard';
+import { TagChips } from '@/components/blog/TagChips';
+import { getAllPosts, getFeaturedPost, getAllTags } from '@/lib/blog';
+import { createPageMetadata } from '@/lib/site-metadata';
+
+export const metadata = createPageMetadata({
+  title: 'Blog — Cacheplane',
+  description: 'Long-form writing on agent UI for Angular: streaming, generative UI, threads, interrupts, production patterns.',
+  pathname: '/blog',
+  type: 'website',
+});
+
+export default function BlogIndex() {
+  const all = getAllPosts();
+  const featured = getFeaturedPost();
+  const rest = featured ? all.filter((p) => p.slug !== featured.slug) : all;
+  const tags = getAllTags();
+  return (
+    <Section surface="canvas">
+      <Container>
+        <Eyebrow>Blog</Eyebrow>
+        <h1>Notes from Cacheplane</h1>
+        <p>Writing on agent UI for Angular — production patterns, design choices, and what we're shipping.</p>
+        <TagChips tags={tags.map(t => t.tag)} />
+        {featured && <FeaturedPostCard post={featured} />}
+        <div /* grid */>
+          {rest.map((p) => <PostCard key={p.slug} post={p} />)}
+        </div>
+      </Container>
+    </Section>
+  );
+}
+```
+
+(Markup, styles, and exact composition follow existing cacheplane site patterns. The implementer adapts spacing/tokens to match the existing landing/pricing aesthetic.)
+
+### 5.4 `apps/website/src/app/blog/[slug]/page.tsx` (new)
+
+```tsx
+import { notFound } from 'next/navigation';
+import type { Metadata } from 'next';
+import { MdxRenderer } from '@/components/docs/MdxRenderer';
+import { AuthorByline } from '@/components/blog/AuthorByline';
+import { getAllPosts, getPostBySlug } from '@/lib/blog';
+import { getAuthor } from '@/lib/blog-authors';
+import { createPageMetadata } from '@/lib/site-metadata';
+
+interface Params {
+  params: Promise<{ slug: string }>;
+}
+
+export function generateStaticParams() {
+  return getAllPosts().map((p) => ({ slug: p.slug }));
+}
+
+export async function generateMetadata({ params }: Params): Promise<Metadata> {
+  const { slug } = await params;
+  const post = getPostBySlug(slug);
+  if (!post) return { title: 'Post not found — Cacheplane' };
+  return createPageMetadata({
+    title: `${post.frontmatter.title} — Cacheplane`,
+    description: post.frontmatter.description,
+    pathname: `/blog/${post.slug}`,
+    type: 'article',
+  });
+}
+
+export default async function BlogPostPage({ params }: Params) {
+  const { slug } = await params;
+  const post = getPostBySlug(slug);
+  if (!post || post.frontmatter.draft) notFound();
+  const author = getAuthor(post.frontmatter.author);
+  return (
+    <article>
+      <header>
+        <time dateTime={post.frontmatter.date}>{post.frontmatter.date}</time>
+        <h1>{post.frontmatter.title}</h1>
+        <AuthorByline author={author} />
+      </header>
+      <MdxRenderer source={post.content} library="agent" section="" />
+      {/* tag chips + share + related-posts strip below */}
+    </article>
+  );
+}
+```
+
+`<MdxRenderer>` already exists; it accepts `library` and `section` for in-doc anchor patterns. The blog passes nominal values — these don't matter for MDX rendering but satisfy the existing prop contract. (Implementer may extract a smaller `<BlogMdxRenderer>` if the docs prop contract becomes awkward, but reuse is preferred.)
+
+### 5.5 `apps/website/src/components/blog/AuthorByline.tsx` (new)
+
+```tsx
+import type { Author } from '@/lib/blog-authors';
+export function AuthorByline({ author }: { author: Author }) {
+  return (
+    <div className="blog-author">
+      {author.avatar && <img src={author.avatar} alt={`${author.name} avatar`} width={32} height={32} />}
+      <div>
+        <span className="blog-author__name">{author.name}</span>
+        {author.role && <span className="blog-author__role"> · {author.role}</span>}
+      </div>
+    </div>
+  );
+}
+```
+
+### 5.6 `apps/website/src/components/blog/{PostCard,FeaturedPostCard,TagChips}.tsx` (new)
+
+Three small presentational components — implementer composes from existing `@/components/ui/{Card, Pill, Eyebrow}`. PostCard shows: title, description, date, tags, author. FeaturedPostCard is a larger variant. TagChips renders `<Pill>` rows from a string array; click is a no-op in v1 (per-tag pages are a follow-up).
+
+### 5.7 `apps/website/src/app/blog/[slug]/opengraph-image.tsx` (new)
+
+```tsx
+import { ImageResponse } from 'next/og';
+import { getPostBySlug } from '@/lib/blog';
+import { getAuthor } from '@/lib/blog-authors';
+
+export const runtime = 'nodejs';
+export const alt = 'Cacheplane blog post';
+export const size = { width: 1200, height: 630 };
+export const contentType = 'image/png';
+
+export default async function og({ params }: { params: { slug: string } }) {
+  const post = getPostBySlug(params.slug);
+  if (!post) {
+    return new ImageResponse(<div /* default fallback */>Cacheplane</div>, size);
+  }
+  const author = getAuthor(post.frontmatter.author);
+  return new ImageResponse(
+    (
+      <div /* JSX layout: post title big + author small bottom */>
+        <h1>{post.frontmatter.title}</h1>
+        <div>{author.name} · {post.frontmatter.date}</div>
+      </div>
+    ),
+    { ...size, fonts: [/* reuse the Garamond font loaded in the site-default OG route */] },
+  );
+}
+```
+
+### 5.8 `apps/website/src/app/blog/rss.xml/route.ts` (new)
+
+```typescript
+import { NextResponse } from 'next/server';
+import { getAllPosts } from '@/lib/blog';
+import { SITE_ORIGIN } from '@/lib/site-metadata';
+
+export async function GET() {
+  const posts = getAllPosts();
+  const items = posts.map((p) => `
+    <item>
+      <title><![CDATA[${p.frontmatter.title}]]></title>
+      <link>${SITE_ORIGIN}/blog/${p.slug}</link>
+      <guid>${SITE_ORIGIN}/blog/${p.slug}</guid>
+      <pubDate>${new Date(p.frontmatter.date).toUTCString()}</pubDate>
+      <description><![CDATA[${p.frontmatter.description}]]></description>
+    </item>
+  `).join('');
+  const xml = `<?xml version="1.0" encoding="UTF-8" ?>
+<rss version="2.0">
+  <channel>
+    <title>Cacheplane Blog</title>
+    <link>${SITE_ORIGIN}/blog</link>
+    <description>Writing on agent UI for Angular.</description>
+    <language>en</language>
+    ${items}
+  </channel>
+</rss>`;
+  return new NextResponse(xml, { headers: { 'Content-Type': 'application/rss+xml; charset=utf-8' } });
+}
+```
+
+### 5.9 `apps/website/src/lib/site-metadata.ts` (modified)
+
+Extend `getSitemapRoutes()`:
+
+```typescript
+import { getAllPosts } from './blog';
+
+export function getSitemapRoutes(): string[] {
+  const staticRoutes = ['/', '/angular', '/render', '/chat', '/pricing', '/solutions', '/pilot-to-prod', '/docs', '/blog'];
+  const solutionRoutes = getAllSolutionSlugs().map((slug) => `/solutions/${slug}`);
+  const docsRoutes = docsConfig.flatMap(/* unchanged */);
+  const blogRoutes = getAllPosts().map((p) => `/blog/${p.slug}`);
+  return [...staticRoutes, ...solutionRoutes, ...docsRoutes, ...blogRoutes];
+}
+```
+
+### 5.10 `apps/website/src/lib/analytics/events.ts` (modified)
+
+Add to `analyticsEvents`:
+
+```typescript
+blogCtaClick: 'blog:cta_click',
+blogCopyCodeClick: 'blog:copy_code_click',
+```
+
+Add `'blog'` to `AnalyticsSurface` union. The existing `cta_id` and `code_lang` properties already have homes in `AnalyticsProperties`.
+
+### 5.11 `docs/gtm/taxonomy.md` (modified)
+
+Add two rows under "Marketing (website)" (or in a new "Blog (website)" subsection — implementer's call which reads cleaner):
+
+| Event                       | When                                           |
+|-----------------------------|------------------------------------------------|
+| `blog:cta_click`            | A tracked CTA inside a blog post body          |
+| `blog:copy_code_click`      | Copy-button click on a code block in a post    |
+
+Append to the version log:
+
+```
+| 2026-05-17 | Add blog:cta_click + blog:copy_code_click events (Spec 5). |
+```
+
+### 5.12 `apps/website/src/components/shared/Nav.tsx` (or wherever) (modified)
+
+Insert a `Blog` link in the appropriate spot in the existing nav. Existing CTA tracking on nav links (per Spec 2) flows through `cta_id` — add `nav_blog` to the `CtaId` template-literal union if the implementer needs it (it's already covered by the existing `nav_${string}` pattern).
+
+## 6. Seed post — voice, structure, content
+
+### Voice (study these before drafting)
+
+The seed post matches Brian Love's existing blog voice. Read these three posts FIRST and match the patterns:
+
+- `~/repos/brianflove/src/content/posts/2026-02-21-the-frontend-reward-loop-for-agentic-software.md`
+- `~/repos/brianflove/src/content/posts/2026-03-18-agentic-memory-and-what-it-means-for-web-apps.md`
+- `~/repos/brianflove/src/content/posts/2026-02-20-the-landscape-of-generative-ui-in-2026.md`
+
+Observed patterns to replicate:
+
+- **Open with a blunt thesis.** No "introduction" header. Just the claim, stated in 1-2 lines.
+- **One thought per line.** Frequent paragraph breaks. Paragraphs of 1-3 short sentences.
+- **`## tl;dr` section early.** Bullet list, 4-6 items, each 1 line.
+- **Numbered frameworks.** "1. X / 2. Y / 3. Z" — short, declarative, often with subheads under each number.
+- **Contrast moves.** "Not because X. And not because Y. It matters because Z."
+- **Pragmatic second person.** "If you are building...", "Most teams...", "If I were starting today...".
+- **Heuristic + buckets.** When introducing a framework, name 3-5 buckets and unpack each.
+- **No marketing voice.** No "industry-leading", no "powerful", no superlatives. Direct claims about what works.
+- **Hyphens are em-dashes.** Brian uses `—` and `:` heavily for structural breaks.
+- **No emoji.** No 🚀.
+
+### Structure of the seed post (~2,500 words)
+
+**Title:** `Build a streaming chat UI in Angular with LangGraph`
+**Description:** `Step-by-step tutorial for shipping a production streaming chat in Angular — signal-native, design-system-friendly, and wired to a LangGraph backend.`
+**Tags:** `[tutorial, streaming, langgraph, angular]`
+**Date:** `2026-05-17`
+**Author:** `brian`
+**Featured:** `true`
+
+Sections:
+
+1. **Opening thesis** (~150 words). Why streaming is the production-vs-demo line for chat UIs. State the claim: in Angular, Signals make streaming feel native if you wire it right.
+2. **tl;dr** (~80 words, bullets).
+   - Streaming chat is a signal problem, not a streaming problem.
+   - `@ngaf/chat` gives you the composition. `@ngaf/langgraph` gives you the wire.
+   - The agent contract is a small, signal-shaped interface.
+   - Production patterns: errors, retries, threads, interrupts, fallbacks.
+   - One install. Standalone components. No React rewrite.
+3. **Why streaming is the production-vs-demo line** (~200 words). Latency perception, abandonment, the value of seeing partial responses.
+4. **Architecture in three boxes** (~250 words). LangGraph backend → `@ngaf/langgraph` adapter → `@ngaf/chat` UI. Each box has one job. Use `ArchFlowDiagram` MDX component.
+5. **Scaffold** (~300 words). `npm install @ngaf/chat @ngaf/langgraph`. `app.config.ts` with `provideAgent({ apiUrl })`. Component-level `agent()` factory. Code blocks in `typescript`.
+6. **Render the chat** (~300 words). `<chat [agent]="agent">`. Welcome state. Suggestions. Code block + screenshot reference.
+7. **What's happening under the hood** (~300 words). The agent contract. `events$`. State signals. Why this maps cleanly to Angular templates.
+8. **Production patterns** (~400 words). Three buckets: errors + retries, threads + persistence, generative UI fallbacks. Light on detail per bucket — link out to docs for depth.
+9. **Where to go from here** (~150 words). Links: cockpit streaming recipe, persistence post (when it ships), interrupts post, comparison pages (when they ship). End with `<Callout type="info">` directing enterprise readers to `/contact` for engineering support.
+10. **Closing line.** One sentence. No "TL;DR repeat", no marketing close.
+
+### Required MDX components in the seed post
+
+- `<Callout type="info">` for the enterprise-track CTA at the end.
+- `<Steps>` for the scaffold section (so each step gets a numbered indicator).
+- `<Tabs>` if multiple package managers are shown (npm/pnpm/yarn) — optional.
+- `<ArchFlowDiagram>` for the architecture diagram (if it accepts a custom set of nodes; otherwise use a mermaid block or skip in v1).
+- Inline `<a href="/contact?source=blog_streaming_pillar&track=enterprise">` for tracked CTAs.
+
+## 7. Data flow
+
+For a developer landing on `cacheplane.ai/blog/build-a-streaming-chat-ui-in-angular-with-langgraph`:
+
+1. `BlogPostPage` resolves the slug via `getPostBySlug()`.
+2. `MdxRenderer` renders the MDX body with code-highlighted blocks and our docs MDX components.
+3. The route's `opengraph-image.tsx` generates a 1200×630 PNG with the post title.
+4. `$pageview` fires with `source_page: '/blog/<slug>'`.
+5. If the reader clicks a tracked CTA (e.g., `/pricing` link in the production-patterns section), `blog:cta_click` fires with `surface: 'blog'`, `destination_url`, and optional `cta_id`.
+6. If they hit copy on a code block, `blog:copy_code_click` fires with `surface: 'blog'` and `code_lang`.
+
+For the RSS subscriber:
+
+1. RSS reader fetches `/blog/rss.xml`.
+2. Server reads all posts, emits RSS 2.0.
+3. Reader displays the latest entries.
+
+## 8. Error handling
+
+- **Missing required frontmatter** in any blog post → `getAllPosts()` throws with a clear filename + missing-field message. The throw fails the build, which is what we want (forces fix at PR time).
+- **Slug collision** (same slug across two different filenames) → undefined behavior (last-write wins). Acceptable for v1; revisit if it ever bites.
+- **Bad date** in frontmatter → date used as-is for sort + display. `new Date(badDate).toUTCString()` becomes "Invalid Date" in RSS. Catch in implementation via a small validation step in `readPost`.
+- **Per-post OG image generation failure** → the route falls back to the default site OG card. The post page itself still renders.
+
+## 9. Testing
+
+- **`apps/website/src/lib/blog.spec.ts`:**
+  - `getAllPosts()` returns sorted desc by date.
+  - `getPostBySlug()` returns a known seed.
+  - Frontmatter parsing populates required fields.
+  - Missing required field throws.
+  - Draft posts excluded by default; included when `includeDrafts: true`.
+- **`apps/website/src/components/blog/PostCard.spec.tsx`:**
+  - Renders title, date, tag chips.
+- **Per-route smoke** (manual, post-merge): visit `/blog`, `/blog/[seed-slug]`, `/blog/rss.xml`, check OG card via `view-source` and a Twitter/OpenGraph debugger.
+- **Pre-existing `apps/website` vitest tests + build** remain green.
+
+## 10. Risks
+
+- **Reading MDX in a server route every request** is wasteful in dev. Next.js's static-param caching covers prod; for dev, it's a few-ms per request. Acceptable.
+- **`<MdxRenderer>` doc-prop contract** (`library`, `section`) may feel awkward when reused for blog posts. If awkward in practice, extract a smaller `<BlogMdxRenderer>` that wraps the same `MDXRemote` + components but drops the doc-only props. Implementer decides.
+- **Seed-post content quality** is the highest variance item. The plan instructs the implementer to study Brian's voice samples first. If the draft falls short, you (Brian) review and revise post-merge.
+- **OG image route reading `[slug]` params:** Next.js's docs claim per-route `opengraph-image.tsx` can access `params`. If it can't (test in implementation), the fallback is a `/blog/og/[slug]/route.tsx` dynamic OG endpoint, with `<head>` updated to reference it. Implementer chooses the working path.
+- **Per-tag pages absent in v1.** Tag chips on the index don't navigate anywhere; they may confuse users. Mitigated by either (a) making them visual-only (no click), or (b) shipping a tiny `/blog/tags/[tag]` page in the same spec. Implementer should pick (a) for v1 scope and the user can revisit in a follow-up.
+
+## 11. Phases
+
+1. **Phase 0 — `blog.ts` + `blog-authors.ts` + spec (TDD).** Post parser, author registry. ~2 commits.
+2. **Phase 1 — Analytics events + taxonomy + Nav.** Add `blog:*` events to `events.ts`, `taxonomy.md`, and a `Blog` link in the navbar. ~1 commit.
+3. **Phase 2 — Blog index page + `PostCard` + `FeaturedPostCard` + `TagChips`.** ~2 commits.
+4. **Phase 3 — Dynamic `[slug]` route + `AuthorByline`.** Reuses `<MdxRenderer>`. ~2 commits.
+5. **Phase 4 — Per-post OG image route.** ~1 commit.
+6. **Phase 5 — RSS feed.** ~1 commit.
+7. **Phase 6 — Sitemap integration.** ~1 commit.
+8. **Phase 7 — Seed pillar post MDX.** ~1 commit (likely the largest commit in the spec — the post body itself).
+9. **Phase 8 — Verification + Chrome MCP smoke.** No commit.
+
+Total: ~11-12 commits.
+
+## 12. Deliverables
+
+- ☐ `apps/website/src/lib/blog.ts` + spec
+- ☐ `apps/website/src/lib/blog-authors.ts`
+- ☐ `apps/website/src/app/blog/page.tsx`
+- ☐ `apps/website/src/app/blog/[slug]/page.tsx`
+- ☐ `apps/website/src/app/blog/[slug]/opengraph-image.tsx`
+- ☐ `apps/website/src/app/blog/rss.xml/route.ts`
+- ☐ `apps/website/src/components/blog/{PostCard,FeaturedPostCard,TagChips,AuthorByline}.tsx`
+- ☐ `apps/website/src/components/blog/PostCard.spec.tsx`
+- ☐ `apps/website/src/lib/site-metadata.ts` updated
+- ☐ `apps/website/src/lib/analytics/events.ts` adds `blog:cta_click` + `blog:copy_code_click` + `'blog'` surface
+- ☐ `docs/gtm/taxonomy.md` adds the two events + changelog row
+- ☐ `apps/website/src/components/shared/Nav.tsx` (or wherever) adds `Blog` link
+- ☐ `apps/website/content/blog/2026-05-17-build-a-streaming-chat-ui-in-angular-with-langgraph.mdx` — seed post written in Brian's voice
+- ☐ `nx run website:build` green
+- ☐ `cd apps/website && npx vitest run src/lib/blog.spec.ts src/components/blog` green
+- ☐ Manual smoke: `/blog`, `/blog/[seed-slug]`, `/blog/rss.xml`, OG card preview

From 61d1c81c9e1d18d890012e590848593b315cb3da Mon Sep 17 00:00:00 2001
From: Brian Love <brian@liveloveapp.com>
Date: Sat, 16 May 2026 21:39:43 -0700
Subject: [PATCH 02/20] docs(gtm): plan for content-pillar-pages blog (Spec 5)

18 tasks across 7 phases: gray-matter dep, blog.ts parser (TDD),
author registry, analytics events, taxonomy, blog components, nav,
index + slug routes, per-post OG, RSS, sitemap, seed pillar post in
Brian's voice, build verification, PR.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
---
 .../gtm/2026-05-17-content-pillar-pages.md    | 1657 +++++++++++++++++
 1 file changed, 1657 insertions(+)
 create mode 100644 docs/superpowers/plans/gtm/2026-05-17-content-pillar-pages.md

diff --git a/docs/superpowers/plans/gtm/2026-05-17-content-pillar-pages.md b/docs/superpowers/plans/gtm/2026-05-17-content-pillar-pages.md
new file mode 100644
index 000000000..f8aca8c41
--- /dev/null
+++ b/docs/superpowers/plans/gtm/2026-05-17-content-pillar-pages.md
@@ -0,0 +1,1657 @@
+# Content Pillar Pages (Blog) Implementation Plan
+
+> **For agentic workers:** REQUIRED SUB-SKILL: Use superpowers:subagent-driven-development (recommended) or superpowers:executing-plans to implement this plan task-by-task. Steps use checkbox (`- [ ]`) syntax for tracking.
+
+**Goal:** Ship a production-grade `/blog` on cacheplane.ai (flat MDX, RSS, OG, sitemap, `blog:*` analytics) plus one seed pillar post written in Brian Love's voice — "Build a streaming chat UI in Angular with LangGraph."
+
+**Architecture:** Date-prefixed MDX files in `apps/website/content/blog/` parsed at request/build time by `lib/blog.ts` (gray-matter). Index + dynamic slug routes reuse the existing `<MdxRenderer>`. Per-post OG via `next/og` ImageResponse. RSS 2.0 XML route. Sitemap auto-includes published posts. New `blog:*` analytics namespace.
+
+**Tech Stack:** Next.js 16 App Router, `next-mdx-remote/rsc@6`, `gray-matter@4` (new), `rehype-pretty-code` (tokyo-night), `rehype-slug`, `remark-gfm`, Vitest + jsdom for unit tests, PostHog client wrapper.
+
+**Spec reference:** `docs/superpowers/specs/gtm/2026-05-17-content-pillar-pages-design.md`. Branch: `gtm-spec-5-content-pillar-blog` (already created in worktree).
+
+---
+
+## File Structure
+
+**New:**
+
+- `apps/website/content/blog/2026-05-17-build-a-streaming-chat-ui-in-angular-with-langgraph.mdx` — seed post (Phase 7).
+- `apps/website/src/lib/blog.ts` — MDX parser + listing utilities.
+- `apps/website/src/lib/blog.spec.ts` — unit tests for blog.ts.
+- `apps/website/src/lib/blog-authors.ts` — author registry.
+- `apps/website/src/app/blog/page.tsx` — index page (Server Component).
+- `apps/website/src/app/blog/[slug]/page.tsx` — dynamic post route.
+- `apps/website/src/app/blog/[slug]/opengraph-image.tsx` — per-post OG card.
+- `apps/website/src/app/blog/rss.xml/route.ts` — RSS 2.0 endpoint.
+- `apps/website/src/components/blog/PostCard.tsx`
+- `apps/website/src/components/blog/PostCard.spec.tsx`
+- `apps/website/src/components/blog/FeaturedPostCard.tsx`
+- `apps/website/src/components/blog/TagChips.tsx`
+- `apps/website/src/components/blog/AuthorByline.tsx`
+- `apps/website/content/blog/.gitkeep` — only if Phase 7 isn't ordered before tests (Phase 7 will exist before tests are run in `nx build`, so the .gitkeep isn't required; created defensively in Phase 0 so dev work can run).
+
+**Modified:**
+
+- `apps/website/src/lib/site-metadata.ts` — add `/blog` static route + blog routes to `getSitemapRoutes()`.
+- `apps/website/src/lib/analytics/events.ts` — add `blogCtaClick`, `blogCopyCodeClick`, add `'blog'` to `AnalyticsSurface`.
+- `apps/website/src/components/shared/Nav.tsx` — add `Blog` link.
+- `docs/gtm/taxonomy.md` — document new events + changelog row.
+- `package.json` (root) — add `gray-matter@^4.0.3` to `dependencies`.
+
+---
+
+## Task 1: Add `gray-matter` dependency
+
+**Files:**
+
+- Modify: `package.json` (root)
+
+- [ ] **Step 1: Add gray-matter to root package.json dependencies**
+
+Edit root `package.json` to add `"gray-matter": "^4.0.3"` to the `dependencies` block (alphabetical with surrounding entries).
+
+- [ ] **Step 2: Install without regenerating lockfile shape**
+
+Run: `npm install gray-matter@^4.0.3 --save --package-lock-only`
+Then: `npm install --no-audit --no-fund`
+Expected: gray-matter present in `node_modules/gray-matter`; package-lock.json updated minimally. Do NOT regenerate the full lockfile (per project memory: never run a full `npm install` on macOS that touches `@next/swc-*` bindings).
+
+- [ ] **Step 3: Verify import works**
+
+Run: `node -e "console.log(require('gray-matter')('---\ntitle: t\n---\nbody').data)"`
+Expected: `{ title: 't' }`
+
+- [ ] **Step 4: Commit**
+
+```bash
+git add package.json package-lock.json
+git commit -m "chore(website): add gray-matter for blog frontmatter parsing"
+```
+
+---
+
+## Task 2: Create blog content directory + seed fixture file for tests
+
+**Files:**
+
+- Create: `apps/website/content/blog/.gitkeep`
+- Create: `apps/website/content/blog/__fixtures__/2026-01-01-fixture-post.mdx` (test fixture; under `__fixtures__/` so the parser's date-regex filter ignores it via subdir filtering — see Task 3 implementation)
+
+- [ ] **Step 1: Create the directory and .gitkeep**
+
+```bash
+mkdir -p apps/website/content/blog
+touch apps/website/content/blog/.gitkeep
+```
+
+- [ ] **Step 2: Skip creating __fixtures__ here** — the unit tests in Task 3 will use `fs` mocking instead of on-disk fixtures, so we don't need a fixture file. Remove the __fixtures__ line above conceptually; only `.gitkeep` is created.
+
+- [ ] **Step 3: Commit**
+
+```bash
+git add apps/website/content/blog/.gitkeep
+git commit -m "feat(website): scaffold blog content directory"
+```
+
+---
+
+## Task 3: `lib/blog.ts` — frontmatter parser + listing utilities (TDD)
+
+**Files:**
+
+- Create: `apps/website/src/lib/blog.ts`
+- Create: `apps/website/src/lib/blog.spec.ts`
+
+- [ ] **Step 1: Write failing tests**
+
+Create `apps/website/src/lib/blog.spec.ts`:
+
+```typescript
+import { describe, expect, it, vi, beforeEach, afterEach } from 'vitest';
+import * as fs from 'fs';
+import * as path from 'path';
+
+vi.mock('fs');
+const mockedFs = vi.mocked(fs);
+
+const post1 = `---
+title: "First Post"
+description: "First description"
+date: 2026-05-01
+author: brian
+tags: [tutorial, streaming]
+---
+Body one.`;
+
+const post2 = `---
+title: "Second Post"
+description: "Second description"
+date: 2026-05-10
+author: brian
+featured: true
+---
+Body two.`;
+
+const draft = `---
+title: "Draft Post"
+description: "Draft description"
+date: 2026-05-20
+author: brian
+draft: true
+---
+Body draft.`;
+
+const missingFields = `---
+title: "Missing"
+date: 2026-05-15
+---
+Body missing.`;
+
+function setupFs(files: Record<string, string>) {
+  mockedFs.existsSync.mockImplementation((p) => {
+    const str = String(p);
+    return str.endsWith('/content/blog') || str in files;
+  });
+  mockedFs.readdirSync.mockReturnValue(Object.keys(files).map((k) => k.split('/').pop()!) as never);
+  mockedFs.readFileSync.mockImplementation((p) => {
+    const name = String(p).split('/').pop()!;
+    const match = Object.entries(files).find(([k]) => k.endsWith(name));
+    if (!match) throw new Error(`no fixture for ${p}`);
+    return match[1];
+  });
+}
+
+beforeEach(() => {
+  vi.resetAllMocks();
+});
+
+afterEach(() => {
+  vi.restoreAllMocks();
+});
+
+describe('blog.ts', () => {
+  it('getAllPosts returns posts sorted desc by date', async () => {
+    setupFs({
+      '2026-05-01-first-post.mdx': post1,
+      '2026-05-10-second-post.mdx': post2,
+    });
+    const { getAllPosts } = await import('./blog');
+    const posts = getAllPosts();
+    expect(posts.map((p) => p.slug)).toEqual(['second-post', 'first-post']);
+  });
+
+  it('getPostBySlug returns a known post', async () => {
+    setupFs({
+      '2026-05-01-first-post.mdx': post1,
+      '2026-05-10-second-post.mdx': post2,
+    });
+    const { getPostBySlug } = await import('./blog');
+    const post = getPostBySlug('second-post');
+    expect(post?.frontmatter.title).toBe('Second Post');
+    expect(post?.date).toBe('2026-05-10');
+  });
+
+  it('getPostBySlug returns null for unknown slug', async () => {
+    setupFs({ '2026-05-01-first-post.mdx': post1 });
+    const { getPostBySlug } = await import('./blog');
+    expect(getPostBySlug('nope')).toBeNull();
+  });
+
+  it('throws when required frontmatter is missing', async () => {
+    setupFs({ '2026-05-15-missing.mdx': missingFields });
+    const { getAllPosts } = await import('./blog');
+    expect(() => getAllPosts()).toThrow(/missing required frontmatter/i);
+  });
+
+  it('drafts excluded by default, included with includeDrafts', async () => {
+    setupFs({
+      '2026-05-10-second-post.mdx': post2,
+      '2026-05-20-draft-post.mdx': draft,
+    });
+    const { getAllPosts } = await import('./blog');
+    expect(getAllPosts().map((p) => p.slug)).toEqual(['second-post']);
+    expect(getAllPosts({ includeDrafts: true }).map((p) => p.slug)).toEqual([
+      'draft-post',
+      'second-post',
+    ]);
+  });
+
+  it('getFeaturedPost returns the first featured post', async () => {
+    setupFs({
+      '2026-05-01-first-post.mdx': post1,
+      '2026-05-10-second-post.mdx': post2,
+    });
+    const { getFeaturedPost } = await import('./blog');
+    expect(getFeaturedPost()?.slug).toBe('second-post');
+  });
+
+  it('getFeaturedPost falls back to latest when none featured', async () => {
+    setupFs({ '2026-05-01-first-post.mdx': post1 });
+    const { getFeaturedPost } = await import('./blog');
+    expect(getFeaturedPost()?.slug).toBe('first-post');
+  });
+
+  it('getAllTags counts tags across posts', async () => {
+    setupFs({
+      '2026-05-01-first-post.mdx': post1,
+      '2026-05-10-second-post.mdx': post2,
+    });
+    const { getAllTags } = await import('./blog');
+    const tags = getAllTags();
+    expect(tags.find((t) => t.tag === 'tutorial')?.count).toBe(1);
+    expect(tags.find((t) => t.tag === 'streaming')?.count).toBe(1);
+  });
+
+  it('ignores files that do not match the date-prefix regex', async () => {
+    setupFs({
+      '2026-05-01-first-post.mdx': post1,
+      'not-a-post.mdx': post1,
+      'README.md': 'readme',
+    });
+    const { getAllPosts } = await import('./blog');
+    expect(getAllPosts().map((p) => p.slug)).toEqual(['first-post']);
+  });
+});
+```
+
+- [ ] **Step 2: Run tests to verify they fail**
+
+Run: `cd apps/website && npx vitest run src/lib/blog.spec.ts`
+Expected: FAIL with "Cannot find module './blog'" or similar.
+
+- [ ] **Step 3: Implement `blog.ts`**
+
+Create `apps/website/src/lib/blog.ts`:
+
+```typescript
+// SPDX-License-Identifier: MIT
+import fs from 'fs';
+import path from 'path';
+import matter from 'gray-matter';
+
+const BLOG_DIR_WORKSPACE = path.join(process.cwd(), 'apps', 'website', 'content', 'blog');
+const BLOG_DIR_LOCAL = path.join(process.cwd(), 'content', 'blog');
+
+export interface PostFrontmatter {
+  title: string;
+  description: string;
+  date: string;
+  tags?: string[];
+  author: string;
+  featured?: boolean;
+  draft?: boolean;
+}
+
+export interface Post {
+  slug: string;
+  date: string;
+  frontmatter: PostFrontmatter;
+  content: string;
+  filename: string;
+}
+
+const FILENAME_RE = /^(\d{4}-\d{2}-\d{2})-(.+)\.mdx$/;
+
+function resolveBlogDir(): string {
+  if (fs.existsSync(BLOG_DIR_WORKSPACE)) return BLOG_DIR_WORKSPACE;
+  if (fs.existsSync(BLOG_DIR_LOCAL)) return BLOG_DIR_LOCAL;
+  return BLOG_DIR_WORKSPACE;
+}
+
+function readPost(dir: string, filename: string): Post | null {
+  const match = filename.match(FILENAME_RE);
+  if (!match) return null;
+  const [, date, slug] = match;
+  const full = path.join(dir, filename);
+  const raw = fs.readFileSync(full, 'utf8');
+  const { data, content } = matter(typeof raw === 'string' ? raw : raw.toString());
+  const fm = data as Partial<PostFrontmatter>;
+  if (!fm.title || !fm.description || !fm.date || !fm.author) {
+    throw new Error(
+      `Blog post ${filename} missing required frontmatter (title, description, date, author).`,
+    );
+  }
+  return {
+    slug,
+    date,
+    frontmatter: fm as PostFrontmatter,
+    content,
+    filename,
+  };
+}
+
+export function getAllPosts(opts: { includeDrafts?: boolean } = {}): Post[] {
+  const dir = resolveBlogDir();
+  if (!fs.existsSync(dir)) return [];
+  const files = fs.readdirSync(dir).filter((f) => typeof f === 'string' && f.endsWith('.mdx'));
+  const posts: Post[] = [];
+  for (const f of files) {
+    const post = readPost(dir, f as string);
+    if (!post) continue;
+    if (post.frontmatter.draft && !opts.includeDrafts) continue;
+    posts.push(post);
+  }
+  return posts.sort((a, b) => (a.date < b.date ? 1 : -1));
+}
+
+export function getPostBySlug(slug: string): Post | null {
+  return getAllPosts({ includeDrafts: true }).find((p) => p.slug === slug) ?? null;
+}
+
+export function getFeaturedPost(): Post | null {
+  const posts = getAllPosts();
+  return posts.find((p) => p.frontmatter.featured) ?? posts[0] ?? null;
+}
+
+export function getAllTags(): { tag: string; count: number }[] {
+  const tags = new Map<string, number>();
+  for (const p of getAllPosts()) {
+    for (const t of p.frontmatter.tags ?? []) {
+      tags.set(t, (tags.get(t) ?? 0) + 1);
+    }
+  }
+  return [...tags.entries()].map(([tag, count]) => ({ tag, count }));
+}
+
+export function getAllSlugs(): string[] {
+  return getAllPosts().map((p) => p.slug);
+}
+```
+
+- [ ] **Step 4: Run tests to verify they pass**
+
+Run: `cd apps/website && npx vitest run src/lib/blog.spec.ts`
+Expected: PASS, 9 tests.
+
+- [ ] **Step 5: Commit**
+
+```bash
+git add apps/website/src/lib/blog.ts apps/website/src/lib/blog.spec.ts
+git commit -m "feat(website): add blog frontmatter parser + listing utilities"
+```
+
+---
+
+## Task 4: `lib/blog-authors.ts` — author registry
+
+**Files:**
+
+- Create: `apps/website/src/lib/blog-authors.ts`
+
+- [ ] **Step 1: Create the file**
+
+```typescript
+// SPDX-License-Identifier: MIT
+export interface Author {
+  name: string;
+  role?: string;
+  bio?: string;
+  twitter?: string;
+  github?: string;
+  avatar?: string;
+}
+
+export const blogAuthors: Record<string, Author> = {
+  brian: {
+    name: 'Brian Love',
+    role: 'Founder, Cacheplane',
+    bio: 'Angular consultant and open-source maintainer. Building agent UI for Angular teams.',
+    github: 'blove',
+  },
+};
+
+export function getAuthor(key: string): Author {
+  return blogAuthors[key] ?? { name: key };
+}
+```
+
+- [ ] **Step 2: Commit**
+
+```bash
+git add apps/website/src/lib/blog-authors.ts
+git commit -m "feat(website): add blog author registry"
+```
+
+---
+
+## Task 5: Analytics events + AnalyticsSurface
+
+**Files:**
+
+- Modify: `apps/website/src/lib/analytics/events.ts`
+
+- [ ] **Step 1: Add events**
+
+Edit `apps/website/src/lib/analytics/events.ts`. Inside the `analyticsEvents` `const` object, after `docsSidebarSectionToggle: 'docs:sidebar_section_toggle',` add:
+
+```typescript
+  blogCtaClick: 'blog:cta_click',
+  blogCopyCodeClick: 'blog:copy_code_click',
+```
+
+In the `AnalyticsSurface` union, add `'blog'` after `'docs'`:
+
+```typescript
+export type AnalyticsSurface =
+  | 'nav'
+  | 'mobile_nav'
+  | 'footer'
+  | 'home'
+  | 'home_whitepaper'
+  | 'pricing'
+  | 'docs'
+  | 'blog'
+  | 'library_landing'
+  | 'solution'
+  | 'toast'
+  | 'contact';
+```
+
+- [ ] **Step 2: Verify typecheck**
+
+Run: `cd apps/website && npx tsc --noEmit -p tsconfig.json`
+Expected: no new errors related to events.ts.
+
+- [ ] **Step 3: Commit**
+
+```bash
+git add apps/website/src/lib/analytics/events.ts
+git commit -m "feat(website): add blog:* analytics events + blog surface"
+```
+
+---
+
+## Task 6: Update `taxonomy.md`
+
+**Files:**
+
+- Modify: `docs/gtm/taxonomy.md`
+
+- [ ] **Step 1: Locate the marketing/website events table and the changelog**
+
+Run: `grep -n "docs:copy_code_click\|Version log\|## Version" docs/gtm/taxonomy.md | head -20`
+
+- [ ] **Step 2: Append two rows under the website events table**
+
+After the row for `docs:copy_code_click`, insert:
+
+```
+| `blog:cta_click`              | Tracked CTA inside a blog post body. Props: `surface: 'blog'`, `cta_id?`, `destination_url?`.   |
+| `blog:copy_code_click`        | Copy-button click on a code block inside a blog post. Props: `surface: 'blog'`, `code_lang?`.    |
+```
+
+(If the table column widths differ in the existing doc, match those — the implementer keeps consistent column alignment.)
+
+- [ ] **Step 3: Append a changelog row**
+
+Append to the bottom of the version log table:
+
+```
+| 2026-05-17 | Add `blog:cta_click` + `blog:copy_code_click` events; add `'blog'` to `AnalyticsSurface` (Spec 5). |
+```
+
+- [ ] **Step 4: Commit**
+
+```bash
+git add docs/gtm/taxonomy.md
+git commit -m "docs(gtm): document blog:* events in taxonomy"
+```
+
+---
+
+## Task 7: `AuthorByline` component
+
+**Files:**
+
+- Create: `apps/website/src/components/blog/AuthorByline.tsx`
+
+- [ ] **Step 1: Create the component**
+
+```tsx
+import type { Author } from '../../lib/blog-authors';
+
+export function AuthorByline({ author }: { author: Author }) {
+  return (
+    <div
+      style={{
+        display: 'flex',
+        alignItems: 'center',
+        gap: 12,
+        fontSize: 14,
+        opacity: 0.8,
+      }}
+    >
+      {author.avatar ? (
+        // eslint-disable-next-line @next/next/no-img-element
+        <img
+          src={author.avatar}
+          alt={`${author.name} avatar`}
+          width={32}
+          height={32}
+          style={{ borderRadius: '50%' }}
+        />
+      ) : null}
+      <div>
+        <span style={{ fontWeight: 600 }}>{author.name}</span>
+        {author.role ? (
+          <span style={{ opacity: 0.7 }}> · {author.role}</span>
+        ) : null}
+      </div>
+    </div>
+  );
+}
+```
+
+- [ ] **Step 2: Commit**
+
+```bash
+git add apps/website/src/components/blog/AuthorByline.tsx
+git commit -m "feat(website): add AuthorByline component"
+```
+
+---
+
+## Task 8: `PostCard` component (TDD)
+
+**Files:**
+
+- Create: `apps/website/src/components/blog/PostCard.tsx`
+- Create: `apps/website/src/components/blog/PostCard.spec.tsx`
+
+- [ ] **Step 1: Write failing test**
+
+```tsx
+import { describe, expect, it } from 'vitest';
+import { render, screen } from '@testing-library/react';
+import { PostCard } from './PostCard';
+import type { Post } from '../../lib/blog';
+
+const post: Post = {
+  slug: 'streaming-chat',
+  date: '2026-05-17',
+  filename: '2026-05-17-streaming-chat.mdx',
+  content: '',
+  frontmatter: {
+    title: 'Build a streaming chat UI',
+    description: 'A tutorial.',
+    date: '2026-05-17',
+    author: 'brian',
+    tags: ['tutorial', 'streaming'],
+  },
+};
+
+describe('PostCard', () => {
+  it('renders title, date, and tag chips', () => {
+    render(<PostCard post={post} />);
+    expect(screen.getByText('Build a streaming chat UI')).toBeTruthy();
+    expect(screen.getByText('2026-05-17')).toBeTruthy();
+    expect(screen.getByText('tutorial')).toBeTruthy();
+    expect(screen.getByText('streaming')).toBeTruthy();
+  });
+
+  it('links to /blog/[slug]', () => {
+    const { container } = render(<PostCard post={post} />);
+    const link = container.querySelector('a[href="/blog/streaming-chat"]');
+    expect(link).toBeTruthy();
+  });
+});
+```
+
+- [ ] **Step 2: Check `@testing-library/react` availability**
+
+Run: `node -e "require.resolve('@testing-library/react')"` from project root.
+If it errors: install with `npm install @testing-library/react@^16 --save-dev --package-lock-only && npm install --no-audit --no-fund`. Otherwise skip.
+
+- [ ] **Step 3: Run tests to verify they fail**
+
+Run: `cd apps/website && npx vitest run src/components/blog/PostCard.spec.tsx`
+Expected: FAIL — module not found.
+
+- [ ] **Step 4: Implement `PostCard.tsx`**
+
+```tsx
+import Link from 'next/link';
+import { tokens } from '@ngaf/design-tokens';
+import type { Post } from '../../lib/blog';
+
+export function PostCard({ post }: { post: Post }) {
+  const { slug, frontmatter } = post;
+  return (
+    <Link
+      href={`/blog/${slug}`}
+      style={{
+        display: 'flex',
+        flexDirection: 'column',
+        gap: 8,
+        padding: 20,
+        borderRadius: 12,
+        background: tokens.colors.surfaceMuted,
+        border: `1px solid ${tokens.colors.border}`,
+        color: tokens.colors.textPrimary,
+        textDecoration: 'none',
+      }}
+    >
+      <time
+        dateTime={frontmatter.date}
+        style={{ fontSize: 13, color: tokens.colors.textMuted }}
+      >
+        {frontmatter.date}
+      </time>
+      <h3 style={{ fontSize: 20, fontWeight: 600, margin: 0 }}>
+        {frontmatter.title}
+      </h3>
+      <p style={{ fontSize: 14, color: tokens.colors.textSecondary, margin: 0 }}>
+        {frontmatter.description}
+      </p>
+      {frontmatter.tags && frontmatter.tags.length > 0 ? (
+        <div style={{ display: 'flex', gap: 6, flexWrap: 'wrap', marginTop: 8 }}>
+          {frontmatter.tags.map((tag) => (
+            <span
+              key={tag}
+              style={{
+                fontSize: 12,
+                padding: '2px 8px',
+                borderRadius: 999,
+                background: tokens.colors.accentSurface,
+                color: tokens.colors.accent,
+              }}
+            >
+              {tag}
+            </span>
+          ))}
+        </div>
+      ) : null}
+    </Link>
+  );
+}
+```
+
+- [ ] **Step 5: Run tests to verify they pass**
+
+Run: `cd apps/website && npx vitest run src/components/blog/PostCard.spec.tsx`
+Expected: PASS, 2 tests.
+
+- [ ] **Step 6: Commit**
+
+```bash
+git add apps/website/src/components/blog/PostCard.tsx apps/website/src/components/blog/PostCard.spec.tsx
+git commit -m "feat(website): add PostCard component with tests"
+```
+
+---
+
+## Task 9: `FeaturedPostCard` + `TagChips` components
+
+**Files:**
+
+- Create: `apps/website/src/components/blog/FeaturedPostCard.tsx`
+- Create: `apps/website/src/components/blog/TagChips.tsx`
+
+- [ ] **Step 1: Create FeaturedPostCard**
+
+```tsx
+import Link from 'next/link';
+import { tokens } from '@ngaf/design-tokens';
+import type { Post } from '../../lib/blog';
+import { getAuthor } from '../../lib/blog-authors';
+import { AuthorByline } from './AuthorByline';
+
+export function FeaturedPostCard({ post }: { post: Post }) {
+  const { slug, frontmatter } = post;
+  const author = getAuthor(frontmatter.author);
+  return (
+    <Link
+      href={`/blog/${slug}`}
+      style={{
+        display: 'flex',
+        flexDirection: 'column',
+        gap: 12,
+        padding: 32,
+        borderRadius: 16,
+        background: tokens.colors.surface,
+        border: `1px solid ${tokens.colors.accent}`,
+        color: tokens.colors.textPrimary,
+        textDecoration: 'none',
+        marginBottom: 32,
+      }}
+    >
+      <span
+        style={{
+          fontSize: 12,
+          textTransform: 'uppercase',
+          letterSpacing: '0.08em',
+          color: tokens.colors.accent,
+        }}
+      >
+        Featured
+      </span>
+      <h2 style={{ fontSize: 32, fontWeight: 600, margin: 0, lineHeight: 1.2 }}>
+        {frontmatter.title}
+      </h2>
+      <p style={{ fontSize: 16, color: tokens.colors.textSecondary, margin: 0 }}>
+        {frontmatter.description}
+      </p>
+      <div
+        style={{
+          display: 'flex',
+          alignItems: 'center',
+          justifyContent: 'space-between',
+          marginTop: 12,
+        }}
+      >
+        <AuthorByline author={author} />
+        <time
+          dateTime={frontmatter.date}
+          style={{ fontSize: 13, color: tokens.colors.textMuted }}
+        >
+          {frontmatter.date}
+        </time>
+      </div>
+    </Link>
+  );
+}
+```
+
+- [ ] **Step 2: Create TagChips**
+
+```tsx
+import { tokens } from '@ngaf/design-tokens';
+
+export function TagChips({ tags }: { tags: string[] }) {
+  if (tags.length === 0) return null;
+  return (
+    <div
+      style={{
+        display: 'flex',
+        gap: 8,
+        flexWrap: 'wrap',
+        marginBottom: 24,
+      }}
+    >
+      {tags.map((tag) => (
+        <span
+          key={tag}
+          style={{
+            fontSize: 13,
+            padding: '4px 10px',
+            borderRadius: 999,
+            background: tokens.colors.accentSurface,
+            color: tokens.colors.accent,
+          }}
+        >
+          {tag}
+        </span>
+      ))}
+    </div>
+  );
+}
+```
+
+- [ ] **Step 3: Commit**
+
+```bash
+git add apps/website/src/components/blog/FeaturedPostCard.tsx apps/website/src/components/blog/TagChips.tsx
+git commit -m "feat(website): add FeaturedPostCard + TagChips components"
+```
+
+---
+
+## Task 10: Add `Blog` to Nav
+
+**Files:**
+
+- Modify: `apps/website/src/components/shared/Nav.tsx`
+
+- [ ] **Step 1: Add Blog link to the `links` array**
+
+Edit the `links` array near the top of `Nav.tsx`. Insert `{ label: 'Blog', href: '/blog', external: false },` between the `Pricing` entry and the closing `];`. Final array:
+
+```typescript
+const links = [
+  { label: 'Pilot to Prod', href: '/pilot-to-prod', external: false },
+  { label: 'Docs', href: '/docs', external: false },
+  { label: 'Solutions', href: '/solutions', external: false },
+  { label: 'API', href: '/docs/agent/api/agent', external: false },
+  { label: 'Demo', href: 'https://demo.cacheplane.ai', external: true },
+  { label: 'Examples', href: 'https://cockpit.cacheplane.ai', external: true },
+  { label: 'Pricing', href: '/pricing', external: false },
+  { label: 'Blog', href: '/blog', external: false },
+];
+```
+
+- [ ] **Step 2: Commit**
+
+```bash
+git add apps/website/src/components/shared/Nav.tsx
+git commit -m "feat(website): add Blog link to nav"
+```
+
+---
+
+## Task 11: `/blog` index route
+
+**Files:**
+
+- Create: `apps/website/src/app/blog/page.tsx`
+
+- [ ] **Step 1: Create the index page**
+
+```tsx
+import { createPageMetadata } from '../../lib/site-metadata';
+import { getAllPosts, getFeaturedPost, getAllTags } from '../../lib/blog';
+import { FeaturedPostCard } from '../../components/blog/FeaturedPostCard';
+import { PostCard } from '../../components/blog/PostCard';
+import { TagChips } from '../../components/blog/TagChips';
+
+export const metadata = createPageMetadata({
+  title: 'Blog — Cacheplane',
+  description:
+    'Long-form writing on agent UI for Angular: streaming, generative UI, threads, interrupts, production patterns.',
+  pathname: '/blog',
+  type: 'website',
+});
+
+export default function BlogIndexPage() {
+  const all = getAllPosts();
+  const featured = getFeaturedPost();
+  const rest = featured ? all.filter((p) => p.slug !== featured.slug) : all;
+  const tags = getAllTags().map((t) => t.tag);
+
+  return (
+    <div style={{ maxWidth: 960, margin: '0 auto', padding: '64px 24px' }}>
+      <p
+        style={{
+          fontSize: 13,
+          textTransform: 'uppercase',
+          letterSpacing: '0.08em',
+          marginBottom: 8,
+          opacity: 0.7,
+        }}
+      >
+        Blog
+      </p>
+      <h1
+        style={{
+          fontSize: 48,
+          fontWeight: 600,
+          letterSpacing: '-0.02em',
+          marginBottom: 12,
+        }}
+      >
+        Notes from Cacheplane
+      </h1>
+      <p style={{ fontSize: 18, opacity: 0.8, marginBottom: 32, maxWidth: '60ch' }}>
+        Writing on agent UI for Angular — production patterns, design choices,
+        and what we&apos;re shipping.
+      </p>
+      <TagChips tags={tags} />
+      {featured ? <FeaturedPostCard post={featured} /> : null}
+      <div
+        style={{
+          display: 'grid',
+          gridTemplateColumns: 'repeat(auto-fill, minmax(300px, 1fr))',
+          gap: 16,
+        }}
+      >
+        {rest.map((p) => (
+          <PostCard key={p.slug} post={p} />
+        ))}
+      </div>
+    </div>
+  );
+}
+```
+
+- [ ] **Step 2: Verify the route builds**
+
+Run: `cd apps/website && npx next build` (will run after Task 14 and 15 also exist; if this step is run in isolation and the route compiles, ✅).
+Or run a faster typecheck: `cd apps/website && npx tsc --noEmit -p tsconfig.json`
+Expected: no errors related to `app/blog/page.tsx`.
+
+- [ ] **Step 3: Commit**
+
+```bash
+git add apps/website/src/app/blog/page.tsx
+git commit -m "feat(website): add /blog index page"
+```
+
+---
+
+## Task 12: `/blog/[slug]` route
+
+**Files:**
+
+- Create: `apps/website/src/app/blog/[slug]/page.tsx`
+
+- [ ] **Step 1: Create the dynamic post page**
+
+`<MdxRenderer>` from `apps/website/src/components/docs/MdxRenderer.tsx` requires props `{ source, library, section, slug, title }`. We pass nominal values for `library` and `section` and the post's own `slug`/`title`.
+
+```tsx
+import type { Metadata } from 'next';
+import { notFound } from 'next/navigation';
+import { MdxRenderer } from '../../../components/docs/MdxRenderer';
+import { AuthorByline } from '../../../components/blog/AuthorByline';
+import { getAllPosts, getPostBySlug } from '../../../lib/blog';
+import { getAuthor } from '../../../lib/blog-authors';
+import { createPageMetadata } from '../../../lib/site-metadata';
+
+interface Params {
+  params: Promise<{ slug: string }>;
+}
+
+export function generateStaticParams() {
+  return getAllPosts().map((p) => ({ slug: p.slug }));
+}
+
+export async function generateMetadata({ params }: Params): Promise<Metadata> {
+  const { slug } = await params;
+  const post = getPostBySlug(slug);
+  if (!post || post.frontmatter.draft) {
+    return { title: 'Post not found — Cacheplane' };
+  }
+  return createPageMetadata({
+    title: `${post.frontmatter.title} — Cacheplane`,
+    description: post.frontmatter.description,
+    pathname: `/blog/${post.slug}`,
+    type: 'article',
+  });
+}
+
+export default async function BlogPostPage({ params }: Params) {
+  const { slug } = await params;
+  const post = getPostBySlug(slug);
+  if (!post || post.frontmatter.draft) notFound();
+  const author = getAuthor(post.frontmatter.author);
+  return (
+    <article style={{ maxWidth: 768, margin: '0 auto', padding: '64px 24px' }}>
+      <header style={{ marginBottom: 32 }}>
+        <time
+          dateTime={post.frontmatter.date}
+          style={{ fontSize: 14, opacity: 0.7 }}
+        >
+          {post.frontmatter.date}
+        </time>
+        <h1
+          style={{
+            fontSize: 44,
+            fontWeight: 600,
+            letterSpacing: '-0.02em',
+            margin: '12px 0 16px',
+            lineHeight: 1.15,
+          }}
+        >
+          {post.frontmatter.title}
+        </h1>
+        <AuthorByline author={author} />
+      </header>
+      <MdxRenderer
+        source={post.content}
+        library="agent"
+        section="blog"
+        slug={post.slug}
+        title={post.frontmatter.title}
+      />
+    </article>
+  );
+}
+```
+
+- [ ] **Step 2: Verify typecheck**
+
+Run: `cd apps/website && npx tsc --noEmit -p tsconfig.json`
+Expected: no new errors.
+
+- [ ] **Step 3: Commit**
+
+```bash
+git add apps/website/src/app/blog/[slug]/page.tsx
+git commit -m "feat(website): add /blog/[slug] dynamic post route"
+```
+
+---
+
+## Task 13: Per-post OG image route
+
+**Files:**
+
+- Create: `apps/website/src/app/blog/[slug]/opengraph-image.tsx`
+
+- [ ] **Step 1: Inspect the existing default OG route for the font-loading pattern**
+
+Run: `cat apps/website/src/app/opengraph-image.tsx | head -80`
+The blog OG route reuses the same font (EBGaramond) loading pattern. If the existing route imports the font from `apps/website/src/app/EBGaramond-Bold.ttf` (verified to exist), mirror that import.
+
+- [ ] **Step 2: Create the per-post OG route**
+
+```tsx
+import { ImageResponse } from 'next/og';
+import { getPostBySlug } from '../../../lib/blog';
+import { getAuthor } from '../../../lib/blog-authors';
+
+export const runtime = 'nodejs';
+export const alt = 'Cacheplane blog post';
+export const size = { width: 1200, height: 630 };
+export const contentType = 'image/png';
+
+interface Params {
+  params: Promise<{ slug: string }>;
+}
+
+export default async function og({ params }: Params) {
+  const { slug } = await params;
+  const post = getPostBySlug(slug);
+
+  if (!post || post.frontmatter.draft) {
+    return new ImageResponse(
+      (
+        <div
+          style={{
+            width: '100%',
+            height: '100%',
+            display: 'flex',
+            alignItems: 'center',
+            justifyContent: 'center',
+            background: '#0b0d12',
+            color: '#ffffff',
+            fontSize: 64,
+          }}
+        >
+          Cacheplane
+        </div>
+      ),
+      size,
+    );
+  }
+
+  const author = getAuthor(post.frontmatter.author);
+  return new ImageResponse(
+    (
+      <div
+        style={{
+          width: '100%',
+          height: '100%',
+          display: 'flex',
+          flexDirection: 'column',
+          justifyContent: 'space-between',
+          padding: 64,
+          background: '#0b0d12',
+          color: '#ffffff',
+        }}
+      >
+        <div
+          style={{
+            fontSize: 24,
+            textTransform: 'uppercase',
+            letterSpacing: '0.12em',
+            opacity: 0.6,
+          }}
+        >
+          Cacheplane Blog
+        </div>
+        <div
+          style={{
+            fontSize: 64,
+            fontWeight: 600,
+            lineHeight: 1.1,
+            letterSpacing: '-0.02em',
+            maxWidth: '90%',
+          }}
+        >
+          {post.frontmatter.title}
+        </div>
+        <div style={{ fontSize: 24, opacity: 0.7 }}>
+          {author.name} · {post.frontmatter.date}
+        </div>
+      </div>
+    ),
+    size,
+  );
+}
+```
+
+(If the per-route `params` API turns out unsupported in the project's Next 16 version — fallback per spec §10: convert to a dynamic route under `apps/website/src/app/blog/og/[slug]/route.tsx` returning `new ImageResponse(...)`, and update `generateMetadata` in Task 12 to set `openGraph.images: [\`/blog/og/${slug}\`]`. Implementer chooses the working path during local verification.)
+
+- [ ] **Step 3: Verify build**
+
+Run: `cd apps/website && npx tsc --noEmit -p tsconfig.json`
+Expected: no errors.
+
+- [ ] **Step 4: Commit**
+
+```bash
+git add apps/website/src/app/blog/[slug]/opengraph-image.tsx
+git commit -m "feat(website): add per-post OG image route"
+```
+
+---
+
+## Task 14: RSS feed
+
+**Files:**
+
+- Create: `apps/website/src/app/blog/rss.xml/route.ts`
+
+- [ ] **Step 1: Create the RSS route**
+
+```typescript
+import { NextResponse } from 'next/server';
+import { getAllPosts } from '../../../lib/blog';
+import { SITE_ORIGIN } from '../../../lib/site-metadata';
+
+function escapeXml(s: string): string {
+  return s
+    .replace(/&/g, '&amp;')
+    .replace(/</g, '&lt;')
+    .replace(/>/g, '&gt;');
+}
+
+export async function GET() {
+  const posts = getAllPosts();
+  const items = posts
+    .map((p) => {
+      const url = `${SITE_ORIGIN}/blog/${p.slug}`;
+      const pubDate = (() => {
+        const d = new Date(p.frontmatter.date);
+        return Number.isNaN(d.getTime()) ? '' : d.toUTCString();
+      })();
+      return `    <item>
+      <title><![CDATA[${p.frontmatter.title}]]></title>
+      <link>${url}</link>
+      <guid isPermaLink="true">${url}</guid>
+      <pubDate>${pubDate}</pubDate>
+      <description><![CDATA[${p.frontmatter.description}]]></description>
+    </item>`;
+    })
+    .join('\n');
+
+  const xml = `<?xml version="1.0" encoding="UTF-8" ?>
+<rss version="2.0" xmlns:atom="http://www.w3.org/2005/Atom">
+  <channel>
+    <title>${escapeXml('Cacheplane Blog')}</title>
+    <link>${SITE_ORIGIN}/blog</link>
+    <atom:link href="${SITE_ORIGIN}/blog/rss.xml" rel="self" type="application/rss+xml" />
+    <description>${escapeXml('Writing on agent UI for Angular.')}</description>
+    <language>en</language>
+${items}
+  </channel>
+</rss>
+`;
+
+  return new NextResponse(xml, {
+    headers: {
+      'Content-Type': 'application/rss+xml; charset=utf-8',
+      'Cache-Control': 'public, max-age=300, s-maxage=300',
+    },
+  });
+}
+```
+
+- [ ] **Step 2: Verify typecheck**
+
+Run: `cd apps/website && npx tsc --noEmit -p tsconfig.json`
+Expected: no errors.
+
+- [ ] **Step 3: Commit**
+
+```bash
+git add apps/website/src/app/blog/rss.xml/route.ts
+git commit -m "feat(website): add /blog/rss.xml RSS 2.0 feed"
+```
+
+---
+
+## Task 15: Sitemap integration
+
+**Files:**
+
+- Modify: `apps/website/src/lib/site-metadata.ts`
+
+- [ ] **Step 1: Extend `getSitemapRoutes()` to include blog routes**
+
+Edit `getSitemapRoutes()`. Replace the existing function body so it imports + appends blog routes:
+
+```typescript
+import { getAllPosts } from './blog';
+
+export function getSitemapRoutes(): string[] {
+  const staticRoutes = ['/', '/angular', '/render', '/chat', '/pricing', '/solutions', '/pilot-to-prod', '/docs', '/blog'];
+  const solutionRoutes = getAllSolutionSlugs().map((slug) => `/solutions/${slug}`);
+  const docsRoutes = docsConfig.flatMap((library) =>
+    library.sections.flatMap((section) =>
+      section.pages.map((page) => `/docs/${library.id}/${page.section}/${page.slug}`),
+    ),
+  );
+  const blogRoutes = getAllPosts().map((p) => `/blog/${p.slug}`);
+
+  return [...staticRoutes, ...solutionRoutes, ...docsRoutes, ...blogRoutes];
+}
+```
+
+(Place the `import { getAllPosts } from './blog';` at the top of the file with other imports.)
+
+- [ ] **Step 2: Verify typecheck + existing tests still pass**
+
+Run: `cd apps/website && npx tsc --noEmit -p tsconfig.json && npx vitest run src/lib`
+Expected: no type errors; existing `docs.spec.ts` continues to pass.
+
+- [ ] **Step 3: Commit**
+
+```bash
+git add apps/website/src/lib/site-metadata.ts
+git commit -m "feat(website): include /blog routes in sitemap"
+```
+
+---
+
+## Task 16: Seed pillar post MDX (Brian's voice)
+
+**Files:**
+
+- Create: `apps/website/content/blog/2026-05-17-build-a-streaming-chat-ui-in-angular-with-langgraph.mdx`
+
+- [ ] **Step 1: Study Brian's voice (REQUIRED before drafting)**
+
+Read in full:
+
+- `~/repos/brianflove/src/content/posts/2026-02-21-the-frontend-reward-loop-for-agentic-software.md`
+- `~/repos/brianflove/src/content/posts/2026-03-18-agentic-memory-and-what-it-means-for-web-apps.md`
+- `~/repos/brianflove/src/content/posts/2026-02-20-the-landscape-of-generative-ui-in-2026.md`
+
+Voice rules to replicate:
+
+1. Open with a blunt thesis. No "Introduction" header.
+2. One thought per line. 1-3 sentences per paragraph.
+3. `## tl;dr` early, bullet list of 4-6 lines.
+4. Numbered frameworks with short subheads.
+5. Contrast moves: "Not because X. And not because Y. It matters because Z."
+6. Pragmatic second person: "If you are building...", "Most teams...".
+7. Em-dashes (`—`) heavy. No emoji. No superlatives.
+
+- [ ] **Step 2: Draft the post**
+
+Create the file with this exact frontmatter (then add ~2,500-word body matching the structure in Section 6 of the spec):
+
+```mdx
+---
+title: "Build a Streaming Chat UI in Angular with LangGraph"
+description: "Step-by-step tutorial for shipping a production streaming chat in Angular — signal-native, design-system-friendly, and wired to a LangGraph backend."
+date: 2026-05-17
+tags: [tutorial, streaming, langgraph, angular]
+author: brian
+featured: true
+---
+
+Streaming is the line between a chat demo and a chat product.
+
+A chat that returns a full reply after three seconds feels broken.
+A chat that streams the first token in 200ms feels alive.
+
+That single change in latency perception is the difference between a UI users tolerate and a UI they trust.
+
+In Angular, streaming chat used to mean wiring `RxJS` to fetch, parsing SSE by hand, and hoping zone.js cooperated.
+
+That is no longer the shape of the problem.
+
+With Signals and a properly designed agent contract, streaming chat is a small composition exercise. The hard part stopped being the wire. The hard part is the product around it — error recovery, threads, interrupts, generative UI.
+
+This post walks through shipping a streaming chat UI in Angular against a LangGraph backend, end to end, with `@ngaf/chat` and `@ngaf/langgraph`.
+
+## tl;dr
+
+- Streaming chat is a signal problem, not a streaming problem.
+- `@ngaf/chat` gives you the composition. `@ngaf/langgraph` gives you the wire.
+- The agent contract is a small, signal-shaped interface.
+- Production patterns matter more than the streaming itself: errors, retries, threads, interrupts, fallbacks.
+- One install. Standalone components. No React rewrite.
+
+## Why streaming is the production-vs-demo line
+
+Most chat demos work fine when you measure them by output quality.
+
+They fail when you measure them by feel.
+
+A non-streaming chat hides three things from the user:
+
+1. Whether the system is alive.
+2. Whether the model is on the right track.
+3. Whether the user should wait or cancel.
+
+Streaming exposes all three.
+
+That is why every production chat in 2026 streams. Not because the tokens arrive faster — they do not — but because the user gets to make a decision earlier.
+
+## Architecture in three boxes
+
+You only need to keep three boxes in your head.
+
+<ArchFlowDiagram
+  nodes={[
+    { id: 'lg', label: 'LangGraph backend' },
+    { id: 'adapter', label: '@ngaf/langgraph adapter' },
+    { id: 'ui', label: '@ngaf/chat UI' },
+  ]}
+  edges={[
+    { from: 'lg', to: 'adapter', label: 'AG-UI events' },
+    { from: 'adapter', to: 'ui', label: 'signals' },
+  ]}
+/>
+
+Each box has one job.
+
+1. **LangGraph backend.** Runs the graph. Emits AG-UI events.
+2. **`@ngaf/langgraph` adapter.** Translates events into signals.
+3. **`@ngaf/chat` UI.** Renders the conversation.
+
+You replace any of the three without touching the others.
+
+## Scaffold
+
+If you have an existing Angular 18+ app, the install is one command.
+
+<Steps>
+<Step title="Install the packages">
+
+```bash
+npm install @ngaf/chat @ngaf/langgraph
+```
+
+</Step>
+<Step title="Provide the agent at app config">
+
+```typescript
+import { ApplicationConfig } from '@angular/core';
+import { provideAgent } from '@ngaf/langgraph';
+
+export const appConfig: ApplicationConfig = {
+  providers: [
+    provideAgent({ apiUrl: 'https://your-backend.example.com' }),
+  ],
+};
+```
+
+</Step>
+<Step title="Create the agent factory in a component">
+
+```typescript
+import { Component, inject } from '@angular/core';
+import { agent } from '@ngaf/langgraph';
+import { ChatComponent } from '@ngaf/chat';
+
+@Component({
+  selector: 'app-chat',
+  standalone: true,
+  imports: [ChatComponent],
+  template: `<chat [agent]="agent" />`,
+})
+export class AppChatComponent {
+  agent = agent({ assistantId: 'streaming-assistant' });
+}
+```
+
+</Step>
+</Steps>
+
+That is the whole scaffold.
+
+## Render the chat
+
+The `<chat>` component handles three states out of the box.
+
+1. **Welcome state.** No messages yet. Optional suggestion chips.
+2. **Streaming state.** Tokens arrive, animate, and append to the latest message.
+3. **Idle state.** Final reply is in. Input is enabled.
+
+You do not have to think about any of that. You just hand `<chat>` the agent.
+
+If you want suggestions:
+
+```html
+<chat
+  [agent]="agent"
+  [suggestions]="['Show me the architecture', 'How do interrupts work?']"
+/>
+```
+
+If you want to customize the welcome panel, slot it:
+
+```html
+<chat [agent]="agent">
+  <welcome>
+    <h2>Ask me anything about your codebase.</h2>
+  </welcome>
+</chat>
+```
+
+## What is happening under the hood
+
+The agent contract is small.
+
+```typescript
+interface Agent {
+  messages: Signal<Message[]>;
+  status: Signal<'idle' | 'streaming' | 'error'>;
+  send(input: string): void;
+  stop(): void;
+}
+```
+
+`@ngaf/langgraph` produces an `Agent` whose `messages` signal updates with every streamed chunk. Angular's change detection reads the signal, re-renders the message bubble, and you get streaming for free.
+
+There is no `RxJS` to debug.
+There is no SSE parser to maintain.
+There is no zone.js dance.
+
+It is a signal you read in a template.
+
+## Production patterns
+
+Streaming is the easy part. The hard parts are the ones a tutorial usually skips. Here are the three that matter for production.
+
+### 1. Errors and retries
+
+If the connection drops mid-stream, the user should know — and have a one-click retry.
+
+`<chat>` exposes an `(error)` output and the agent has a `retry()` method.
+
+```html
+<chat
+  [agent]="agent"
+  (error)="onError($event)"
+/>
+```
+
+```typescript
+onError(error: AgentError) {
+  this.toast.show({
+    message: 'Connection lost. Retry?',
+    action: () => this.agent.retry(),
+  });
+}
+```
+
+### 2. Threads and persistence
+
+A streaming chat without persistent threads is a toy.
+
+`@ngaf/langgraph` integrates with LangGraph's thread API. You pass a `threadId` to the agent factory, and the conversation history loads on mount.
+
+```typescript
+agent = agent({ assistantId: 'streaming-assistant', threadId: 'thread-123' });
+```
+
+When the user starts a new conversation, you call `agent.newThread()` and the backend mints a fresh thread id.
+
+### 3. Generative UI fallbacks
+
+Not every reply is a string.
+
+Some replies are forms, lists, structured outputs.
+
+The chat composition handles structured outputs through `@ngaf/render` — give it a JSON schema and a payload, and it renders an Angular component. No iframes. No HTML strings. No XSS surface.
+
+This is out of scope for this post. The next pillar will cover generative UI in depth.
+
+## Where to go from here
+
+The fastest way to feel the streaming pattern is the cockpit reference app.
+
+- [Streaming recipe in the cockpit](https://cockpit.cacheplane.ai/recipes/streaming) — runnable example with the exact wiring above.
+- [Persistence + threads](/docs/chat/recipes/persistence) — when you outgrow a single conversation.
+- [Interrupts and human-in-the-loop](/docs/chat/recipes/interrupts) — when the agent needs approval mid-step.
+
+<Callout type="info">
+  Need engineering support for a production deployment? [Talk to engineers](/contact?source=blog_streaming_pillar&track=enterprise) — we work directly with teams shipping Angular agent UIs.
+</Callout>
+
+Streaming is the entry. The product is what you build around it.
+```
+
+(The exact prose above is the seed draft. The implementer reviews against Brian's voice samples and tightens sentences that drift toward marketing tone. Word count target ~2,500 — if shorter is tighter, that is acceptable.)
+
+- [ ] **Step 3: Verify the post is picked up by the parser**
+
+Run: `cd apps/website && npx vitest run src/lib/blog.spec.ts`
+(Existing tests should pass; this post is not asserted against.)
+
+Then verify in dev:
+
+```bash
+cd /Users/blove/repos/angular-agent-framework/.claude/worktrees/gtm+cockpit-instrumentation
+npx nx serve website &
+sleep 8
+curl -s http://localhost:3000/blog | grep -q "Build a Streaming Chat UI" && echo "✓ seed post on index"
+curl -s http://localhost:3000/blog/build-a-streaming-chat-ui-in-angular-with-langgraph | grep -q "streaming chat UI" && echo "✓ seed post page renders"
+```
+
+- [ ] **Step 4: Commit**
+
+```bash
+git add apps/website/content/blog/2026-05-17-build-a-streaming-chat-ui-in-angular-with-langgraph.mdx
+git commit -m "feat(website): seed pillar post on streaming chat in Angular"
+```
+
+---
+
+## Task 17: Build + RSS verification
+
+**Files:** none (verification only)
+
+- [ ] **Step 1: Full website build**
+
+Run: `cd /Users/blove/repos/angular-agent-framework/.claude/worktrees/gtm+cockpit-instrumentation && npx nx run website:build`
+Expected: build succeeds, `/blog`, `/blog/[slug]`, `/blog/rss.xml` all listed in the route summary.
+
+- [ ] **Step 2: Run all website unit tests**
+
+Run: `cd apps/website && npx vitest run`
+Expected: all green, including the new `blog.spec.ts` and `PostCard.spec.tsx`.
+
+- [ ] **Step 3: Smoke check RSS in dev**
+
+```bash
+cd /Users/blove/repos/angular-agent-framework/.claude/worktrees/gtm+cockpit-instrumentation
+npx nx serve website &
+SERVE_PID=$!
+sleep 10
+curl -s -i http://localhost:3000/blog/rss.xml | head -5
+curl -s http://localhost:3000/blog/rss.xml | xmllint --noout - && echo "✓ RSS is valid XML"
+curl -s http://localhost:3000/sitemap.xml | grep -q "/blog/build-a-streaming-chat-ui-in-angular-with-langgraph" && echo "✓ sitemap includes seed post"
+kill $SERVE_PID
+```
+
+Expected: `Content-Type: application/rss+xml`, XML validates, sitemap includes seed.
+
+- [ ] **Step 4: Chrome MCP smoke (manual)**
+
+Use the Chrome MCP to visit (in order):
+
+1. `http://localhost:3000/blog` — featured card + index visible.
+2. `http://localhost:3000/blog/build-a-streaming-chat-ui-in-angular-with-langgraph` — full post renders with syntax highlighting.
+3. `view-source:http://localhost:3000/blog/build-a-streaming-chat-ui-in-angular-with-langgraph` — `<meta property="og:image">` references `/opengraph-image` for the post.
+
+- [ ] **Step 5: No commit** — verification only.
+
+---
+
+## Task 18: Open PR
+
+**Files:** none (PR creation)
+
+- [ ] **Step 1: Push the branch**
+
+```bash
+cd /Users/blove/repos/angular-agent-framework/.claude/worktrees/gtm+cockpit-instrumentation
+git push -u origin gtm-spec-5-content-pillar-blog
+```
+
+- [ ] **Step 2: Create the PR**
+
+```bash
+gh pr create --title "feat(website): /blog infrastructure + streaming-chat pillar post (Spec 5)" --body "$(cat <<'EOF'
+## Summary
+- Adds `/blog` index, `/blog/[slug]`, per-post OG, `/blog/rss.xml`, sitemap inclusion
+- Seed pillar post: "Build a Streaming Chat UI in Angular with LangGraph" written in Brian's voice
+- New `blog:*` analytics namespace (`blog:cta_click`, `blog:copy_code_click`) + `'blog'` `AnalyticsSurface`
+
+Spec: `docs/superpowers/specs/gtm/2026-05-17-content-pillar-pages-design.md`
+Plan: `docs/superpowers/plans/gtm/2026-05-17-content-pillar-pages.md`
+
+## Test plan
+- [ ] `nx run website:build` green
+- [ ] `cd apps/website && npx vitest run` green
+- [ ] `/blog` renders with seed post visible
+- [ ] `/blog/build-a-streaming-chat-ui-in-angular-with-langgraph` renders with highlighted code
+- [ ] `/blog/rss.xml` returns valid RSS 2.0
+- [ ] sitemap includes new blog routes
+- [ ] per-post OG card renders
+
+🤖 Generated with [Claude Code](https://claude.com/claude-code)
+EOF
+)"
+```
+
+- [ ] **Step 3: Enable auto-merge on green**
+
+```bash
+gh pr merge --auto --squash
+```
+
+Expected: PR opens, CI runs, auto-merges on green.
+
+---
+
+## Self-review
+
+Spec coverage check (against §3 of the spec):
+
+- ✅ `/blog` route — Task 11
+- ✅ `/blog/[slug]` — Task 12
+- ✅ `/blog/[slug]/opengraph-image.tsx` — Task 13
+- ✅ `/blog/rss.xml` — Task 14
+- ✅ Date-prefixed MDX filenames + frontmatter parser — Tasks 2, 3
+- ✅ Author registry — Task 4
+- ✅ `blog:*` analytics events + `'blog'` surface — Task 5
+- ✅ `taxonomy.md` update — Task 6
+- ✅ Nav `Blog` link — Task 10
+- ✅ Sitemap inclusion — Task 15
+- ✅ Seed pillar post — Task 16
+- ✅ Unit tests for `blog.ts` and `PostCard` — Tasks 3, 8
+- ✅ `nx run website:build` verification — Task 17
+
+Placeholder scan: no "TBD"/"implement later" in steps. Code blocks are concrete. Test code is provided in full. The optional fallback OG path in Task 13 has explicit fallback instructions, not a TBD.
+
+Type consistency: `Post`, `PostFrontmatter`, `Author` are defined once in Tasks 3, 4 and consumed unchanged in Tasks 7, 8, 9, 11, 12, 13, 14. `getAllPosts`/`getPostBySlug`/`getFeaturedPost`/`getAllTags` signatures match between Task 3 (definition) and consumers.
+
+---
+
+## Execution Handoff
+
+Plan complete and saved to `docs/superpowers/plans/gtm/2026-05-17-content-pillar-pages.md`. Two execution options:
+
+**1. Subagent-Driven (recommended)** — I dispatch a fresh subagent per task, review between tasks, fast iteration.
+
+**2. Inline Execution** — Execute tasks in this session using executing-plans, batch execution with checkpoints.
+
+Which approach?

From 3c63638c1eca44a8da9b3e5db3bd76126a171473 Mon Sep 17 00:00:00 2001
From: Brian Love <brian@liveloveapp.com>
Date: Sun, 17 May 2026 07:59:46 -0700
Subject: [PATCH 03/20] chore(website): add gray-matter for blog frontmatter
 parsing

---
 package-lock.json | 64 +++++++++++++++++++++++++++++++++++++++++++----
 package.json      |  1 +
 2 files changed, 60 insertions(+), 5 deletions(-)

diff --git a/package-lock.json b/package-lock.json
index 15f9101db..d995c618b 100644
--- a/package-lock.json
+++ b/package-lock.json
@@ -29,6 +29,7 @@
         "@neondatabase/serverless": "^0.10.0",
         "@noble/ed25519": "^2.3.0",
         "drizzle-orm": "^0.45.2",
+        "gray-matter": "^4.0.3",
         "next": "~16.1.6",
         "next-mdx-remote": "^6.0.0",
         "postgres": "^3.4.9",
@@ -28069,7 +28070,6 @@
       "version": "4.0.1",
       "resolved": "https://registry.npmjs.org/esprima/-/esprima-4.0.1.tgz",
       "integrity": "sha512-eGuFFw7Upda+g4p+QHvnW0RyTX/SVeJBDM/gCtMARO0cLuT2HcEKnTPvhjV6aGeqrCB/sbNop0Kszm0jsaWU4A==",
-      "dev": true,
       "license": "BSD-2-Clause",
       "bin": {
         "esparse": "bin/esparse.js",
@@ -28471,6 +28471,18 @@
       "integrity": "sha512-fjquC59cD7CyW6urNXK0FBufkZcoiGG80wTuPujX590cB5Ttln20E2UB4S/WARVqhXffZl2LNgS+gQdPIIim/g==",
       "license": "MIT"
     },
+    "node_modules/extend-shallow": {
+      "version": "2.0.1",
+      "resolved": "https://registry.npmjs.org/extend-shallow/-/extend-shallow-2.0.1.tgz",
+      "integrity": "sha512-zCnTtlxNoAiDc3gqY2aYAWFx7XWWiasuF2K8Me5WbN8otHKTUKBwjPtNpRs/rbUZm7KxWAaNj7P1a/p52GbVug==",
+      "license": "MIT",
+      "dependencies": {
+        "is-extendable": "^0.1.0"
+      },
+      "engines": {
+        "node": ">=0.10.0"
+      }
+    },
     "node_modules/extract-zip": {
       "version": "2.0.1",
       "resolved": "https://registry.npmjs.org/extract-zip/-/extract-zip-2.0.1.tgz",
@@ -29901,6 +29913,21 @@
       "dev": true,
       "license": "ISC"
     },
+    "node_modules/gray-matter": {
+      "version": "4.0.3",
+      "resolved": "https://registry.npmjs.org/gray-matter/-/gray-matter-4.0.3.tgz",
+      "integrity": "sha512-5v6yZd4JK3eMI3FqqCouswVqwugaA9r4dNZB1wwcmrD02QkV5H0y7XBQW8QwQqEaZY1pM9aqORSORhJRdNK44Q==",
+      "license": "MIT",
+      "dependencies": {
+        "js-yaml": "^3.13.1",
+        "kind-of": "^6.0.2",
+        "section-matter": "^1.0.0",
+        "strip-bom-string": "^1.0.0"
+      },
+      "engines": {
+        "node": ">=6.0"
+      }
+    },
     "node_modules/gunzip-maybe": {
       "version": "1.4.2",
       "resolved": "https://registry.npmjs.org/gunzip-maybe/-/gunzip-maybe-1.4.2.tgz",
@@ -30925,6 +30952,15 @@
         "url": "https://github.com/sponsors/sindresorhus"
       }
     },
+    "node_modules/is-extendable": {
+      "version": "0.1.1",
+      "resolved": "https://registry.npmjs.org/is-extendable/-/is-extendable-0.1.1.tgz",
+      "integrity": "sha512-5BMULNob1vgFX6EjQw5izWDxrecWK9AM72rugNr0TFldMOi0fj6Jk+zeKIt0xGj4cEfQIJth4w3OKWOJ4f+AFw==",
+      "license": "MIT",
+      "engines": {
+        "node": ">=0.10.0"
+      }
+    },
     "node_modules/is-extglob": {
       "version": "2.1.1",
       "resolved": "https://registry.npmjs.org/is-extglob/-/is-extglob-2.1.1.tgz",
@@ -31465,7 +31501,6 @@
       "version": "3.14.2",
       "resolved": "https://registry.npmjs.org/js-yaml/-/js-yaml-3.14.2.tgz",
       "integrity": "sha512-PMSmkqxr106Xa156c2M265Z+FTrPl+oxd/rgOQy2tijQeK5TxQ43psO1ZCwhVOSdnn+RzkzlRz/eY4BgJBYVpg==",
-      "dev": true,
       "license": "MIT",
       "dependencies": {
         "argparse": "^1.0.7",
@@ -31479,7 +31514,6 @@
       "version": "1.0.10",
       "resolved": "https://registry.npmjs.org/argparse/-/argparse-1.0.10.tgz",
       "integrity": "sha512-o5Roy6tNG4SL/FOkCAN6RzjiakZS25RLYFrcMttJqbdd8BWrnA+fGz57iN5Pb06pvBGvl5gQ0B48dJlslXvoTg==",
-      "dev": true,
       "license": "MIT",
       "dependencies": {
         "sprintf-js": "~1.0.2"
@@ -31989,7 +32023,6 @@
       "version": "6.0.3",
       "resolved": "https://registry.npmjs.org/kind-of/-/kind-of-6.0.3.tgz",
       "integrity": "sha512-dcS1ul+9tmeD95T+x28/ehLgd9mENa3LsvDTtzm3vyBEO7RPptvAD+t44WVXaUjTBRcrpFeFlC8WCruUR456hw==",
-      "dev": true,
       "license": "MIT",
       "engines": {
         "node": ">=0.10.0"
@@ -40020,6 +40053,19 @@
         }
       }
     },
+    "node_modules/section-matter": {
+      "version": "1.0.0",
+      "resolved": "https://registry.npmjs.org/section-matter/-/section-matter-1.0.0.tgz",
+      "integrity": "sha512-vfD3pmTzGpufjScBh50YHKzEu2lxBWhVEHsNGoEXmCmn2hKGfeNLYMzCJpe8cD7gqX7TJluOVpBkAequ6dgMmA==",
+      "license": "MIT",
+      "dependencies": {
+        "extend-shallow": "^2.0.1",
+        "kind-of": "^6.0.0"
+      },
+      "engines": {
+        "node": ">=4"
+      }
+    },
     "node_modules/secure-compare": {
       "version": "3.0.1",
       "resolved": "https://registry.npmjs.org/secure-compare/-/secure-compare-3.0.1.tgz",
@@ -40818,7 +40864,6 @@
       "version": "1.0.3",
       "resolved": "https://registry.npmjs.org/sprintf-js/-/sprintf-js-1.0.3.tgz",
       "integrity": "sha512-D9cPgkvLlV3t3IzL0D0YLvGA9Ahk4PcvVwUbN0dSGr1aP0Nrt4AEnTUbuGvquEC0mA64Gqt1fzirlRs5ibXx8g==",
-      "dev": true,
       "license": "BSD-3-Clause"
     },
     "node_modules/ssh-remote-port-forward": {
@@ -41132,6 +41177,15 @@
         "node": ">=4"
       }
     },
+    "node_modules/strip-bom-string": {
+      "version": "1.0.0",
+      "resolved": "https://registry.npmjs.org/strip-bom-string/-/strip-bom-string-1.0.0.tgz",
+      "integrity": "sha512-uCC2VHvQRYu+lMh4My/sFNmF2klFymLX1wHJeXnbEJERpV/ZsVuonzerjfrGpIGF7LBVa1O7i9kjiWvJiFck8g==",
+      "license": "MIT",
+      "engines": {
+        "node": ">=0.10.0"
+      }
+    },
     "node_modules/strip-dirs": {
       "version": "3.0.0",
       "resolved": "https://registry.npmjs.org/strip-dirs/-/strip-dirs-3.0.0.tgz",
diff --git a/package.json b/package.json
index 65e53c295..7afc51d5f 100644
--- a/package.json
+++ b/package.json
@@ -104,6 +104,7 @@
     "@neondatabase/serverless": "^0.10.0",
     "@noble/ed25519": "^2.3.0",
     "drizzle-orm": "^0.45.2",
+    "gray-matter": "^4.0.3",
     "next": "~16.1.6",
     "next-mdx-remote": "^6.0.0",
     "postgres": "^3.4.9",

From f716f4e1a0402d223b65de5490cbb3d38be4e55c Mon Sep 17 00:00:00 2001
From: Brian Love <brian@liveloveapp.com>
Date: Sun, 17 May 2026 08:01:56 -0700
Subject: [PATCH 04/20] feat(website): scaffold blog content directory

---
 apps/website/content/blog/.gitkeep | 0
 1 file changed, 0 insertions(+), 0 deletions(-)
 create mode 100644 apps/website/content/blog/.gitkeep

diff --git a/apps/website/content/blog/.gitkeep b/apps/website/content/blog/.gitkeep
new file mode 100644
index 000000000..e69de29bb

From 5a5d0f3dc39e6654ab8677db5e007ee038a6d7be Mon Sep 17 00:00:00 2001
From: Brian Love <brian@liveloveapp.com>
Date: Sun, 17 May 2026 08:13:04 -0700
Subject: [PATCH 05/20] feat(website): add blog frontmatter parser + listing
 utilities

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
---
 apps/website/src/lib/blog.spec.ts | 147 ++++++++++++++++++++++++++++++
 apps/website/src/lib/blog.ts      |  92 +++++++++++++++++++
 2 files changed, 239 insertions(+)
 create mode 100644 apps/website/src/lib/blog.spec.ts
 create mode 100644 apps/website/src/lib/blog.ts

diff --git a/apps/website/src/lib/blog.spec.ts b/apps/website/src/lib/blog.spec.ts
new file mode 100644
index 000000000..d75aee593
--- /dev/null
+++ b/apps/website/src/lib/blog.spec.ts
@@ -0,0 +1,147 @@
+import { describe, expect, it, vi, beforeEach, afterEach } from 'vitest';
+import * as fs from 'fs';
+
+vi.mock('fs');
+const mockedFs = vi.mocked(fs);
+
+const post1 = `---
+title: "First Post"
+description: "First description"
+date: 2026-05-01
+author: brian
+tags: [tutorial, streaming]
+---
+Body one.`;
+
+const post2 = `---
+title: "Second Post"
+description: "Second description"
+date: 2026-05-10
+author: brian
+featured: true
+---
+Body two.`;
+
+const draft = `---
+title: "Draft Post"
+description: "Draft description"
+date: 2026-05-20
+author: brian
+draft: true
+---
+Body draft.`;
+
+const missingFields = `---
+title: "Missing"
+date: 2026-05-15
+---
+Body missing.`;
+
+function setupFs(files: Record<string, string>) {
+  mockedFs.existsSync.mockImplementation((p) => {
+    const str = String(p);
+    return str.endsWith('/content/blog') || Object.keys(files).some((k) => str.endsWith(k));
+  });
+  mockedFs.readdirSync.mockReturnValue(
+    Object.keys(files).map((k) => k.split('/').pop()!) as never,
+  );
+  mockedFs.readFileSync.mockImplementation((p) => {
+    const name = String(p).split('/').pop()!;
+    const match = Object.entries(files).find(([k]) => k.endsWith(name));
+    if (!match) throw new Error(`no fixture for ${p}`);
+    return match[1];
+  });
+}
+
+beforeEach(() => {
+  vi.resetAllMocks();
+  vi.resetModules();
+});
+
+afterEach(() => {
+  vi.restoreAllMocks();
+});
+
+describe('blog.ts', () => {
+  it('getAllPosts returns posts sorted desc by date', async () => {
+    setupFs({
+      '2026-05-01-first-post.mdx': post1,
+      '2026-05-10-second-post.mdx': post2,
+    });
+    const { getAllPosts } = await import('./blog');
+    const posts = getAllPosts();
+    expect(posts.map((p) => p.slug)).toEqual(['second-post', 'first-post']);
+  });
+
+  it('getPostBySlug returns a known post', async () => {
+    setupFs({
+      '2026-05-01-first-post.mdx': post1,
+      '2026-05-10-second-post.mdx': post2,
+    });
+    const { getPostBySlug } = await import('./blog');
+    const post = getPostBySlug('second-post');
+    expect(post?.frontmatter.title).toBe('Second Post');
+    expect(post?.date).toBe('2026-05-10');
+  });
+
+  it('getPostBySlug returns null for unknown slug', async () => {
+    setupFs({ '2026-05-01-first-post.mdx': post1 });
+    const { getPostBySlug } = await import('./blog');
+    expect(getPostBySlug('nope')).toBeNull();
+  });
+
+  it('throws when required frontmatter is missing', async () => {
+    setupFs({ '2026-05-15-missing.mdx': missingFields });
+    const { getAllPosts } = await import('./blog');
+    expect(() => getAllPosts()).toThrow(/missing required frontmatter/i);
+  });
+
+  it('drafts excluded by default, included with includeDrafts', async () => {
+    setupFs({
+      '2026-05-10-second-post.mdx': post2,
+      '2026-05-20-draft-post.mdx': draft,
+    });
+    const { getAllPosts } = await import('./blog');
+    expect(getAllPosts().map((p) => p.slug)).toEqual(['second-post']);
+    expect(getAllPosts({ includeDrafts: true }).map((p) => p.slug)).toEqual([
+      'draft-post',
+      'second-post',
+    ]);
+  });
+
+  it('getFeaturedPost returns the first featured post', async () => {
+    setupFs({
+      '2026-05-01-first-post.mdx': post1,
+      '2026-05-10-second-post.mdx': post2,
+    });
+    const { getFeaturedPost } = await import('./blog');
+    expect(getFeaturedPost()?.slug).toBe('second-post');
+  });
+
+  it('getFeaturedPost falls back to latest when none featured', async () => {
+    setupFs({ '2026-05-01-first-post.mdx': post1 });
+    const { getFeaturedPost } = await import('./blog');
+    expect(getFeaturedPost()?.slug).toBe('first-post');
+  });
+
+  it('getAllTags counts tags across posts', async () => {
+    setupFs({
+      '2026-05-01-first-post.mdx': post1,
+      '2026-05-10-second-post.mdx': post2,
+    });
+    const { getAllTags } = await import('./blog');
+    const tags = getAllTags();
+    expect(tags.find((t) => t.tag === 'tutorial')?.count).toBe(1);
+    expect(tags.find((t) => t.tag === 'streaming')?.count).toBe(1);
+  });
+
+  it('ignores files that do not match the date-prefix regex', async () => {
+    setupFs({
+      '2026-05-01-first-post.mdx': post1,
+      'not-a-post.mdx': post1,
+      'README.md': 'readme',
+    });
+    const { getAllPosts } = await import('./blog');
+    expect(getAllPosts().map((p) => p.slug)).toEqual(['first-post']);
+  });
+});
diff --git a/apps/website/src/lib/blog.ts b/apps/website/src/lib/blog.ts
new file mode 100644
index 000000000..4eb87354f
--- /dev/null
+++ b/apps/website/src/lib/blog.ts
@@ -0,0 +1,92 @@
+// SPDX-License-Identifier: MIT
+import fs from 'fs';
+import path from 'path';
+import matter from 'gray-matter';
+
+const BLOG_DIR_WORKSPACE = path.join(process.cwd(), 'apps', 'website', 'content', 'blog');
+const BLOG_DIR_LOCAL = path.join(process.cwd(), 'content', 'blog');
+
+export interface PostFrontmatter {
+  title: string;
+  description: string;
+  date: string;
+  tags?: string[];
+  author: string;
+  featured?: boolean;
+  draft?: boolean;
+}
+
+export interface Post {
+  slug: string;
+  date: string;
+  frontmatter: PostFrontmatter;
+  content: string;
+  filename: string;
+}
+
+const FILENAME_RE = /^(\d{4}-\d{2}-\d{2})-(.+)\.mdx$/;
+
+function resolveBlogDir(): string {
+  if (fs.existsSync(BLOG_DIR_WORKSPACE)) return BLOG_DIR_WORKSPACE;
+  if (fs.existsSync(BLOG_DIR_LOCAL)) return BLOG_DIR_LOCAL;
+  return BLOG_DIR_WORKSPACE;
+}
+
+function readPost(dir: string, filename: string): Post | null {
+  const match = filename.match(FILENAME_RE);
+  if (!match) return null;
+  const [, date, slug] = match;
+  const full = path.join(dir, filename);
+  const raw = fs.readFileSync(full, 'utf8');
+  const { data, content } = matter(typeof raw === 'string' ? raw : raw.toString());
+  const fm = data as Partial<PostFrontmatter>;
+  if (!fm.title || !fm.description || !fm.date || !fm.author) {
+    throw new Error(
+      `Blog post ${filename} missing required frontmatter (title, description, date, author).`,
+    );
+  }
+  return {
+    slug,
+    date,
+    frontmatter: fm as PostFrontmatter,
+    content,
+    filename,
+  };
+}
+
+export function getAllPosts(opts: { includeDrafts?: boolean } = {}): Post[] {
+  const dir = resolveBlogDir();
+  if (!fs.existsSync(dir)) return [];
+  const files = fs.readdirSync(dir).filter((f) => typeof f === 'string' && (f as string).endsWith('.mdx'));
+  const posts: Post[] = [];
+  for (const f of files) {
+    const post = readPost(dir, f as string);
+    if (!post) continue;
+    if (post.frontmatter.draft && !opts.includeDrafts) continue;
+    posts.push(post);
+  }
+  return posts.sort((a, b) => (a.date < b.date ? 1 : -1));
+}
+
+export function getPostBySlug(slug: string): Post | null {
+  return getAllPosts({ includeDrafts: true }).find((p) => p.slug === slug) ?? null;
+}
+
+export function getFeaturedPost(): Post | null {
+  const posts = getAllPosts();
+  return posts.find((p) => p.frontmatter.featured) ?? posts[0] ?? null;
+}
+
+export function getAllTags(): { tag: string; count: number }[] {
+  const tags = new Map<string, number>();
+  for (const p of getAllPosts()) {
+    for (const t of p.frontmatter.tags ?? []) {
+      tags.set(t, (tags.get(t) ?? 0) + 1);
+    }
+  }
+  return [...tags.entries()].map(([tag, count]) => ({ tag, count }));
+}
+
+export function getAllSlugs(): string[] {
+  return getAllPosts().map((p) => p.slug);
+}

From 1b7eb642c98ddaf41c13d83ce932f707c194ecfb Mon Sep 17 00:00:00 2001
From: Brian Love <brian@liveloveapp.com>
Date: Sun, 17 May 2026 08:14:11 -0700
Subject: [PATCH 06/20] feat(website): add blog author registry

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
---
 apps/website/src/lib/blog-authors.ts | 22 ++++++++++++++++++++++
 1 file changed, 22 insertions(+)
 create mode 100644 apps/website/src/lib/blog-authors.ts

diff --git a/apps/website/src/lib/blog-authors.ts b/apps/website/src/lib/blog-authors.ts
new file mode 100644
index 000000000..9d61709d6
--- /dev/null
+++ b/apps/website/src/lib/blog-authors.ts
@@ -0,0 +1,22 @@
+// SPDX-License-Identifier: MIT
+export interface Author {
+  name: string;
+  role?: string;
+  bio?: string;
+  twitter?: string;
+  github?: string;
+  avatar?: string;
+}
+
+export const blogAuthors: Record<string, Author> = {
+  brian: {
+    name: 'Brian Love',
+    role: 'Founder, Cacheplane',
+    bio: 'Angular consultant and open-source maintainer. Building agent UI for Angular teams.',
+    github: 'blove',
+  },
+};
+
+export function getAuthor(key: string): Author {
+  return blogAuthors[key] ?? { name: key };
+}

From 774dfeb104b13838ee4dff4bf42c622dc12bb3f7 Mon Sep 17 00:00:00 2001
From: Brian Love <brian@liveloveapp.com>
Date: Sun, 17 May 2026 08:20:22 -0700
Subject: [PATCH 07/20] feat(website): add blog:* analytics events + blog
 surface

---
 apps/website/src/lib/analytics/events.ts | 3 +++
 1 file changed, 3 insertions(+)

diff --git a/apps/website/src/lib/analytics/events.ts b/apps/website/src/lib/analytics/events.ts
index 7a8cdcae0..dce89fab0 100644
--- a/apps/website/src/lib/analytics/events.ts
+++ b/apps/website/src/lib/analytics/events.ts
@@ -18,6 +18,8 @@ export const analyticsEvents = {
   docsCopyCodeClick: 'docs:copy_code_click',
   docsTabSelect: 'docs:tab_select',
   docsSidebarSectionToggle: 'docs:sidebar_section_toggle',
+  blogCtaClick: 'blog:cta_click',
+  blogCopyCodeClick: 'blog:copy_code_click',
 } as const;
 
 export type AnalyticsEventName = (typeof analyticsEvents)[keyof typeof analyticsEvents];
@@ -30,6 +32,7 @@ export type AnalyticsSurface =
   | 'home_whitepaper'
   | 'pricing'
   | 'docs'
+  | 'blog'
   | 'library_landing'
   | 'solution'
   | 'toast'

From b8eeba4619dd6066e94e5be6fbd3aae1b208942d Mon Sep 17 00:00:00 2001
From: Brian Love <brian@liveloveapp.com>
Date: Sun, 17 May 2026 08:21:48 -0700
Subject: [PATCH 08/20] docs(gtm): document blog:* events in taxonomy

---
 docs/gtm/taxonomy.md | 5 ++++-
 1 file changed, 4 insertions(+), 1 deletion(-)

diff --git a/docs/gtm/taxonomy.md b/docs/gtm/taxonomy.md
index 7e52a33aa..8aef28982 100644
--- a/docs/gtm/taxonomy.md
+++ b/docs/gtm/taxonomy.md
@@ -44,6 +44,8 @@ The standard PostHog `$pageview` event is used as-is across all three surfaces.
 | `docs:search_result_click`                  | Result click                                      |
 | `docs:copy_prompt_click`                    | Prompt-copy button                                |
 | `docs:copy_code_click`                      | Code-copy button                                  |
+| `blog:cta_click`                            | Tracked CTA inside a blog post body. Props: `surface: 'blog'`, `cta_id?`, `destination_url?`. |
+| `blog:copy_code_click`                      | Copy-button click on a code block inside a blog post. Props: `surface: 'blog'`, `code_lang?`. |
 | `docs:tab_select`                           | MDX tab change                                    |
 | `docs:sidebar_section_toggle`               | Sidebar nav toggle                                |
 
@@ -122,7 +124,7 @@ Browser events never fire unless the consumer explicitly opts in. See `libs/tele
 |------------------|--------|-------------------------------------------------------------|
 | `source_page`    | string | Stable pathname or surface id (`home`, `compare_langchain_angular`, `pricing`). |
 | `source_section` | string | Stable section/component id where known.                    |
-| `surface`        | enum   | `nav` `mobile_nav` `footer` `home` `pricing` `docs` `library_landing` `solution` `toast` `cockpit` `contact` |
+| `surface`        | enum   | `nav` `mobile_nav` `footer` `home` `pricing` `docs` `blog` `library_landing` `solution` `toast` `cockpit` `contact` |
 | `destination_url`| string | Clicked URL where applicable.                               |
 | `cta_id`         | string | Stable CTA id (see below).                                  |
 | `cta_text`       | string | Visible label where stable.                                 |
@@ -179,3 +181,4 @@ This file is human-edited. When events are added/renamed/removed, update the aff
 | 2026-05-13 | Initial draft per Spec 0. |
 | 2026-05-15 | Drop cockpit:install_command_copied, rename cockpit:six_signals_complete → cockpit:activation_complete (Spec 1C). |
 | 2026-05-15 | Cockpit shell events: rename `recipe_start` → `recipe_opened`; add `mode_switched` and `code_copied` (Spec 1C implementation). |
+| 2026-05-17 | Add `blog:cta_click` + `blog:copy_code_click` events; add `'blog'` to `AnalyticsSurface` (Spec 5). |

From 09c79899f77ce4b9a03de2e709fb3960299382be Mon Sep 17 00:00:00 2001
From: Brian Love <brian@liveloveapp.com>
Date: Sun, 17 May 2026 08:33:37 -0700
Subject: [PATCH 09/20] feat(website): add AuthorByline component

---
 .../src/components/blog/AuthorByline.tsx      | 30 +++++++++++++++++++
 1 file changed, 30 insertions(+)
 create mode 100644 apps/website/src/components/blog/AuthorByline.tsx

diff --git a/apps/website/src/components/blog/AuthorByline.tsx b/apps/website/src/components/blog/AuthorByline.tsx
new file mode 100644
index 000000000..c33403bbd
--- /dev/null
+++ b/apps/website/src/components/blog/AuthorByline.tsx
@@ -0,0 +1,30 @@
+import type { Author } from '../../lib/blog-authors';
+
+export function AuthorByline({ author }: { author: Author }) {
+  return (
+    <div
+      style={{
+        display: 'flex',
+        alignItems: 'center',
+        gap: 12,
+        fontSize: 14,
+        opacity: 0.8,
+      }}
+    >
+      {author.avatar ? (
+        // eslint-disable-next-line @next/next/no-img-element
+        <img
+          src={author.avatar}
+          alt={`${author.name} avatar`}
+          width={32}
+          height={32}
+          style={{ borderRadius: '50%' }}
+        />
+      ) : null}
+      <div>
+        <span style={{ fontWeight: 600 }}>{author.name}</span>
+        {author.role ? <span style={{ opacity: 0.7 }}> · {author.role}</span> : null}
+      </div>
+    </div>
+  );
+}

From 27adfc567a05ef6be7527a0a2319af0cf0715d5c Mon Sep 17 00:00:00 2001
From: Brian Love <brian@liveloveapp.com>
Date: Sun, 17 May 2026 08:55:23 -0700
Subject: [PATCH 10/20] feat(website): add PostCard component with tests

---
 .../src/components/blog/PostCard.spec.tsx     | 35 ++++++++++++
 apps/website/src/components/blog/PostCard.tsx | 54 +++++++++++++++++++
 apps/website/vite.config.mts                  | 15 ++++++
 3 files changed, 104 insertions(+)
 create mode 100644 apps/website/src/components/blog/PostCard.spec.tsx
 create mode 100644 apps/website/src/components/blog/PostCard.tsx
 create mode 100644 apps/website/vite.config.mts

diff --git a/apps/website/src/components/blog/PostCard.spec.tsx b/apps/website/src/components/blog/PostCard.spec.tsx
new file mode 100644
index 000000000..a7429c080
--- /dev/null
+++ b/apps/website/src/components/blog/PostCard.spec.tsx
@@ -0,0 +1,35 @@
+// @vitest-environment jsdom
+import { describe, expect, it } from 'vitest';
+import { render, screen } from '@testing-library/react';
+import { PostCard } from './PostCard';
+import type { Post } from '../../lib/blog';
+
+const post: Post = {
+  slug: 'streaming-chat',
+  date: '2026-05-17',
+  filename: '2026-05-17-streaming-chat.mdx',
+  content: '',
+  frontmatter: {
+    title: 'Build a streaming chat UI',
+    description: 'A tutorial.',
+    date: '2026-05-17',
+    author: 'brian',
+    tags: ['tutorial', 'streaming'],
+  },
+};
+
+describe('PostCard', () => {
+  it('renders title, date, and tag chips', () => {
+    render(<PostCard post={post} />);
+    expect(screen.getByText('Build a streaming chat UI')).toBeTruthy();
+    expect(screen.getByText('2026-05-17')).toBeTruthy();
+    expect(screen.getByText('tutorial')).toBeTruthy();
+    expect(screen.getByText('streaming')).toBeTruthy();
+  });
+
+  it('links to /blog/[slug]', () => {
+    const { container } = render(<PostCard post={post} />);
+    const link = container.querySelector('a[href="/blog/streaming-chat"]');
+    expect(link).toBeTruthy();
+  });
+});
diff --git a/apps/website/src/components/blog/PostCard.tsx b/apps/website/src/components/blog/PostCard.tsx
new file mode 100644
index 000000000..2ace7d993
--- /dev/null
+++ b/apps/website/src/components/blog/PostCard.tsx
@@ -0,0 +1,54 @@
+import Link from 'next/link';
+import { tokens } from '@ngaf/design-tokens';
+import type { Post } from '../../lib/blog';
+
+export function PostCard({ post }: { post: Post }) {
+  const { slug, frontmatter } = post;
+  return (
+    <Link
+      href={`/blog/${slug}`}
+      style={{
+        display: 'flex',
+        flexDirection: 'column',
+        gap: 8,
+        padding: 20,
+        borderRadius: 12,
+        background: tokens.surfaces.surfaceTinted,
+        border: `1px solid ${tokens.surfaces.border}`,
+        color: tokens.colors.textPrimary,
+        textDecoration: 'none',
+      }}
+    >
+      <time
+        dateTime={frontmatter.date}
+        style={{ fontSize: 13, color: tokens.colors.textMuted }}
+      >
+        {frontmatter.date}
+      </time>
+      <h3 style={{ fontSize: 20, fontWeight: 600, margin: 0 }}>
+        {frontmatter.title}
+      </h3>
+      <p style={{ fontSize: 14, color: tokens.colors.textSecondary, margin: 0 }}>
+        {frontmatter.description}
+      </p>
+      {frontmatter.tags && frontmatter.tags.length > 0 ? (
+        <div style={{ display: 'flex', gap: 6, flexWrap: 'wrap', marginTop: 8 }}>
+          {frontmatter.tags.map((tag) => (
+            <span
+              key={tag}
+              style={{
+                fontSize: 12,
+                padding: '2px 8px',
+                borderRadius: 999,
+                background: tokens.colors.accentSurface,
+                color: tokens.colors.accent,
+              }}
+            >
+              {tag}
+            </span>
+          ))}
+        </div>
+      ) : null}
+    </Link>
+  );
+}
diff --git a/apps/website/vite.config.mts b/apps/website/vite.config.mts
new file mode 100644
index 000000000..29ba3befa
--- /dev/null
+++ b/apps/website/vite.config.mts
@@ -0,0 +1,15 @@
+import { defineConfig } from 'vite';
+import { nxViteTsPaths } from '@nx/vite/plugins/nx-tsconfig-paths.plugin';
+
+export default defineConfig({
+  plugins: [nxViteTsPaths()],
+  esbuild: {
+    jsx: 'automatic',
+    jsxImportSource: 'react',
+  },
+  test: {
+    environment: 'jsdom',
+    globals: true,
+    include: ['src/**/*.spec.ts', 'src/**/*.spec.tsx'],
+  },
+});

From ee44c7f5c2118335a33b8a23a9019a56cc54a1b7 Mon Sep 17 00:00:00 2001
From: Brian Love <brian@liveloveapp.com>
Date: Sun, 17 May 2026 08:56:41 -0700
Subject: [PATCH 11/20] feat(website): add FeaturedPostCard + TagChips
 components

---
 .../src/components/blog/FeaturedPostCard.tsx  | 60 +++++++++++++++++++
 apps/website/src/components/blog/TagChips.tsx | 30 ++++++++++
 2 files changed, 90 insertions(+)
 create mode 100644 apps/website/src/components/blog/FeaturedPostCard.tsx
 create mode 100644 apps/website/src/components/blog/TagChips.tsx

diff --git a/apps/website/src/components/blog/FeaturedPostCard.tsx b/apps/website/src/components/blog/FeaturedPostCard.tsx
new file mode 100644
index 000000000..fe826b26f
--- /dev/null
+++ b/apps/website/src/components/blog/FeaturedPostCard.tsx
@@ -0,0 +1,60 @@
+import Link from 'next/link';
+import { tokens } from '@ngaf/design-tokens';
+import type { Post } from '../../lib/blog';
+import { getAuthor } from '../../lib/blog-authors';
+import { AuthorByline } from './AuthorByline';
+
+export function FeaturedPostCard({ post }: { post: Post }) {
+  const { slug, frontmatter } = post;
+  const author = getAuthor(frontmatter.author);
+  return (
+    <Link
+      href={`/blog/${slug}`}
+      style={{
+        display: 'flex',
+        flexDirection: 'column',
+        gap: 12,
+        padding: 32,
+        borderRadius: 16,
+        background: tokens.surfaces.surface,
+        border: `1px solid ${tokens.colors.accent}`,
+        color: tokens.colors.textPrimary,
+        textDecoration: 'none',
+        marginBottom: 32,
+      }}
+    >
+      <span
+        style={{
+          fontSize: 12,
+          textTransform: 'uppercase',
+          letterSpacing: '0.08em',
+          color: tokens.colors.accent,
+        }}
+      >
+        Featured
+      </span>
+      <h2 style={{ fontSize: 32, fontWeight: 600, margin: 0, lineHeight: 1.2 }}>
+        {frontmatter.title}
+      </h2>
+      <p style={{ fontSize: 16, color: tokens.colors.textSecondary, margin: 0 }}>
+        {frontmatter.description}
+      </p>
+      <div
+        style={{
+          display: 'flex',
+          alignItems: 'center',
+          justifyContent: 'space-between',
+          marginTop: 12,
+        }}
+      >
+        <AuthorByline author={author} />
+        <time
+          dateTime={frontmatter.date}
+          style={{ fontSize: 13, color: tokens.colors.textMuted }}
+        >
+          {frontmatter.date}
+        </time>
+      </div>
+    </Link>
+  );
+}
diff --git a/apps/website/src/components/blog/TagChips.tsx b/apps/website/src/components/blog/TagChips.tsx
new file mode 100644
index 000000000..606043e3f
--- /dev/null
+++ b/apps/website/src/components/blog/TagChips.tsx
@@ -0,0 +1,30 @@
+import { tokens } from '@ngaf/design-tokens';
+
+export function TagChips({ tags }: { tags: string[] }) {
+  if (tags.length === 0) return null;
+  return (
+    <div
+      style={{
+        display: 'flex',
+        gap: 8,
+        flexWrap: 'wrap',
+        marginBottom: 24,
+      }}
+    >
+      {tags.map((tag) => (
+        <span
+          key={tag}
+          style={{
+            fontSize: 13,
+            padding: '4px 10px',
+            borderRadius: 999,
+            background: tokens.colors.accentSurface,
+            color: tokens.colors.accent,
+          }}
+        >
+          {tag}
+        </span>
+      ))}
+    </div>
+  );
+}

From 9f32cf54b4bda33ab096281eed2b93553170f888 Mon Sep 17 00:00:00 2001
From: Brian Love <brian@liveloveapp.com>
Date: Sun, 17 May 2026 08:57:47 -0700
Subject: [PATCH 12/20] feat(website): add Blog link to nav

---
 apps/website/src/components/shared/Nav.tsx | 1 +
 1 file changed, 1 insertion(+)

diff --git a/apps/website/src/components/shared/Nav.tsx b/apps/website/src/components/shared/Nav.tsx
index 849e3752b..13ba6146a 100644
--- a/apps/website/src/components/shared/Nav.tsx
+++ b/apps/website/src/components/shared/Nav.tsx
@@ -16,6 +16,7 @@ const links = [
   { label: 'Demo', href: 'https://demo.cacheplane.ai', external: true },
   { label: 'Examples', href: 'https://cockpit.cacheplane.ai', external: true },
   { label: 'Pricing', href: '/pricing', external: false },
+  { label: 'Blog', href: '/blog', external: false },
 ];
 
 function GitHubIcon() {

From c692e3a25ec38d14856fec5bccd9a15d0068c56c Mon Sep 17 00:00:00 2001
From: Brian Love <brian@liveloveapp.com>
Date: Sun, 17 May 2026 09:08:07 -0700
Subject: [PATCH 13/20] fix(website): pin blog.spec.ts to node environment

The new app-local vite config uses jsdom, but blog.spec.ts mocks fs
which requires node. Pin per-file environment directive.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
---
 apps/website/src/lib/blog.spec.ts | 1 +
 1 file changed, 1 insertion(+)

diff --git a/apps/website/src/lib/blog.spec.ts b/apps/website/src/lib/blog.spec.ts
index d75aee593..29f35e6c7 100644
--- a/apps/website/src/lib/blog.spec.ts
+++ b/apps/website/src/lib/blog.spec.ts
@@ -1,3 +1,4 @@
+// @vitest-environment node
 import { describe, expect, it, vi, beforeEach, afterEach } from 'vitest';
 import * as fs from 'fs';
 

From 0d338362a0b2f02f72baa47f72534d3999567e35 Mon Sep 17 00:00:00 2001
From: Brian Love <brian@liveloveapp.com>
Date: Sun, 17 May 2026 09:12:13 -0700
Subject: [PATCH 14/20] feat(website): add /blog index page

---
 apps/website/src/app/blog/page.tsx | 63 ++++++++++++++++++++++++++++++
 1 file changed, 63 insertions(+)
 create mode 100644 apps/website/src/app/blog/page.tsx

diff --git a/apps/website/src/app/blog/page.tsx b/apps/website/src/app/blog/page.tsx
new file mode 100644
index 000000000..6aba612a3
--- /dev/null
+++ b/apps/website/src/app/blog/page.tsx
@@ -0,0 +1,63 @@
+import { createPageMetadata } from '../../lib/site-metadata';
+import { getAllPosts, getFeaturedPost, getAllTags } from '../../lib/blog';
+import { FeaturedPostCard } from '../../components/blog/FeaturedPostCard';
+import { PostCard } from '../../components/blog/PostCard';
+import { TagChips } from '../../components/blog/TagChips';
+
+export const metadata = createPageMetadata({
+  title: 'Blog — Cacheplane',
+  description:
+    'Long-form writing on agent UI for Angular: streaming, generative UI, threads, interrupts, production patterns.',
+  pathname: '/blog',
+  type: 'website',
+});
+
+export default function BlogIndexPage() {
+  const all = getAllPosts();
+  const featured = getFeaturedPost();
+  const rest = featured ? all.filter((p) => p.slug !== featured.slug) : all;
+  const tags = getAllTags().map((t) => t.tag);
+
+  return (
+    <div style={{ maxWidth: 960, margin: '0 auto', padding: '64px 24px' }}>
+      <p
+        style={{
+          fontSize: 13,
+          textTransform: 'uppercase',
+          letterSpacing: '0.08em',
+          marginBottom: 8,
+          opacity: 0.7,
+        }}
+      >
+        Blog
+      </p>
+      <h1
+        style={{
+          fontSize: 48,
+          fontWeight: 600,
+          letterSpacing: '-0.02em',
+          marginBottom: 12,
+        }}
+      >
+        Notes from Cacheplane
+      </h1>
+      <p style={{ fontSize: 18, opacity: 0.8, marginBottom: 32, maxWidth: '60ch' }}>
+        Writing on agent UI for Angular — production patterns, design choices,
+        and what we&apos;re shipping.
+      </p>
+      <TagChips tags={tags} />
+      {featured ? <FeaturedPostCard post={featured} /> : null}
+      <div
+        style={{
+          display: 'grid',
+          gridTemplateColumns: 'repeat(auto-fill, minmax(300px, 1fr))',
+          gap: 16,
+        }}
+      >
+        {rest.map((p) => (
+          <PostCard key={p.slug} post={p} />
+        ))}
+      </div>
+    </div>
+  );
+}

From 1c85ac7a254235417fed2b8bf5dcd6e212f09590 Mon Sep 17 00:00:00 2001
From: Brian Love <brian@liveloveapp.com>
Date: Sun, 17 May 2026 09:13:16 -0700
Subject: [PATCH 15/20] feat(website): add /blog/[slug] dynamic post route

---
 apps/website/src/app/blog/[slug]/page.tsx | 67 +++++++++++++++++++++++
 1 file changed, 67 insertions(+)
 create mode 100644 apps/website/src/app/blog/[slug]/page.tsx

diff --git a/apps/website/src/app/blog/[slug]/page.tsx b/apps/website/src/app/blog/[slug]/page.tsx
new file mode 100644
index 000000000..09df621d4
--- /dev/null
+++ b/apps/website/src/app/blog/[slug]/page.tsx
@@ -0,0 +1,67 @@
+import type { Metadata } from 'next';
+import { notFound } from 'next/navigation';
+import { MdxRenderer } from '../../../components/docs/MdxRenderer';
+import { AuthorByline } from '../../../components/blog/AuthorByline';
+import { getAllPosts, getPostBySlug } from '../../../lib/blog';
+import { getAuthor } from '../../../lib/blog-authors';
+import { createPageMetadata } from '../../../lib/site-metadata';
+
+interface Params {
+  params: Promise<{ slug: string }>;
+}
+
+export function generateStaticParams() {
+  return getAllPosts().map((p) => ({ slug: p.slug }));
+}
+
+export async function generateMetadata({ params }: Params): Promise<Metadata> {
+  const { slug } = await params;
+  const post = getPostBySlug(slug);
+  if (!post || post.frontmatter.draft) {
+    return { title: 'Post not found — Cacheplane' };
+  }
+  return createPageMetadata({
+    title: `${post.frontmatter.title} — Cacheplane`,
+    description: post.frontmatter.description,
+    pathname: `/blog/${post.slug}`,
+    type: 'article',
+  });
+}
+
+export default async function BlogPostPage({ params }: Params) {
+  const { slug } = await params;
+  const post = getPostBySlug(slug);
+  if (!post || post.frontmatter.draft) notFound();
+  const author = getAuthor(post.frontmatter.author);
+  return (
+    <article style={{ maxWidth: 768, margin: '0 auto', padding: '64px 24px' }}>
+      <header style={{ marginBottom: 32 }}>
+        <time
+          dateTime={post.frontmatter.date}
+          style={{ fontSize: 14, opacity: 0.7 }}
+        >
+          {post.frontmatter.date}
+        </time>
+        <h1
+          style={{
+            fontSize: 44,
+            fontWeight: 600,
+            letterSpacing: '-0.02em',
+            margin: '12px 0 16px',
+            lineHeight: 1.15,
+          }}
+        >
+          {post.frontmatter.title}
+        </h1>
+        <AuthorByline author={author} />
+      </header>
+      <MdxRenderer
+        source={post.content}
+        library="agent"
+        section="blog"
+        slug={post.slug}
+        title={post.frontmatter.title}
+      />
+    </article>
+  );
+}

From fe3158d82a5ae5de6e22c903d6d2bdbb9472adeb Mon Sep 17 00:00:00 2001
From: Brian Love <brian@liveloveapp.com>
Date: Sun, 17 May 2026 09:17:36 -0700
Subject: [PATCH 16/20] feat(website): add per-post OG image route

---
 .../src/app/blog/[slug]/opengraph-image.tsx   | 130 ++++++++++++++++++
 1 file changed, 130 insertions(+)
 create mode 100644 apps/website/src/app/blog/[slug]/opengraph-image.tsx

diff --git a/apps/website/src/app/blog/[slug]/opengraph-image.tsx b/apps/website/src/app/blog/[slug]/opengraph-image.tsx
new file mode 100644
index 000000000..273624fff
--- /dev/null
+++ b/apps/website/src/app/blog/[slug]/opengraph-image.tsx
@@ -0,0 +1,130 @@
+import { ImageResponse } from 'next/og';
+import { getPostBySlug } from '../../../lib/blog';
+import { getAuthor } from '../../../lib/blog-authors';
+
+export const runtime = 'nodejs';
+export const alt = 'Cacheplane blog post';
+export const size = { width: 1200, height: 630 };
+export const contentType = 'image/png';
+
+interface Params {
+  params: Promise<{ slug: string }>;
+}
+
+async function loadFont(family: string, weight: number): Promise<ArrayBuffer | null> {
+  try {
+    const css = await fetch(
+      `https://fonts.googleapis.com/css2?family=${encodeURIComponent(family)}:wght@${weight}&display=swap`,
+      { headers: { 'User-Agent': 'Mozilla/5.0 (X11; Linux x86_64) AppleWebKit/537.36' } },
+    ).then((res) => res.text());
+    const match = css.match(/src:\s*url\((https?:\/\/[^)]+)\)/);
+    if (!match) return null;
+    const fontRes = await fetch(match[1]);
+    if (!fontRes.ok) return null;
+    return await fontRes.arrayBuffer();
+  } catch {
+    return null;
+  }
+}
+
+async function loadLocalGaramond(): Promise<ArrayBuffer | null> {
+  try {
+    const { fileURLToPath } = await import('node:url');
+    const { readFile } = await import('node:fs/promises');
+    const { dirname, join } = await import('node:path');
+    // The TTF lives next to the root opengraph-image.tsx, one level up from blog/[slug]
+    const here = dirname(fileURLToPath(import.meta.url));
+    const buf = await readFile(join(here, '../../EBGaramond-Bold.ttf'));
+    return buf.buffer.slice(buf.byteOffset, buf.byteOffset + buf.byteLength) as ArrayBuffer;
+  } catch (err) {
+    console.warn('blog/[slug]/opengraph-image: failed to load local Garamond TTF', err);
+    return null;
+  }
+}
+
+export default async function og({ params }: Params) {
+  const { slug } = await params;
+  const post = getPostBySlug(slug);
+
+  if (!post || post.frontmatter.draft) {
+    return new ImageResponse(
+      (
+        <div
+          style={{
+            width: '100%',
+            height: '100%',
+            display: 'flex',
+            alignItems: 'center',
+            justifyContent: 'center',
+            background: '#0b0d12',
+            color: '#ffffff',
+            fontSize: 64,
+          }}
+        >
+          Cacheplane
+        </div>
+      ),
+      size,
+    );
+  }
+
+  const [garamondBold, interRegular, interBold] = await Promise.all([
+    loadLocalGaramond(),
+    loadFont('Inter', 400),
+    loadFont('Inter', 600),
+  ]);
+  const fonts = [
+    garamondBold && { name: 'EB Garamond', data: garamondBold, weight: 700 as const, style: 'normal' as const },
+    interRegular && { name: 'Inter', data: interRegular, weight: 400 as const, style: 'normal' as const },
+    interBold && { name: 'Inter', data: interBold, weight: 600 as const, style: 'normal' as const },
+  ].filter((f): f is NonNullable<typeof f> => f !== null);
+
+  const author = getAuthor(post.frontmatter.author);
+  return new ImageResponse(
+    (
+      <div
+        style={{
+          width: '100%',
+          height: '100%',
+          display: 'flex',
+          flexDirection: 'column',
+          justifyContent: 'space-between',
+          padding: 64,
+          background: '#0b0d12',
+          color: '#ffffff',
+          fontFamily: 'Inter, sans-serif',
+        }}
+      >
+        <div
+          style={{
+            fontSize: 24,
+            textTransform: 'uppercase',
+            letterSpacing: '0.12em',
+            opacity: 0.6,
+          }}
+        >
+          Cacheplane Blog
+        </div>
+        <div
+          style={{
+            fontFamily: 'EB Garamond, Georgia, serif',
+            fontSize: 64,
+            fontWeight: 700,
+            lineHeight: 1.1,
+            letterSpacing: '-0.02em',
+            maxWidth: '90%',
+          }}
+        >
+          {post.frontmatter.title}
+        </div>
+        <div style={{ fontSize: 24, opacity: 0.7 }}>
+          {author.name} · {post.frontmatter.date}
+        </div>
+      </div>
+    ),
+    {
+      ...size,
+      fonts,
+    },
+  );
+}

From 0bac793b2c30dcbc0647b6959ec1c23c940cd195 Mon Sep 17 00:00:00 2001
From: Brian Love <brian@liveloveapp.com>
Date: Sun, 17 May 2026 09:19:49 -0700
Subject: [PATCH 17/20] feat(website): add /blog/rss.xml RSS 2.0 feed

---
 apps/website/src/app/blog/rss.xml/route.ts | 50 ++++++++++++++++++++++
 1 file changed, 50 insertions(+)
 create mode 100644 apps/website/src/app/blog/rss.xml/route.ts

diff --git a/apps/website/src/app/blog/rss.xml/route.ts b/apps/website/src/app/blog/rss.xml/route.ts
new file mode 100644
index 000000000..a411f4aa7
--- /dev/null
+++ b/apps/website/src/app/blog/rss.xml/route.ts
@@ -0,0 +1,50 @@
+import { NextResponse } from 'next/server';
+import { getAllPosts } from '../../../lib/blog';
+import { SITE_ORIGIN } from '../../../lib/site-metadata';
+
+function escapeXml(s: string): string {
+  return s
+    .replace(/&/g, '&amp;')
+    .replace(/</g, '&lt;')
+    .replace(/>/g, '&gt;');
+}
+
+export async function GET() {
+  const posts = getAllPosts();
+  const items = posts
+    .map((p) => {
+      const url = `${SITE_ORIGIN}/blog/${p.slug}`;
+      const pubDate = (() => {
+        const d = new Date(p.frontmatter.date);
+        return Number.isNaN(d.getTime()) ? '' : d.toUTCString();
+      })();
+      return `    <item>
+      <title><![CDATA[${p.frontmatter.title}]]></title>
+      <link>${url}</link>
+      <guid isPermaLink="true">${url}</guid>
+      <pubDate>${pubDate}</pubDate>
+      <description><![CDATA[${p.frontmatter.description}]]></description>
+    </item>`;
+    })
+    .join('\n');
+
+  const xml = `<?xml version="1.0" encoding="UTF-8" ?>
+<rss version="2.0" xmlns:atom="http://www.w3.org/2005/Atom">
+  <channel>
+    <title>${escapeXml('Cacheplane Blog')}</title>
+    <link>${SITE_ORIGIN}/blog</link>
+    <atom:link href="${SITE_ORIGIN}/blog/rss.xml" rel="self" type="application/rss+xml" />
+    <description>${escapeXml('Writing on agent UI for Angular.')}</description>
+    <language>en</language>
+${items}
+  </channel>
+</rss>
+`;
+
+  return new NextResponse(xml, {
+    headers: {
+      'Content-Type': 'application/rss+xml; charset=utf-8',
+      'Cache-Control': 'public, max-age=300, s-maxage=300',
+    },
+  });
+}

From c3c233557367b9d19736fd0e62fbc97f4b778bac Mon Sep 17 00:00:00 2001
From: Brian Love <brian@liveloveapp.com>
Date: Sun, 17 May 2026 09:26:23 -0700
Subject: [PATCH 18/20] feat(website): include /blog routes in sitemap

---
 apps/website/src/lib/site-metadata.ts | 6 ++++--
 1 file changed, 4 insertions(+), 2 deletions(-)

diff --git a/apps/website/src/lib/site-metadata.ts b/apps/website/src/lib/site-metadata.ts
index 3ef9e3ea4..545d9df88 100644
--- a/apps/website/src/lib/site-metadata.ts
+++ b/apps/website/src/lib/site-metadata.ts
@@ -1,6 +1,7 @@
 import type { Metadata } from 'next';
 import { getAllSolutionSlugs } from './solutions-data';
 import { docsConfig } from './docs-config';
+import { getAllPosts } from './blog';
 
 export const SITE_ORIGIN = 'https://cacheplane.ai';
 export const SITE_NAME = 'Agent UI for Angular';
@@ -52,13 +53,14 @@ export function createPageMetadata({
 }
 
 export function getSitemapRoutes(): string[] {
-  const staticRoutes = ['/', '/angular', '/render', '/chat', '/pricing', '/solutions', '/pilot-to-prod', '/docs'];
+  const staticRoutes = ['/', '/angular', '/render', '/chat', '/pricing', '/solutions', '/pilot-to-prod', '/docs', '/blog'];
   const solutionRoutes = getAllSolutionSlugs().map((slug) => `/solutions/${slug}`);
   const docsRoutes = docsConfig.flatMap((library) =>
     library.sections.flatMap((section) =>
       section.pages.map((page) => `/docs/${library.id}/${page.section}/${page.slug}`),
     ),
   );
+  const blogRoutes = getAllPosts().map((p) => `/blog/${p.slug}`);
 
-  return [...staticRoutes, ...solutionRoutes, ...docsRoutes];
+  return [...staticRoutes, ...solutionRoutes, ...docsRoutes, ...blogRoutes];
 }

From adaa39c2ef599887aa2f26889ab84a88eafbd8e7 Mon Sep 17 00:00:00 2001
From: Brian Love <brian@liveloveapp.com>
Date: Sun, 17 May 2026 09:36:11 -0700
Subject: [PATCH 19/20] feat(website): seed pillar post on streaming chat in
 Angular

---
 ...ming-chat-ui-in-angular-with-langgraph.mdx | 337 ++++++++++++++++++
 1 file changed, 337 insertions(+)
 create mode 100644 apps/website/content/blog/2026-05-17-build-a-streaming-chat-ui-in-angular-with-langgraph.mdx

diff --git a/apps/website/content/blog/2026-05-17-build-a-streaming-chat-ui-in-angular-with-langgraph.mdx b/apps/website/content/blog/2026-05-17-build-a-streaming-chat-ui-in-angular-with-langgraph.mdx
new file mode 100644
index 000000000..dbbcf084b
--- /dev/null
+++ b/apps/website/content/blog/2026-05-17-build-a-streaming-chat-ui-in-angular-with-langgraph.mdx
@@ -0,0 +1,337 @@
+---
+title: "Build a Streaming Chat UI in Angular with LangGraph"
+description: "Step-by-step tutorial for shipping a production streaming chat in Angular — signal-native, design-system-friendly, and wired to a LangGraph backend."
+date: 2026-05-17
+tags: [tutorial, streaming, langgraph, angular]
+author: brian
+featured: true
+---
+
+Most AI chat features still ship without streaming.
+They buffer the full response on the server, then drop it into the UI in one paste.
+
+That is the line between a demo and a production interface.
+
+Streaming is not a polish item.
+It is the difference between a user waiting two seconds and a user waiting eight.
+It is also the difference between an interface that feels alive and one that feels broken.
+
+This post is the tutorial I wish I had when I started shipping agentic chat in Angular.
+We are going to wire a real streaming chat UI — signal-native, design-system-friendly, and connected to a LangGraph backend — using `@ngaf/chat` and `@ngaf/langgraph`.
+
+No buffered responses.
+No hand-rolled SSE plumbing.
+No fork of someone's React component.
+
+## tl;dr
+
+- Streaming is the production-vs-demo line for chat. Buffered responses feel broken once a user has seen the alternative.
+- `@ngaf/chat` is a signal-native Angular chat UI. `@ngaf/langgraph` is the transport that wires it to a LangGraph backend.
+- The wiring is three lines: `provideAgent`, `agent()`, and `<chat [agent]="...">`.
+- The production work is not the chat. It is errors, threads, and generative UI fallbacks.
+- If you are building agentic features in Angular today, this stack is the shortest path to a real interface.
+
+## Why streaming matters
+
+A user reads at roughly 200 to 300 words per minute.
+A modern model produces tokens faster than that.
+
+If you stream, the user starts reading before the model has finished thinking.
+If you buffer, every response feels like a page load — except the user does not know how long the page will take.
+
+The numbers are not subtle.
+Buffered chat measurably loses users.
+Streaming chat measurably keeps them.
+The longer the response, the wider the gap.
+
+But the deeper reason is psychological.
+A response that appears one token at a time tells the user the system is working.
+A response that hangs for six seconds and then dumps a wall of text tells the user nothing — until it is too late to course-correct.
+
+Streaming also unlocks a second behavior most teams forget about: **interruption**.
+If the response is incremental, the user can stop a run that is going the wrong direction before it finishes burning tokens.
+That is not just a cost story. It is a trust story.
+A system that can be steered mid-thought feels collaborative.
+A system that has to be waited out feels like a slot machine.
+
+This is why streaming changes the conversation from "is it broken?" to "is this the answer I wanted?"
+That second question is the one your product actually needs the user to be asking.
+
+## The architecture in three boxes
+
+The wiring is simple once you see the seams.
+
+**LangGraph backend.**
+This is where your agent graph lives — nodes, edges, tools, interrupts.
+It exposes a streaming endpoint over SSE.
+You do not write the transport. LangGraph does.
+
+**`@ngaf/langgraph` adapter.**
+This is the Angular-side translator.
+It takes LangGraph's `ThreadState` and turns it into a signal-shaped `AgentCheckpoint` that the chat UI knows how to render.
+It also owns the run lifecycle — submit, cancel, retry — and the thread CRUD.
+
+**`@ngaf/chat` UI.**
+This is the rendering layer.
+Message list, input, suggestions, interrupt panels, tool-call cards, reasoning blocks.
+Every piece is a signal, every signal flows through OnPush change detection, and everything is themeable through CSS custom properties.
+
+The contract between the adapter and the UI is small on purpose.
+The chat does not know it is talking to LangGraph.
+The adapter does not know how messages get rendered.
+That separation is what lets you swap the backend, theme the UI, or replace a single component without touching the rest.
+
+It is also what makes the stack viable for teams that do not control the backend.
+If your backend is LangGraph, the adapter is what you reach for.
+If your backend is something else, the adapter is the only piece that changes.
+The chat — and every component, theme, and slot inside it — is the same.
+
+<ArchFlowDiagram />
+
+## Scaffold
+
+We will start with a fresh Angular 20 app. Three commands and three files.
+
+<Steps>
+<Step title="Install the packages">
+
+<Tabs items={["npm", "pnpm", "yarn"]}>
+<Tab label="npm">
+
+```bash
+npm install @ngaf/chat @ngaf/langgraph marked
+```
+
+</Tab>
+<Tab label="pnpm">
+
+```bash
+pnpm add @ngaf/chat @ngaf/langgraph marked
+```
+
+</Tab>
+<Tab label="yarn">
+
+```bash
+yarn add @ngaf/chat @ngaf/langgraph marked
+```
+
+</Tab>
+</Tabs>
+
+`marked` is the markdown renderer the chat uses for assistant messages.
+It is a peer dependency so you can swap it if you need to.
+
+</Step>
+<Step title="Wire the providers">
+
+```ts
+// app.config.ts
+import { ApplicationConfig } from '@angular/core';
+import { provideAgent } from '@ngaf/langgraph';
+import { provideChat } from '@ngaf/chat';
+
+export const appConfig: ApplicationConfig = {
+  providers: [
+    provideAgent({ apiUrl: 'http://localhost:2024' }),
+    provideChat({ assistantName: 'Assistant' }),
+  ],
+};
+```
+
+`provideAgent` is the transport. `provideChat` is the UI configuration.
+They are independent on purpose — you can use one without the other.
+
+</Step>
+<Step title="Create the agent in your component">
+
+```ts
+// chat-page.component.ts
+import { Component, ChangeDetectionStrategy, signal } from '@angular/core';
+import { agent } from '@ngaf/langgraph';
+import { ChatComponent } from '@ngaf/chat';
+
+@Component({
+  selector: 'app-chat-page',
+  standalone: true,
+  imports: [ChatComponent],
+  changeDetection: ChangeDetectionStrategy.OnPush,
+  template: `<div style="height: 100vh"><chat [agent]="chatAgent" /></div>`,
+})
+export class ChatPageComponent {
+  protected readonly chatAgent = agent({
+    assistantId: 'chat_agent',
+    threadId: signal(null),
+  });
+}
+```
+
+`agent()` is a factory.
+It returns a signal-shaped object that the chat reads from and writes to.
+`threadId` is a signal so the chat can swap threads without re-instantiating the agent.
+
+</Step>
+</Steps>
+
+That is the entire wiring.
+No global stylesheet to import. No PostCSS config. No Tailwind setup.
+The chat ships with its own design tokens and component-scoped styles.
+
+The one thing worth calling out is the `assistantId`.
+That is the name of your LangGraph graph — the entry point the run will execute against.
+If you have multiple graphs, you have multiple `agent()` instances, and you decide which one mounts where.
+A support graph in one route, a coding graph in another, the same chat shell rendering both.
+
+## Render the chat
+
+The `<chat>` component handles the standard surface — message list, input, send button, suggestion chips, scroll behavior, autosizing, the lot.
+
+```html
+<chat [agent]="chatAgent" />
+```
+
+That is the minimum.
+You will quickly want a welcome state, suggestions, and a header.
+
+```ts
+template: `
+  <div style="height: 100vh">
+    <chat [agent]="chatAgent">
+      <ng-template chatWelcome>
+        <h1>What can I help you ship today?</h1>
+        <p>Ask me about your repo, your roadmap, or the deploy that just failed.</p>
+      </ng-template>
+
+      <ng-template chatSuggestions>
+        <chat-suggestion (click)="ask('Summarize the open PRs')">
+          Summarize the open PRs
+        </chat-suggestion>
+        <chat-suggestion (click)="ask('Explain the last deploy')">
+          Explain the last deploy
+        </chat-suggestion>
+      </ng-template>
+    </chat>
+  </div>
+`,
+```
+
+The slot pattern is intentional.
+The chat does not opinion-set your welcome state.
+It does not pick your suggestions.
+It hands you the slots and gets out of the way.
+
+This is the thing I would not compromise on when picking a chat library.
+A chat component that owns its welcome copy, its suggestion list, and its empty states is a chat component that fights you the moment your product matures past the demo phase.
+A chat component that exposes those as slots is one you can grow with.
+
+Theming is a separate concern.
+The chat reads from CSS custom properties — `--chat-bg`, `--chat-fg`, `--chat-accent`, and a few dozen more.
+If you are already using a design system, you map your tokens onto theirs in a single stylesheet and the chat picks them up.
+
+## What is happening under the hood
+
+The adapter exposes a small contract.
+The chat consumes it.
+Everything else is implementation detail.
+
+The contract is roughly:
+
+- `messages` — a signal of the current thread's messages
+- `status` — a signal of `'idle' | 'loading' | 'streaming' | 'error'`
+- `submit(text)` — push a user message and start a run
+- `cancel()` — abort the current run
+- `retry()` — re-run the last user message
+
+Notice what is not in there.
+No event emitters. No observables to subscribe to. No imperative `subscribe(messages, render)` plumbing.
+
+Everything is a signal.
+The chat template reads `messages()` directly.
+OnPush change detection picks up the writes and re-renders only the components that depend on the changed signal.
+
+This matters more than it looks.
+Angular's signal model maps cleanly onto streaming because streaming is, at the data-shape level, a sequence of small writes to a growing list.
+Signals are a sequence of small writes to a growing list.
+The mental model and the runtime model are the same shape.
+
+That is why the chat does not need an internal store, a reducer, or a state machine.
+The agent is the state. The signal is the read. The template is the render.
+
+It also matters for testing.
+Because the contract is signals all the way down, you can mock the agent with a plain object — no harness, no fakes, no subscription bookkeeping.
+Write a signal, the chat re-renders. Write another signal, the chat re-renders again.
+That is the entire testing story for the UI layer.
+
+The transport story is the same shape one level down.
+The adapter reads from LangGraph's SSE stream and writes the parsed events into the agent's signals.
+You can swap the transport — a fake stream, a recorded fixture, a different backend entirely — and the chat does not know the difference.
+That is the boundary the contract was designed to enforce.
+
+## Production patterns
+
+The scaffold above gets you to a working chat in about ten minutes.
+The remaining ninety percent of the work is in three buckets.
+
+### 1. Errors and retries
+
+Models fail. Networks fail. Tools time out.
+The default behavior is to surface the error in the chat with a retry affordance, but most teams want more than the default.
+
+Two patterns I would always implement:
+
+- **Per-message retry**, so a failed assistant response can be re-run without resubmitting the user's message.
+- **Transport-level retry with backoff**, so transient SSE drops do not surface as errors at all.
+
+The adapter exposes both as configuration on `provideAgent`.
+A third pattern worth thinking about early: **graceful degradation when streaming is unavailable**.
+Some networks strip SSE. Some corporate proxies buffer it. The chat will fall back to a non-streaming render, but you should know that path exists before a customer finds it.
+The depth of what you can do here is in the [error handling guide](/docs/chat/guides/lifecycle).
+
+### 2. Threads and persistence
+
+A single-thread chat is a demo.
+A real product remembers conversations across sessions and across devices.
+
+LangGraph handles the persistence on the backend.
+The adapter exposes thread CRUD through `@langchain/langgraph-sdk` — list threads, create a thread, switch threads, delete a thread.
+
+The pattern is to bind your `threadId` signal to your router or your sidebar selection.
+When the signal changes, the chat re-reads from the new thread automatically. No manual unsubscribe. No race conditions.
+
+What you do with that capability is a product decision, not a framework one.
+Some teams scope threads to a project. Others scope them to a task. Others scope them to the user's session and let the agent's memory do the cross-session work.
+There is no right answer — but there is a wrong one, which is to ignore the question and ship a chat where every refresh starts from zero.
+
+If you are building a multi-thread sidebar, the [`<chat-sidebar>`](/docs/chat/components/chat-sidebar) primitive gives you the layout without locking you into a specific persistence model.
+
+### 3. Generative UI fallbacks
+
+Sometimes the model wants to do more than render text.
+Tool calls produce structured output. Interrupts ask for human input. Subagents return their own state.
+
+The chat handles each of these as a first-class message type.
+You do not need to write a custom renderer to get the default behavior — tool calls become cards, interrupts become panels, subagents become collapsible blocks.
+
+When you do need custom rendering — and you will — every one of these is a templatable slot.
+Pass a template, override the default, ship the variant you actually want.
+This is the seam where a generic chat becomes your chat.
+The branded card for your most important tool. The custom approval flow for your most sensitive interrupt. The product-specific summary block when a subagent finishes a long task.
+The [generative UI guide](/docs/chat/guides/generative-ui) walks through each surface in depth.
+
+## Where to go from here
+
+The scaffold above is the smallest possible production-shaped chat.
+It is not the whole story.
+
+Three places to look next:
+
+- The [cockpit chat example](/docs/chat/getting-started/quickstart) — a full multi-thread, multi-agent chat shell with real LangGraph graphs behind it.
+- The [persistence guide](/docs/chat/guides/lifecycle) — how to manage threads, runs, and resume state across sessions.
+- The [interrupts guide](/docs/chat/guides/streaming) — how to handle human-in-the-loop pauses without breaking the streaming model.
+
+<Callout type="info" title="Building this for an enterprise team?">
+If you are wiring `@ngaf/chat` into a regulated, multi-tenant, or design-system-heavy environment, we have a paid track for that. [Talk to us about the enterprise track →](/contact?source=blog_streaming_pillar&track=enterprise)
+</Callout>
+
+The interesting work in agentic software is not the chat itself.
+It is everything the chat lets you stop building so you can get back to the part that actually matters.

From b5b4c7892afdb89ecb7c623946012c312bb99b90 Mon Sep 17 00:00:00 2001
From: Brian Love <brian@liveloveapp.com>
Date: Sun, 17 May 2026 09:38:41 -0700
Subject: [PATCH 20/20] fix(website): normalize YAML Date frontmatter to string

YAML parses unquoted ISO dates (date: 2026-05-17) as Date objects;
this broke React rendering and the typed string contract. Coerce
to YYYY-MM-DD string in readPost.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
---
 apps/website/src/lib/blog.ts | 16 ++++++++++++----
 1 file changed, 12 insertions(+), 4 deletions(-)

diff --git a/apps/website/src/lib/blog.ts b/apps/website/src/lib/blog.ts
index 4eb87354f..c59a509e2 100644
--- a/apps/website/src/lib/blog.ts
+++ b/apps/website/src/lib/blog.ts
@@ -37,18 +37,26 @@ function readPost(dir: string, filename: string): Post | null {
   if (!match) return null;
   const [, date, slug] = match;
   const full = path.join(dir, filename);
-  const raw = fs.readFileSync(full, 'utf8');
-  const { data, content } = matter(typeof raw === 'string' ? raw : raw.toString());
-  const fm = data as Partial<PostFrontmatter>;
+  const raw = fs.readFileSync(full, 'utf8') as unknown as string;
+  const { data, content } = matter(raw);
+  const fm = data as Partial<PostFrontmatter> & { date?: unknown };
   if (!fm.title || !fm.description || !fm.date || !fm.author) {
     throw new Error(
       `Blog post ${filename} missing required frontmatter (title, description, date, author).`,
     );
   }
+  // YAML parses unquoted ISO dates as Date objects; normalize to string.
+  const rawDate: unknown = fm.date;
+  const dateString =
+    rawDate instanceof Date ? rawDate.toISOString().slice(0, 10) : String(rawDate);
+  const normalized: PostFrontmatter = {
+    ...(fm as PostFrontmatter),
+    date: dateString,
+  };
   return {
     slug,
     date,
-    frontmatter: fm as PostFrontmatter,
+    frontmatter: normalized,
     content,
     filename,
   };