From 53a15543eedbc904c87e3d7f4bde7eae1e47053e Mon Sep 17 00:00:00 2001
From: Brian Love <brian@liveloveapp.com>
Date: Thu, 20 Aug 2026 11:36:18 -0700
Subject: [PATCH 01/35] docs(plan): ai search optimization plan for
 threadplane.ai

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
---
 .../2026-08-20-ai-search-optimization.md      | 2174 +++++++++++++++++
 1 file changed, 2174 insertions(+)
 create mode 100644 docs/superpowers/plans/2026-08-20-ai-search-optimization.md

diff --git a/docs/superpowers/plans/2026-08-20-ai-search-optimization.md b/docs/superpowers/plans/2026-08-20-ai-search-optimization.md
new file mode 100644
index 000000000..3d56fc8d9
--- /dev/null
+++ b/docs/superpowers/plans/2026-08-20-ai-search-optimization.md
@@ -0,0 +1,2174 @@
+# AI Search Optimization (threadplane.ai) 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:** Make threadplane.ai maximally eligible for, and measurable in, Google's generative AI search surfaces (AI Overviews, AI Mode, Discover) plus third-party AI answer engines — by fixing the technical-structure gaps Google's AI optimization guide actually calls out, and by standing up a Search Console API analysis harness for ongoing diagnosis.
+
+**Architecture:** Four phases. Phase 1 builds a dependency-free Google Search Console API harness (service-account JWT via `node:crypto` + `fetch`) that pulls Search Analytics, Sitemaps, and URL Inspection data into committed JSON snapshots plus a derived report. Phase 2 fixes the technical-structure gaps found in the audit (no JSON-LD anywhere, no sitemap `lastmod`, no article dates/authors in metadata, one shared OG image, brand-name inconsistency, heading text polluted by anchor glyphs, agent-hostile markup). Phase 3 closes content and E-E-A-T gaps. Phase 4 wires ongoing measurement (AI-crawler and AI-referral tracking through the existing PostHog server client, plus a documented manual export for the Search Console Generative AI report, which is **not** in any API as of 2026-08).
+
+**Tech Stack:** Next.js App Router (`apps/website`), TypeScript, vitest (`apps/website/vite.config.mts`), `tsx` for scripts (already a root devDependency), `posthog-node` (already an `apps/website` dependency), Google Search Console API v3 over raw `fetch`. **No new npm dependencies** — deliberately, because regenerating `package-lock.json` on macOS drops the Linux `@next/swc-*` bindings and breaks CI.
+
+---
+
+## Background: What the audit found
+
+Evidence gathered 2026-08-20 against the live site and `apps/website` on this branch.
+
+**Already good — do not "fix" these:**
+- `robots.txt` is fully permissive (`User-agent: * / Allow: /`) and points at the sitemap. All AI crawlers (Google-Extended, GPTBot, ClaudeBot, PerplexityBot) are therefore allowed. Correct posture for AI visibility.
+- Sitemap is generated from real route data: 140 URLs (11 static, 3 solutions, ~117 docs, 9 blog).
+- Pages are server-rendered with full content in the HTML (home 1,675 words / docs installation 1,985 / blog tutorial 3,103). No JS-SEO problem.
+- Canonicals are emitted on every page that goes through `createPageMetadata`.
+- Newer blog posts already use question-form H2s (`How do we bind Angular to it?`) — exactly the shape RAG systems extract well.
+- All 21 homepage `<img>` tags have `alt`.
+- `llms.txt` / `llms-full.txt` exist. Google explicitly says these do **nothing** for Google Search — keep them anyway for non-Google engines, but do not invest further there.
+
+**Gaps this plan fixes:**
+
+| # | Gap | Evidence |
+|---|-----|----------|
+| G1 | Zero structured data sitewide | `grep -rl "application/ld+json" src lib` → no matches; live HTML `ld+json` count = 0 on home, docs, and blog |
+| G2 | Sitemap has no `lastmod` | `src/app/sitemap.ts` emits only `changeFrequency`/`priority` — the two signals Google ignores, and omits the one it uses |
+| G3 | Blog metadata has no `publishedTime`, `modifiedTime`, `authors`, or `tags` | `createPageMetadata` in `src/lib/site-metadata.ts` has no article fields |
+| G4 | Every page shares one OG image (`/opengraph-image`) | `DEFAULT_SOCIAL_IMAGE` is the only value passed |
+| G5 | Brand name inconsistency in titles | blog titles use `— ThreadPlane`, docs use `- Threadplane`, root uses `Threadplane` |
+| G6 | Heading text is polluted by the anchor glyph | live docs H2s extract as `#Prerequisites`; `MdxRenderer.tsx:37,43` renders a literal `#` text node *before* the heading text |
+| G7 | Blog posts contain zero images/diagrams | live blog HTML: `img` count = 0. Google's guide explicitly asks for high-quality images/video |
+| G8 | No author/about surface for E-E-A-T | `blogAuthors` has a bio string but there is no `/about` page and no `Person` entity anywhere |
+| G9 | No visibility measurement for AI surfaces | no crawler logging, no AI-referral tracking, no GSC harness |
+| G10 | 3 `solutions/*` pages are programmatic and thin | `src/lib/solutions-data.ts` is 9.4 KB total for 3 pages — scaled-content-abuse adjacent if expanded |
+
+**What Google's guide says NOT to do (do not let scope creep add these):**
+- No `llms.txt`-style AI-specific files as a *Search* tactic.
+- No content "chunking" for retrieval — multi-topic pages are understood fine.
+- No AI-specific keyword rewrites; write naturally.
+- No pursuit of inauthentic mentions.
+- Structured data is *optional* for AI features (it gates rich results). We add it in Phase 2 because it is cheap, it is a rich-result and entity-clarity win, and it costs nothing at runtime — not because it unlocks AI Overviews.
+
+**Deliberately out of scope:** the guide's third pillar — Merchant Center product feeds, Google Business Profile, and the Business Agent / Universal Commerce Protocol surfaces — is aimed at retail and local businesses. Threadplane sells developer licenses through Stripe with no physical location and no product catalog, so none of it applies. This is a scope decision, not an oversight.
+
+**Critical constraint on measurement:** as of 2026-08-11, the Search Console **Generative AI performance report is UI-only**. `searchanalytics.query`'s `type` field still accepts only `web|image|video|news|discover|googleNews`; there is no `aiMode`/`aiOverview` type, no `searchAppearance` value for AI features, and no BigQuery export. Any plan or tool that claims to pull AI Overview impressions programmatically is wrong. Phase 1 therefore uses the API for everything it *can* answer (query/page performance, striking-distance, index coverage), and Phase 4 documents a manual CSV export for the AI report.
+
+---
+
+## File Structure
+
+**Phase 1 — GSC harness (new, self-contained):**
+- `apps/website/scripts/gsc/auth.ts` — service-account JWT → access token. Only file that touches crypto.
+- `apps/website/scripts/gsc/api.ts` — thin typed wrappers over the four GSC endpoints.
+- `apps/website/scripts/gsc/pull.ts` — CLI entrypoint: writes raw snapshots to `apps/website/.gsc/`.
+- `apps/website/scripts/gsc/report.ts` — CLI entrypoint: reads snapshots, writes a markdown report. Pure functions, unit-testable.
+- `apps/website/scripts/gsc/analysis.ts` — pure analysis functions (no I/O) consumed by `report.ts`.
+- `apps/website/scripts/gsc/analysis.spec.ts` — vitest coverage of the analysis functions.
+- `apps/website/scripts/gsc/README.md` — service-account setup runbook.
+
+**Phase 2 — site metadata and structured data:**
+- `apps/website/src/lib/structured-data.ts` (new) — JSON-LD builders, pure functions.
+- `apps/website/src/lib/structured-data.spec.ts` (new).
+- `apps/website/src/components/shared/JsonLd.tsx` (new) — one render component.
+- `apps/website/src/lib/site-metadata.ts` (modify) — article fields, brand constant, `getSitemapEntries`.
+- `apps/website/src/app/sitemap.ts` (modify) — emit `lastModified`.
+- `apps/website/src/app/layout.tsx` (modify) — Organization + WebSite JSON-LD.
+- `apps/website/src/app/blog/[slug]/page.tsx` (modify) — article metadata + Article/Breadcrumb JSON-LD.
+- `apps/website/src/app/blog/[slug]/opengraph-image.tsx` (new) — per-post OG image.
+- `apps/website/src/app/docs/[library]/[section]/[slug]/page.tsx` (modify) — TechArticle/Breadcrumb JSON-LD.
+- `apps/website/src/components/docs/MdxRenderer.tsx` (modify) — anchor glyph out of heading text.
+
+**Phase 3 — content:**
+- `apps/website/src/app/about/page.tsx` (new).
+- `apps/website/content/blog/*.mdx` (modify — add diagrams).
+
+**Phase 4 — measurement:**
+- `apps/website/src/middleware.ts` (new) — AI crawler + AI referral capture.
+- `apps/website/src/lib/analytics/ai-traffic.ts` (new) — pure UA/referrer classification.
+- `apps/website/src/lib/analytics/ai-traffic.spec.ts` (new).
+- `apps/website/src/lib/analytics/events.ts` (modify) — register the two new events.
+- `docs/gtm/ai-search-measurement.md` (new) — the manual GSC AI-report runbook.
+
+---
+
+## Phase 1 — Search Console API analysis harness
+
+### Task 1: Service-account auth
+
+**Files:**
+- Create: `apps/website/scripts/gsc/auth.ts`
+- Create: `apps/website/scripts/gsc/README.md`
+
+- [ ] **Step 1: Write the setup runbook**
+
+Create `apps/website/scripts/gsc/README.md`:
+
+```markdown
+# Search Console API harness
+
+## One-time setup
+
+1. In Google Cloud console, create (or reuse) a project and enable the
+   **Google Search Console API** (`searchconsole.googleapis.com`).
+2. Create a service account. No project-level IAM roles are needed.
+3. Create a JSON key for that service account and download it.
+4. In Search Console, open the `threadplane.ai` **Domain property** →
+   Settings → Users and permissions → Add user → paste the service
+   account's `client_email` → permission **Full** (required: the URL
+   Inspection API rejects "Restricted" users).
+5. Export the key for local use — do NOT commit it:
+
+   export GSC_SERVICE_ACCOUNT_JSON="$(cat ~/secrets/threadplane-gsc.json)"
+   export GSC_SITE_URL="sc-domain:threadplane.ai"
+
+## Usage
+
+    npx tsx apps/website/scripts/gsc/pull.ts        # writes apps/website/.gsc/*.json
+    npx tsx apps/website/scripts/gsc/report.ts      # writes apps/website/.gsc/report.md
+
+## What this CANNOT do
+
+The Search Console **Generative AI performance report** (AI Overviews /
+AI Mode impressions and clicks) is UI-only as of 2026-08. It is not in
+`searchanalytics.query`, not in `searchAppearance`, and not in the
+BigQuery bulk export. See `docs/gtm/ai-search-measurement.md` for the
+manual export procedure.
+```
+
+- [ ] **Step 2: Write the auth module**
+
+Create `apps/website/scripts/gsc/auth.ts`:
+
+```ts
+// SPDX-License-Identifier: MIT
+import { createSign } from 'node:crypto';
+
+const TOKEN_URL = 'https://oauth2.googleapis.com/token';
+const SCOPE = 'https://www.googleapis.com/auth/webmasters.readonly';
+
+interface ServiceAccountKey {
+  client_email: string;
+  private_key: string;
+}
+
+function base64url(value: object): string {
+  return Buffer.from(JSON.stringify(value)).toString('base64url');
+}
+
+export function readServiceAccountKey(): ServiceAccountKey {
+  const raw = process.env['GSC_SERVICE_ACCOUNT_JSON'];
+  if (!raw) {
+    throw new Error(
+      'GSC_SERVICE_ACCOUNT_JSON is not set. See apps/website/scripts/gsc/README.md.',
+    );
+  }
+  const parsed = JSON.parse(raw) as Partial<ServiceAccountKey>;
+  if (!parsed.client_email || !parsed.private_key) {
+    throw new Error('GSC_SERVICE_ACCOUNT_JSON is missing client_email or private_key.');
+  }
+  return { client_email: parsed.client_email, private_key: parsed.private_key };
+}
+
+export async function getAccessToken(nowSeconds = Math.floor(Date.now() / 1000)): Promise<string> {
+  const key = readServiceAccountKey();
+  const signingInput = [
+    base64url({ alg: 'RS256', typ: 'JWT' }),
+    base64url({
+      iss: key.client_email,
+      scope: SCOPE,
+      aud: TOKEN_URL,
+      iat: nowSeconds,
+      exp: nowSeconds + 3600,
+    }),
+  ].join('.');
+  const signature = createSign('RSA-SHA256')
+    .update(signingInput)
+    .sign(key.private_key, 'base64url');
+
+  const response = await fetch(TOKEN_URL, {
+    method: 'POST',
+    headers: { 'content-type': 'application/x-www-form-urlencoded' },
+    body: new URLSearchParams({
+      grant_type: 'urn:ietf:params:oauth:grant-type:jwt-bearer',
+      assertion: `${signingInput}.${signature}`,
+    }),
+  });
+
+  if (!response.ok) {
+    throw new Error(`Token exchange failed: ${response.status} ${await response.text()}`);
+  }
+  const json = (await response.json()) as { access_token?: string };
+  if (!json.access_token) throw new Error('Token exchange returned no access_token.');
+  return json.access_token;
+}
+```
+
+- [ ] **Step 3: Verify auth end to end**
+
+Run (with the env vars from the README exported):
+
+```bash
+npx tsx -e "import('./apps/website/scripts/gsc/auth.ts').then(async m => console.log((await m.getAccessToken()).slice(0, 12) + '…'))"
+```
+
+Expected: a token prefix like `ya29.c.b49…`. If it returns `401 invalid_grant`, the key is wrong; if the later API calls return `403`, the service account was not added to the Search Console property.
+
+- [ ] **Step 4: Ignore the snapshot directory**
+
+Append to `apps/website/.gitignore` (create the file if absent):
+
+```
+.gsc/
+```
+
+- [ ] **Step 5: Commit**
+
+```bash
+git add apps/website/scripts/gsc/auth.ts apps/website/scripts/gsc/README.md apps/website/.gitignore
+git commit -m "feat(website): search console api service-account auth"
+```
+
+---
+
+### Task 2: Typed API wrappers
+
+**Files:**
+- Create: `apps/website/scripts/gsc/api.ts`
+
+- [ ] **Step 1: Write the API module**
+
+Create `apps/website/scripts/gsc/api.ts`:
+
+```ts
+// SPDX-License-Identifier: MIT
+import { getAccessToken } from './auth';
+
+const BASE = 'https://www.googleapis.com/webmasters/v3';
+const INSPECT_URL = 'https://searchconsole.googleapis.com/v1/urlInspection/index:inspect';
+
+export type Dimension = 'query' | 'page' | 'country' | 'device' | 'date' | 'searchAppearance';
+
+export interface SearchAnalyticsRow {
+  keys: string[];
+  clicks: number;
+  impressions: number;
+  ctr: number;
+  position: number;
+}
+
+export function getSiteUrl(): string {
+  return process.env['GSC_SITE_URL'] ?? 'sc-domain:threadplane.ai';
+}
+
+async function authedFetch(url: string, init: RequestInit & { token: string }): Promise<unknown> {
+  const { token, ...rest } = init;
+  const response = await fetch(url, {
+    ...rest,
+    headers: { ...(rest.headers ?? {}), authorization: `Bearer ${token}`, 'content-type': 'application/json' },
+  });
+  if (!response.ok) {
+    throw new Error(`${url} → ${response.status} ${await response.text()}`);
+  }
+  return response.json();
+}
+
+/**
+ * Search Analytics. NOTE: `type` accepts only web|image|video|news|discover|
+ * googleNews. There is no AI Overviews / AI Mode type as of 2026-08.
+ */
+export async function querySearchAnalytics(options: {
+  startDate: string;
+  endDate: string;
+  dimensions: Dimension[];
+  rowLimit?: number;
+  startRow?: number;
+  type?: 'web' | 'image' | 'video' | 'news' | 'discover' | 'googleNews';
+}): Promise<SearchAnalyticsRow[]> {
+  const token = await getAccessToken();
+  const site = encodeURIComponent(getSiteUrl());
+  const rows: SearchAnalyticsRow[] = [];
+  let startRow = options.startRow ?? 0;
+  const rowLimit = options.rowLimit ?? 25000;
+
+  for (;;) {
+    const page = (await authedFetch(`${BASE}/sites/${site}/searchAnalytics/query`, {
+      token,
+      method: 'POST',
+      body: JSON.stringify({
+        startDate: options.startDate,
+        endDate: options.endDate,
+        dimensions: options.dimensions,
+        type: options.type ?? 'web',
+        rowLimit,
+        startRow,
+        dataState: 'all',
+      }),
+    })) as { rows?: SearchAnalyticsRow[] };
+    const batch = page.rows ?? [];
+    rows.push(...batch);
+    if (batch.length < rowLimit) break;
+    startRow += rowLimit;
+  }
+  return rows;
+}
+
+export async function listSitemaps(): Promise<unknown> {
+  const token = await getAccessToken();
+  return authedFetch(`${BASE}/sites/${encodeURIComponent(getSiteUrl())}/sitemaps`, {
+    token,
+    method: 'GET',
+  });
+}
+
+export interface InspectionResult {
+  url: string;
+  verdict: string;
+  coverageState: string;
+  lastCrawlTime: string | null;
+  robotsTxtState: string;
+  indexingState: string;
+  googleCanonical: string | null;
+  userCanonical: string | null;
+}
+
+export async function inspectUrl(inspectionUrl: string): Promise<InspectionResult> {
+  const token = await getAccessToken();
+  const raw = (await authedFetch(INSPECT_URL, {
+    token,
+    method: 'POST',
+    body: JSON.stringify({ inspectionUrl, siteUrl: getSiteUrl(), languageCode: 'en-US' }),
+  })) as {
+    inspectionResult?: {
+      indexStatusResult?: Record<string, string | undefined>;
+    };
+  };
+  const status = raw.inspectionResult?.indexStatusResult ?? {};
+  return {
+    url: inspectionUrl,
+    verdict: status['verdict'] ?? 'UNKNOWN',
+    coverageState: status['coverageState'] ?? 'UNKNOWN',
+    lastCrawlTime: status['lastCrawlTime'] ?? null,
+    robotsTxtState: status['robotsTxtState'] ?? 'UNKNOWN',
+    indexingState: status['indexingState'] ?? 'UNKNOWN',
+    googleCanonical: status['googleCanonical'] ?? null,
+    userCanonical: status['userCanonical'] ?? null,
+  };
+}
+```
+
+- [ ] **Step 2: Verify against the live property**
+
+```bash
+npx tsx -e "import('./apps/website/scripts/gsc/api.ts').then(async m => console.log(JSON.stringify(await m.listSitemaps(), null, 2)))"
+```
+
+Expected: JSON listing `https://threadplane.ai/sitemap.xml` with `lastSubmitted` and `contents`. A `403 User does not have sufficient permission` means step 4 of the README was skipped.
+
+- [ ] **Step 3: Commit**
+
+```bash
+git add apps/website/scripts/gsc/api.ts
+git commit -m "feat(website): typed search console api wrappers"
+```
+
+---
+
+### Task 3: Snapshot puller
+
+**Files:**
+- Create: `apps/website/scripts/gsc/pull.ts`
+
+- [ ] **Step 1: Write the puller**
+
+Create `apps/website/scripts/gsc/pull.ts`:
+
+```ts
+// SPDX-License-Identifier: MIT
+import fs from 'node:fs';
+import path from 'node:path';
+import { inspectUrl, listSitemaps, querySearchAnalytics } from './api';
+
+const OUT_DIR = path.join(process.cwd(), 'apps', 'website', '.gsc');
+
+function isoDaysAgo(days: number): string {
+  const date = new Date(Date.now() - days * 86_400_000);
+  return date.toISOString().slice(0, 10);
+}
+
+function write(name: string, value: unknown): void {
+  fs.mkdirSync(OUT_DIR, { recursive: true });
+  fs.writeFileSync(path.join(OUT_DIR, name), JSON.stringify(value, null, 2));
+  console.log(`wrote .gsc/${name}`);
+}
+
+async function sitemapUrls(): Promise<string[]> {
+  const response = await fetch('https://threadplane.ai/sitemap.xml');
+  const xml = await response.text();
+  return [...xml.matchAll(/<loc>([^<]+)<\/loc>/g)].map((m) => m[1]);
+}
+
+async function main(): Promise<void> {
+  // Search Analytics data lags ~2 days; end 3 days back for a stable window.
+  const endDate = isoDaysAgo(3);
+  const startDate = isoDaysAgo(93);
+
+  write('meta.json', { startDate, endDate, pulledAt: new Date().toISOString() });
+  write('queries.json', await querySearchAnalytics({ startDate, endDate, dimensions: ['query'] }));
+  write('pages.json', await querySearchAnalytics({ startDate, endDate, dimensions: ['page'] }));
+  write(
+    'query-page.json',
+    await querySearchAnalytics({ startDate, endDate, dimensions: ['query', 'page'] }),
+  );
+  write('dates.json', await querySearchAnalytics({ startDate, endDate, dimensions: ['date'] }));
+  write(
+    'discover.json',
+    await querySearchAnalytics({ startDate, endDate, dimensions: ['page'], type: 'discover' }),
+  );
+  write('sitemaps.json', await listSitemaps());
+
+  // URL Inspection is quota-limited (2000/day, 600/min). Serialize with a small delay.
+  const urls = await sitemapUrls();
+  const inspections = [];
+  for (const url of urls) {
+    inspections.push(await inspectUrl(url));
+    await new Promise((resolve) => setTimeout(resolve, 150));
+  }
+  write('inspections.json', inspections);
+}
+
+main().catch((error: unknown) => {
+  console.error(error);
+  process.exitCode = 1;
+});
+```
+
+- [ ] **Step 2: Run the pull**
+
+```bash
+npx tsx apps/website/scripts/gsc/pull.ts
+```
+
+Expected: eight `wrote .gsc/*.json` lines. The inspection loop takes ~30s for 140 URLs. If `discover.json` comes back empty, that is normal — Discover only reports once the property has Discover impressions.
+
+- [ ] **Step 3: Commit**
+
+```bash
+git add apps/website/scripts/gsc/pull.ts
+git commit -m "feat(website): search console snapshot puller"
+```
+
+---
+
+### Task 4: Analysis + report
+
+**Files:**
+- Create: `apps/website/scripts/gsc/analysis.ts`
+- Create: `apps/website/scripts/gsc/analysis.spec.ts`
+- Create: `apps/website/scripts/gsc/report.ts`
+- Modify: `apps/website/vite.config.mts`
+
+- [ ] **Step 1: Widen the vitest include so scripts are tested**
+
+In `apps/website/vite.config.mts`, change:
+
+```ts
+    include: ['src/**/*.spec.ts', 'src/**/*.spec.tsx'],
+```
+
+to:
+
+```ts
+    include: ['src/**/*.spec.ts', 'src/**/*.spec.tsx', 'scripts/**/*.spec.ts'],
+```
+
+- [ ] **Step 2: Write the failing test**
+
+Create `apps/website/scripts/gsc/analysis.spec.ts`:
+
+```ts
+import { describe, expect, it } from 'vitest';
+import { findStrikingDistance, findUnindexed, findZeroImpressionPages } from './analysis';
+
+const rows = [
+  { keys: ['angular langgraph chat'], clicks: 0, impressions: 400, ctr: 0, position: 11.2 },
+  { keys: ['threadplane'], clicks: 90, impressions: 100, ctr: 0.9, position: 1.1 },
+  { keys: ['obscure long tail'], clicks: 0, impressions: 3, ctr: 0, position: 42 },
+];
+
+describe('findStrikingDistance', () => {
+  it('returns rows ranking 5-20 with meaningful impressions, best opportunity first', () => {
+    const result = findStrikingDistance(rows, { minImpressions: 50 });
+    expect(result.map((r) => r.keys[0])).toEqual(['angular langgraph chat']);
+  });
+});
+
+describe('findZeroImpressionPages', () => {
+  it('lists sitemap URLs that earned no impressions in the window', () => {
+    const result = findZeroImpressionPages(
+      ['https://threadplane.ai/a', 'https://threadplane.ai/b'],
+      [{ keys: ['https://threadplane.ai/a'], clicks: 1, impressions: 10, ctr: 0.1, position: 5 }],
+    );
+    expect(result).toEqual(['https://threadplane.ai/b']);
+  });
+});
+
+describe('findUnindexed', () => {
+  it('flags inspections whose verdict is not PASS', () => {
+    const result = findUnindexed([
+      { url: 'https://threadplane.ai/a', verdict: 'PASS', coverageState: 'Submitted and indexed', lastCrawlTime: null, robotsTxtState: 'ALLOWED', indexingState: 'INDEXING_ALLOWED', googleCanonical: null, userCanonical: null },
+      { url: 'https://threadplane.ai/b', verdict: 'NEUTRAL', coverageState: 'Discovered - currently not indexed', lastCrawlTime: null, robotsTxtState: 'ALLOWED', indexingState: 'INDEXING_ALLOWED', googleCanonical: null, userCanonical: null },
+    ]);
+    expect(result.map((r) => r.url)).toEqual(['https://threadplane.ai/b']);
+  });
+});
+```
+
+- [ ] **Step 3: Run it and confirm it fails**
+
+```bash
+npx nx test website
+```
+
+Expected: FAIL — `Failed to resolve import "./analysis"`.
+
+- [ ] **Step 4: Write the analysis module**
+
+Create `apps/website/scripts/gsc/analysis.ts`:
+
+```ts
+// SPDX-License-Identifier: MIT
+import type { InspectionResult, SearchAnalyticsRow } from './api';
+
+/** Queries ranking just off page one — the cheapest ranking wins available. */
+export function findStrikingDistance(
+  rows: SearchAnalyticsRow[],
+  options: { minImpressions: number },
+): SearchAnalyticsRow[] {
+  return rows
+    .filter(
+      (row) =>
+        row.position >= 5 &&
+        row.position <= 20 &&
+        row.impressions >= options.minImpressions,
+    )
+    .sort((a, b) => b.impressions - a.impressions);
+}
+
+/** Sitemap URLs Google never showed for anything in the window. */
+export function findZeroImpressionPages(
+  sitemapUrls: string[],
+  pageRows: SearchAnalyticsRow[],
+): string[] {
+  const seen = new Set(pageRows.map((row) => row.keys[0].replace(/\/$/, '')));
+  return sitemapUrls.filter((url) => !seen.has(url.replace(/\/$/, '')));
+}
+
+/** Inspections that are not cleanly indexed. */
+export function findUnindexed(inspections: InspectionResult[]): InspectionResult[] {
+  return inspections.filter((inspection) => inspection.verdict !== 'PASS');
+}
+
+/** Pages Google canonicalized somewhere other than where we asked — duplicate-content smell. */
+export function findCanonicalMismatches(inspections: InspectionResult[]): InspectionResult[] {
+  return inspections.filter(
+    (inspection) =>
+      inspection.googleCanonical !== null &&
+      inspection.userCanonical !== null &&
+      inspection.googleCanonical !== inspection.userCanonical,
+  );
+}
+
+/** Queries with strong impressions but a CTR well below the position-typical rate. */
+export function findWeakCtr(
+  rows: SearchAnalyticsRow[],
+  options: { minImpressions: number; maxCtr: number },
+): SearchAnalyticsRow[] {
+  return rows
+    .filter(
+      (row) =>
+        row.impressions >= options.minImpressions &&
+        row.position <= 10 &&
+        row.ctr < options.maxCtr,
+    )
+    .sort((a, b) => b.impressions - a.impressions);
+}
+```
+
+- [ ] **Step 5: Run the tests and confirm they pass**
+
+```bash
+npx nx test website
+```
+
+Expected: PASS.
+
+- [ ] **Step 6: Write the report generator**
+
+Create `apps/website/scripts/gsc/report.ts`:
+
+```ts
+// SPDX-License-Identifier: MIT
+import fs from 'node:fs';
+import path from 'node:path';
+import type { InspectionResult, SearchAnalyticsRow } from './api';
+import {
+  findCanonicalMismatches,
+  findStrikingDistance,
+  findUnindexed,
+  findWeakCtr,
+  findZeroImpressionPages,
+} from './analysis';
+
+const DIR = path.join(process.cwd(), 'apps', 'website', '.gsc');
+
+function read<T>(name: string): T {
+  return JSON.parse(fs.readFileSync(path.join(DIR, name), 'utf8')) as T;
+}
+
+function table(rows: SearchAnalyticsRow[], headers: string[], limit = 30): string {
+  const head = `| ${headers.join(' | ')} |\n| ${headers.map(() => '---').join(' | ')} |`;
+  const body = rows
+    .slice(0, limit)
+    .map(
+      (row) =>
+        `| ${row.keys.join(' | ')} | ${row.clicks} | ${row.impressions} | ${(row.ctr * 100).toFixed(1)}% | ${row.position.toFixed(1)} |`,
+    )
+    .join('\n');
+  return `${head}\n${body}`;
+}
+
+function main(): void {
+  const meta = read<{ startDate: string; endDate: string }>('meta.json');
+  const queries = read<SearchAnalyticsRow[]>('queries.json');
+  const pages = read<SearchAnalyticsRow[]>('pages.json');
+  const inspections = read<InspectionResult[]>('inspections.json');
+  const sitemapUrls = inspections.map((inspection) => inspection.url);
+
+  const totals = queries.reduce(
+    (acc, row) => ({ clicks: acc.clicks + row.clicks, impressions: acc.impressions + row.impressions }),
+    { clicks: 0, impressions: 0 },
+  );
+
+  const unindexed = findUnindexed(inspections);
+  const mismatches = findCanonicalMismatches(inspections);
+  const orphans = findZeroImpressionPages(sitemapUrls, pages);
+
+  const report = [
+    `# threadplane.ai — Search Console report`,
+    ``,
+    `Window: ${meta.startDate} → ${meta.endDate}. Total clicks ${totals.clicks}, impressions ${totals.impressions}.`,
+    ``,
+    `> Google's AI Overviews / AI Mode impressions are NOT included — that report is UI-only.`,
+    `> See docs/gtm/ai-search-measurement.md.`,
+    ``,
+    `## Index health`,
+    ``,
+    `- Sitemap URLs inspected: ${inspections.length}`,
+    `- Not cleanly indexed: ${unindexed.length}`,
+    `- Google canonical ≠ our canonical: ${mismatches.length}`,
+    `- Zero-impression pages in window: ${orphans.length}`,
+    ``,
+    `### Not indexed`,
+    ``,
+    unindexed.length
+      ? unindexed.map((i) => `- ${i.url} — ${i.coverageState}`).join('\n')
+      : '_none_',
+    ``,
+    `### Canonical mismatches`,
+    ``,
+    mismatches.length
+      ? mismatches.map((i) => `- ${i.url} → Google chose ${i.googleCanonical}`).join('\n')
+      : '_none_',
+    ``,
+    `### Zero-impression pages`,
+    ``,
+    orphans.length ? orphans.map((url) => `- ${url}`).join('\n') : '_none_',
+    ``,
+    `## Striking distance (position 5–20, ≥50 impressions)`,
+    ``,
+    table(findStrikingDistance(queries, { minImpressions: 50 }), ['Query', 'Clicks', 'Impr', 'CTR', 'Pos']),
+    ``,
+    `## Weak CTR on page one (≥100 impressions, CTR < 2%)`,
+    ``,
+    `Title/description rewrite candidates.`,
+    ``,
+    table(findWeakCtr(queries, { minImpressions: 100, maxCtr: 0.02 }), ['Query', 'Clicks', 'Impr', 'CTR', 'Pos']),
+    ``,
+    `## Top pages`,
+    ``,
+    table(pages.slice(0, 30), ['Page', 'Clicks', 'Impr', 'CTR', 'Pos']),
+    ``,
+  ].join('\n');
+
+  fs.writeFileSync(path.join(DIR, 'report.md'), report);
+  console.log('wrote .gsc/report.md');
+}
+
+main();
+```
+
+- [ ] **Step 7: Generate and read the report**
+
+```bash
+npx tsx apps/website/scripts/gsc/report.ts && cat apps/website/.gsc/report.md
+```
+
+Expected: `wrote .gsc/report.md`, followed by the rendered report. **Read it before continuing** — the "Not indexed", "Canonical mismatches", and "Zero-impression pages" sections determine whether extra remediation tasks are needed beyond Phase 2.
+
+- [ ] **Step 8: Add npm scripts**
+
+In the root `package.json` `scripts` block, add:
+
+```json
+    "gsc:pull": "npx tsx apps/website/scripts/gsc/pull.ts",
+    "gsc:report": "npx tsx apps/website/scripts/gsc/report.ts",
+```
+
+- [ ] **Step 9: Commit**
+
+```bash
+git add apps/website/scripts/gsc/analysis.ts apps/website/scripts/gsc/analysis.spec.ts apps/website/scripts/gsc/report.ts apps/website/vite.config.mts package.json
+git commit -m "feat(website): search console analysis report"
+```
+
+---
+
+## Phase 2 — Technical structure
+
+### Task 5: Sitemap `lastmod`
+
+Google ignores `changefreq` and `priority` entirely but does use `lastmod` when it is honest. Blog posts have real dates; docs and static routes use the source file's mtime.
+
+**Files:**
+- Modify: `apps/website/src/lib/site-metadata.ts`
+- Modify: `apps/website/src/app/sitemap.ts`
+- Modify: `apps/website/src/lib/site-metadata.spec.ts`
+
+- [ ] **Step 1: Write the failing test**
+
+Append to `apps/website/src/lib/site-metadata.spec.ts`:
+
+```ts
+describe('getSitemapEntries', () => {
+  it('emits a lastModified date for every route', async () => {
+    const { getSitemapEntries } = await import('./site-metadata');
+    const entries = getSitemapEntries();
+    expect(entries.length).toBeGreaterThan(100);
+    for (const entry of entries) {
+      expect(entry.lastModified).toBeInstanceOf(Date);
+      expect(Number.isNaN(entry.lastModified.getTime())).toBe(false);
+    }
+  });
+
+  it('uses the post date as lastModified for blog routes', async () => {
+    const { getSitemapEntries } = await import('./site-metadata');
+    const entry = getSitemapEntries().find((e) => e.route === '/blog/angular-chat-app-tutorial-with-ag-ui');
+    expect(entry?.lastModified.toISOString().slice(0, 10)).toBe('2026-08-13');
+  });
+});
+```
+
+- [ ] **Step 2: Run it and confirm it fails**
+
+```bash
+npx nx test website
+```
+
+Expected: FAIL — `getSitemapEntries is not a function`.
+
+- [ ] **Step 3: Implement `getSitemapEntries`**
+
+In `apps/website/src/lib/site-metadata.ts`, add these imports at the top:
+
+```ts
+import fs from 'node:fs';
+import path from 'node:path';
+```
+
+and append:
+
+```ts
+export interface SitemapEntry {
+  route: string;
+  lastModified: Date;
+}
+
+function fileModifiedTime(relativePath: string): Date {
+  const candidates = [
+    path.join(process.cwd(), 'apps', 'website', relativePath),
+    path.join(process.cwd(), relativePath),
+  ];
+  for (const candidate of candidates) {
+    if (fs.existsSync(candidate)) return fs.statSync(candidate).mtime;
+  }
+  return new Date();
+}
+
+export function getSitemapEntries(): SitemapEntry[] {
+  const blogDates = new Map(getAllPosts().map((post) => [`/blog/${post.slug}`, new Date(post.frontmatter.date)]));
+
+  return getSitemapRoutes().map((route) => {
+    const blogDate = blogDates.get(route);
+    if (blogDate) return { route, lastModified: blogDate };
+
+    if (route.startsWith('/docs/')) {
+      const [, , library, section, slug] = route.split('/');
+      return {
+        route,
+        lastModified: fileModifiedTime(path.join('content', 'docs', library, section, `${slug}.mdx`)),
+      };
+    }
+
+    return { route, lastModified: fileModifiedTime(path.join('src', 'app', route === '/' ? 'page.tsx' : `${route.replace(/^\//, '')}/page.tsx`)) };
+  });
+}
+```
+
+- [ ] **Step 4: Rewrite the sitemap route**
+
+Replace the body of `apps/website/src/app/sitemap.ts` with:
+
+```ts
+import type { MetadataRoute } from 'next';
+import { getCanonicalUrl, getSitemapEntries } from '../lib/site-metadata';
+
+export default function sitemap(): MetadataRoute.Sitemap {
+  return getSitemapEntries().map((entry) => ({
+    url: getCanonicalUrl(entry.route),
+    lastModified: entry.lastModified,
+  }));
+}
+```
+
+- [ ] **Step 5: Run the tests and confirm they pass**
+
+```bash
+npx nx test website
+```
+
+Expected: PASS.
+
+- [ ] **Step 6: Verify the built sitemap**
+
+```bash
+npx nx build website && grep -m3 -A3 "<loc>" dist/apps/website/.next/server/app/sitemap.xml.body 2>/dev/null || npx nx serve website
+```
+
+If the build artifact path differs, serve locally and `curl -s http://localhost:3000/sitemap.xml | head -20`. Expected: each `<url>` now carries a `<lastmod>` and no longer carries `<changefreq>`/`<priority>`.
+
+- [ ] **Step 7: Commit**
+
+```bash
+git add apps/website/src/lib/site-metadata.ts apps/website/src/lib/site-metadata.spec.ts apps/website/src/app/sitemap.ts
+git commit -m "feat(website): emit honest lastmod in sitemap"
+```
+
+---
+
+### Task 6: Article metadata + brand-name consistency
+
+`ThreadPlane` vs `Threadplane` splits the brand entity; `publishedTime`/`author` are freshness and E-E-A-T signals that AI surfaces attribute with.
+
+**Files:**
+- Modify: `apps/website/src/lib/site-metadata.ts`
+- Modify: `apps/website/src/lib/site-metadata.spec.ts`
+- Modify: `apps/website/src/app/blog/[slug]/page.tsx`
+- Modify: `apps/website/src/lib/docs.ts`
+
+- [ ] **Step 1: Write the failing test**
+
+Append to `apps/website/src/lib/site-metadata.spec.ts`:
+
+```ts
+describe('createPageMetadata article fields', () => {
+  it('emits openGraph article dates, authors, and tags', () => {
+    const metadata = createPageMetadata({
+      title: 'Post — Threadplane',
+      description: 'A post.',
+      pathname: '/blog/post',
+      type: 'article',
+      article: {
+        publishedTime: '2026-08-13',
+        modifiedTime: '2026-08-14',
+        authors: ['Brian Love'],
+        tags: ['angular', 'ag-ui'],
+      },
+    });
+    const openGraph = metadata.openGraph as Record<string, unknown>;
+    expect(openGraph['publishedTime']).toBe('2026-08-13');
+    expect(openGraph['modifiedTime']).toBe('2026-08-14');
+    expect(openGraph['authors']).toEqual(['Brian Love']);
+    expect(openGraph['tags']).toEqual(['angular', 'ag-ui']);
+  });
+
+  it('accepts a page-specific social image', () => {
+    const metadata = createPageMetadata({
+      title: 'Post — Threadplane',
+      description: 'A post.',
+      pathname: '/blog/post',
+      image: '/blog/post/opengraph-image',
+    });
+    const openGraph = metadata.openGraph as { images: string[] };
+    expect(openGraph.images).toEqual(['/blog/post/opengraph-image']);
+  });
+});
+
+describe('brand name', () => {
+  it('uses one canonical spelling', () => {
+    expect(SITE_NAME).toBe('Threadplane');
+  });
+});
+```
+
+Add `SITE_NAME` to the existing import list at the top of that spec file.
+
+- [ ] **Step 2: Run it and confirm it fails**
+
+```bash
+npx nx test website
+```
+
+Expected: FAIL — `publishedTime` is `undefined`.
+
+- [ ] **Step 3: Extend `createPageMetadata`**
+
+In `apps/website/src/lib/site-metadata.ts`, replace the `createPageMetadata` function with:
+
+```ts
+export interface ArticleMetadata {
+  publishedTime: string;
+  modifiedTime?: string;
+  authors?: string[];
+  tags?: string[];
+}
+
+export function createPageMetadata({
+  title,
+  description,
+  pathname,
+  type = 'article',
+  image = DEFAULT_SOCIAL_IMAGE,
+  article,
+}: {
+  title: string;
+  description: string;
+  pathname: string;
+  type?: 'article' | 'website';
+  image?: string;
+  article?: ArticleMetadata;
+}): Metadata {
+  const canonicalPath = getCanonicalPath(pathname);
+
+  return {
+    title,
+    description,
+    alternates: { canonical: canonicalPath },
+    openGraph: {
+      title,
+      description,
+      url: canonicalPath,
+      siteName: SITE_NAME,
+      type,
+      images: [image],
+      ...(article
+        ? {
+            publishedTime: article.publishedTime,
+            modifiedTime: article.modifiedTime ?? article.publishedTime,
+            authors: article.authors,
+            tags: article.tags,
+          }
+        : {}),
+    },
+    twitter: {
+      card: 'summary_large_image',
+      title,
+      description,
+      images: [image],
+    },
+  };
+}
+```
+
+- [ ] **Step 4: Wire the blog route**
+
+In `apps/website/src/app/blog/[slug]/page.tsx`, replace the body of `generateMetadata` with:
+
+```ts
+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 — Threadplane' };
+  }
+  const author = getAuthor(post.frontmatter.author);
+  return createPageMetadata({
+    title: `${post.frontmatter.title} — Threadplane`,
+    description: post.frontmatter.description,
+    pathname: `/blog/${post.slug}`,
+    type: 'article',
+    image: `/blog/${post.slug}/opengraph-image`,
+    article: {
+      publishedTime: post.frontmatter.date,
+      authors: [author.name],
+      tags: post.frontmatter.tags,
+    },
+  });
+}
+```
+
+- [ ] **Step 5: Unify the docs title separator**
+
+In `apps/website/src/lib/docs.ts:89`, change:
+
+```ts
+  const title = `${doc.title} - ${libraryTitle} Docs - Threadplane`;
+```
+
+to:
+
+```ts
+  const title = `${doc.title} — ${libraryTitle} Docs — Threadplane`;
+```
+
+- [ ] **Step 6: Sweep the remaining mis-cased brand names**
+
+```bash
+grep -rn "ThreadPlane" apps/website/src apps/website/content | grep -v node_modules
+```
+
+Fix every hit to `Threadplane` (the brand is one word, capital T only). Then confirm:
+
+```bash
+grep -rn "ThreadPlane" apps/website/src apps/website/content | grep -v node_modules | wc -l
+```
+
+Expected: `0`.
+
+- [ ] **Step 7: Run the tests and confirm they pass**
+
+```bash
+npx nx test website
+```
+
+Expected: PASS.
+
+- [ ] **Step 8: Commit**
+
+```bash
+git add apps/website/src apps/website/content
+git commit -m "feat(website): article metadata + canonical brand spelling"
+```
+
+---
+
+### Task 7: JSON-LD structured data
+
+**Files:**
+- Create: `apps/website/src/lib/structured-data.ts`
+- Create: `apps/website/src/lib/structured-data.spec.ts`
+- Create: `apps/website/src/components/shared/JsonLd.tsx`
+
+- [ ] **Step 1: Write the failing test**
+
+Create `apps/website/src/lib/structured-data.spec.ts`:
+
+```ts
+import { describe, expect, it } from 'vitest';
+import {
+  breadcrumbJsonLd,
+  organizationJsonLd,
+  softwareSourceCodeJsonLd,
+  techArticleJsonLd,
+  websiteJsonLd,
+  blogPostingJsonLd,
+} from './structured-data';
+
+describe('organizationJsonLd', () => {
+  it('describes Threadplane with an absolute url and logo', () => {
+    const data = organizationJsonLd();
+    expect(data['@type']).toBe('Organization');
+    expect(data['name']).toBe('Threadplane');
+    expect(String(data['url'])).toBe('https://threadplane.ai/');
+  });
+});
+
+describe('websiteJsonLd', () => {
+  it('is a WebSite node pointing at the origin', () => {
+    expect(websiteJsonLd()['@type']).toBe('WebSite');
+  });
+});
+
+describe('blogPostingJsonLd', () => {
+  it('carries headline, dates, author, and absolute urls', () => {
+    const data = blogPostingJsonLd({
+      title: 'A Post',
+      description: 'About things.',
+      slug: 'a-post',
+      datePublished: '2026-08-13',
+      authorName: 'Brian Love',
+      tags: ['angular'],
+    });
+    expect(data['@type']).toBe('BlogPosting');
+    expect(data['headline']).toBe('A Post');
+    expect(data['datePublished']).toBe('2026-08-13');
+    expect(data['dateModified']).toBe('2026-08-13');
+    expect((data['author'] as Record<string, unknown>)['name']).toBe('Brian Love');
+    expect(String(data['url'])).toBe('https://threadplane.ai/blog/a-post');
+  });
+});
+
+describe('techArticleJsonLd', () => {
+  it('describes a docs page', () => {
+    const data = techArticleJsonLd({
+      title: 'Installation',
+      description: 'Install it.',
+      pathname: '/docs/chat/getting-started/installation',
+    });
+    expect(data['@type']).toBe('TechArticle');
+    expect(String(data['url'])).toBe('https://threadplane.ai/docs/chat/getting-started/installation');
+  });
+});
+
+describe('breadcrumbJsonLd', () => {
+  it('numbers positions from 1 and resolves absolute urls', () => {
+    const data = breadcrumbJsonLd([
+      { name: 'Docs', pathname: '/docs' },
+      { name: 'Chat', pathname: '/docs/chat' },
+    ]);
+    const items = data['itemListElement'] as Record<string, unknown>[];
+    expect(items).toHaveLength(2);
+    expect(items[0]['position']).toBe(1);
+    expect(String(items[1]['item'])).toBe('https://threadplane.ai/docs/chat');
+  });
+});
+
+describe('softwareSourceCodeJsonLd', () => {
+  it('marks Threadplane as an Angular TypeScript library', () => {
+    const data = softwareSourceCodeJsonLd();
+    expect(data['@type']).toBe('SoftwareSourceCode');
+    expect(data['programmingLanguage']).toBe('TypeScript');
+  });
+});
+```
+
+- [ ] **Step 2: Run it and confirm it fails**
+
+```bash
+npx nx test website
+```
+
+Expected: FAIL — `Failed to resolve import "./structured-data"`.
+
+- [ ] **Step 3: Implement the builders**
+
+Create `apps/website/src/lib/structured-data.ts`:
+
+```ts
+// SPDX-License-Identifier: MIT
+import { getCanonicalUrl, SITE_NAME } from './site-metadata';
+
+export type JsonLdNode = Record<string, unknown>;
+
+const ORGANIZATION_ID = getCanonicalUrl('/') + '#organization';
+
+export function organizationJsonLd(): JsonLdNode {
+  return {
+    '@context': 'https://schema.org',
+    '@type': 'Organization',
+    '@id': ORGANIZATION_ID,
+    name: SITE_NAME,
+    url: getCanonicalUrl('/'),
+    logo: getCanonicalUrl('/logos/threadplane-mark.svg'),
+    description:
+      'Threadplane builds the Angular UI layer for production agent applications on LangGraph and AG-UI-compatible runtimes.',
+    sameAs: ['https://github.com/blove/angular-agent-framework', 'https://www.npmjs.com/org/threadplane'],
+  };
+}
+
+export function websiteJsonLd(): JsonLdNode {
+  return {
+    '@context': 'https://schema.org',
+    '@type': 'WebSite',
+    '@id': getCanonicalUrl('/') + '#website',
+    name: SITE_NAME,
+    url: getCanonicalUrl('/'),
+    publisher: { '@id': ORGANIZATION_ID },
+  };
+}
+
+export function softwareSourceCodeJsonLd(): JsonLdNode {
+  return {
+    '@context': 'https://schema.org',
+    '@type': 'SoftwareSourceCode',
+    name: '@threadplane/chat',
+    description:
+      'Signal-native Angular chat UI primitives bound to a runtime-neutral Agent contract, with adapters for LangGraph and AG-UI.',
+    programmingLanguage: 'TypeScript',
+    runtimePlatform: 'Angular',
+    codeRepository: 'https://github.com/blove/angular-agent-framework',
+    author: { '@id': ORGANIZATION_ID },
+    license: 'https://threadplane.ai/docs/licensing',
+  };
+}
+
+export function blogPostingJsonLd(post: {
+  title: string;
+  description: string;
+  slug: string;
+  datePublished: string;
+  dateModified?: string;
+  authorName: string;
+  tags?: string[];
+}): JsonLdNode {
+  return {
+    '@context': 'https://schema.org',
+    '@type': 'BlogPosting',
+    headline: post.title,
+    description: post.description,
+    url: getCanonicalUrl(`/blog/${post.slug}`),
+    mainEntityOfPage: getCanonicalUrl(`/blog/${post.slug}`),
+    datePublished: post.datePublished,
+    dateModified: post.dateModified ?? post.datePublished,
+    image: getCanonicalUrl(`/blog/${post.slug}/opengraph-image`),
+    keywords: post.tags,
+    author: { '@type': 'Person', name: post.authorName, url: getCanonicalUrl('/about') },
+    publisher: { '@id': ORGANIZATION_ID },
+  };
+}
+
+export function techArticleJsonLd(doc: {
+  title: string;
+  description: string;
+  pathname: string;
+  dateModified?: string;
+}): JsonLdNode {
+  return {
+    '@context': 'https://schema.org',
+    '@type': 'TechArticle',
+    headline: doc.title,
+    description: doc.description,
+    url: getCanonicalUrl(doc.pathname),
+    mainEntityOfPage: getCanonicalUrl(doc.pathname),
+    ...(doc.dateModified ? { dateModified: doc.dateModified } : {}),
+    author: { '@id': ORGANIZATION_ID },
+    publisher: { '@id': ORGANIZATION_ID },
+    proficiencyLevel: 'Expert',
+  };
+}
+
+export function breadcrumbJsonLd(crumbs: { name: string; pathname: string }[]): JsonLdNode {
+  return {
+    '@context': 'https://schema.org',
+    '@type': 'BreadcrumbList',
+    itemListElement: crumbs.map((crumb, index) => ({
+      '@type': 'ListItem',
+      position: index + 1,
+      name: crumb.name,
+      item: getCanonicalUrl(crumb.pathname),
+    })),
+  };
+}
+
+export function faqJsonLd(entries: { question: string; answer: string }[]): JsonLdNode {
+  return {
+    '@context': 'https://schema.org',
+    '@type': 'FAQPage',
+    mainEntity: entries.map((entry) => ({
+      '@type': 'Question',
+      name: entry.question,
+      acceptedAnswer: { '@type': 'Answer', text: entry.answer },
+    })),
+  };
+}
+```
+
+- [ ] **Step 4: Run the tests and confirm they pass**
+
+```bash
+npx nx test website
+```
+
+Expected: PASS. If `organizationJsonLd` fails on the logo path, run `ls apps/website/public/logos` and use the actual filename.
+
+- [ ] **Step 5: Write the render component**
+
+Create `apps/website/src/components/shared/JsonLd.tsx`:
+
+```tsx
+// SPDX-License-Identifier: MIT
+import type { JsonLdNode } from '../../lib/structured-data';
+
+/**
+ * Renders schema.org JSON-LD. Content is generated from our own data, never
+ * from user input, so `dangerouslySetInnerHTML` is safe here; `<` is still
+ * escaped to keep a stray value from closing the script tag.
+ */
+export function JsonLd({ data }: { data: JsonLdNode | JsonLdNode[] }) {
+  const json = JSON.stringify(data).replace(/</g, '\\u003c');
+  return <script type="application/ld+json" dangerouslySetInnerHTML={{ __html: json }} />;
+}
+```
+
+- [ ] **Step 6: Commit**
+
+```bash
+git add apps/website/src/lib/structured-data.ts apps/website/src/lib/structured-data.spec.ts apps/website/src/components/shared/JsonLd.tsx
+git commit -m "feat(website): schema.org json-ld builders"
+```
+
+---
+
+### Task 8: Mount JSON-LD on layout, blog, and docs
+
+**Files:**
+- Modify: `apps/website/src/app/layout.tsx`
+- Modify: `apps/website/src/app/blog/[slug]/page.tsx`
+- Modify: `apps/website/src/app/docs/[library]/[section]/[slug]/page.tsx`
+
+- [ ] **Step 1: Add sitewide entity nodes**
+
+In `apps/website/src/app/layout.tsx`, add imports:
+
+```tsx
+import { JsonLd } from '../components/shared/JsonLd';
+import { organizationJsonLd, softwareSourceCodeJsonLd, websiteJsonLd } from '../lib/structured-data';
+```
+
+and inside `<body>`, as the first child:
+
+```tsx
+        <JsonLd data={[organizationJsonLd(), websiteJsonLd(), softwareSourceCodeJsonLd()]} />
+```
+
+- [ ] **Step 2: Add BlogPosting + breadcrumbs to blog posts**
+
+In `apps/website/src/app/blog/[slug]/page.tsx`, add imports:
+
+```tsx
+import { JsonLd } from '../../../components/shared/JsonLd';
+import { blogPostingJsonLd, breadcrumbJsonLd } from '../../../lib/structured-data';
+```
+
+and inside `BlogPostPage`, as the first child of the outermost `<div>`:
+
+```tsx
+      <JsonLd
+        data={[
+          blogPostingJsonLd({
+            title: post.frontmatter.title,
+            description: post.frontmatter.description,
+            slug: post.slug,
+            datePublished: post.frontmatter.date,
+            authorName: author.name,
+            tags: post.frontmatter.tags,
+          }),
+          breadcrumbJsonLd([
+            { name: 'Blog', pathname: '/blog' },
+            { name: post.frontmatter.title, pathname: `/blog/${post.slug}` },
+          ]),
+        ]}
+      />
+```
+
+- [ ] **Step 3: Add TechArticle + breadcrumbs to docs pages**
+
+In `apps/website/src/app/docs/[library]/[section]/[slug]/page.tsx`, add imports:
+
+```tsx
+import { JsonLd } from '../../../../../components/shared/JsonLd';
+import { breadcrumbJsonLd, techArticleJsonLd } from '../../../../../lib/structured-data';
+```
+
+and inside `DocsPage`, after the `if (!doc) notFound();` guard, as the first child of the returned outermost `<div>`:
+
+```tsx
+      <JsonLd
+        data={[
+          techArticleJsonLd({
+            title: doc.title,
+            description: doc.description ?? libConfig.description,
+            pathname: `/docs/${library}/${section}/${slug}`,
+          }),
+          breadcrumbJsonLd([
+            { name: 'Docs', pathname: '/docs' },
+            { name: libConfig.title, pathname: `/docs/${library}` },
+            { name: doc.title, pathname: `/docs/${library}/${section}/${slug}` },
+          ]),
+        ]}
+      />
+```
+
+If `doc` has no `description` field, use `getDocDescription(doc.content, libConfig.description)` and import it from `../../../../../lib/docs`.
+
+- [ ] **Step 4: Build and verify the emitted JSON-LD**
+
+```bash
+npx nx build website
+```
+
+Expected: build succeeds. Then serve and check:
+
+```bash
+npx nx serve website
+```
+
+In a second shell:
+
+```bash
+curl -s http://localhost:3000/blog/angular-chat-app-tutorial-with-ag-ui | grep -c 'application/ld+json'
+```
+
+Expected: `2` (layout node array + page node array). Then validate the payload:
+
+```bash
+curl -s http://localhost:3000/blog/angular-chat-app-tutorial-with-ag-ui | python3 -c "import sys,re,json;[json.loads(m) for m in re.findall(r'ld\+json\"[^>]*>(.*?)</script>', sys.stdin.read(), re.S)] and print('valid json-ld')"
+```
+
+Expected: `valid json-ld`.
+
+- [ ] **Step 5: Validate against Google**
+
+Paste the deployed URL into https://search.google.com/test/rich-results after the PR merges and confirm zero errors. Record the result in the PR description.
+
+- [ ] **Step 6: Commit**
+
+```bash
+git add apps/website/src/app
+git commit -m "feat(website): mount json-ld on layout, blog, and docs"
+```
+
+---
+
+### Task 9: Per-post OG images
+
+**Files:**
+- Create: `apps/website/src/app/blog/[slug]/opengraph-image.tsx`
+
+- [ ] **Step 1: Read the existing generator for style parity**
+
+```bash
+cat apps/website/src/app/opengraph-image.tsx
+```
+
+Match its `size`, `contentType`, font loading, and color usage in the next step rather than inventing a new look.
+
+- [ ] **Step 2: Write the per-post generator**
+
+Create `apps/website/src/app/blog/[slug]/opengraph-image.tsx`:
+
+```tsx
+// SPDX-License-Identifier: MIT
+import { ImageResponse } from 'next/og';
+import { getAllPosts, getPostBySlug } from '../../../lib/blog';
+import { getAuthor } from '../../../lib/blog-authors';
+
+export const size = { width: 1200, height: 630 };
+export const contentType = 'image/png';
+export const alt = 'Threadplane blog post';
+
+export function generateStaticParams() {
+  return getAllPosts().map((post) => ({ slug: post.slug }));
+}
+
+export default async function OpengraphImage({ params }: { params: Promise<{ slug: string }> }) {
+  const { slug } = await params;
+  const post = getPostBySlug(slug);
+  const title = post?.frontmatter.title ?? 'Threadplane';
+  const author = post ? getAuthor(post.frontmatter.author).name : 'Threadplane';
+
+  return new ImageResponse(
+    (
+      <div
+        style={{
+          width: '100%',
+          height: '100%',
+          display: 'flex',
+          flexDirection: 'column',
+          justifyContent: 'space-between',
+          background: '#0B0D12',
+          color: '#F5F7FA',
+          padding: 80,
+          fontFamily: 'sans-serif',
+        }}
+      >
+        <div style={{ fontSize: 28, letterSpacing: 2, color: '#8FA3BF', textTransform: 'uppercase' }}>
+          Threadplane · Blog
+        </div>
+        <div style={{ fontSize: 68, lineHeight: 1.1, fontWeight: 700, maxWidth: 980 }}>{title}</div>
+        <div style={{ fontSize: 30, color: '#8FA3BF' }}>{author} · threadplane.ai</div>
+      </div>
+    ),
+    size,
+  );
+}
+```
+
+- [ ] **Step 3: Verify the image renders**
+
+```bash
+npx nx serve website
+```
+
+In a second shell:
+
+```bash
+curl -s -o /tmp/og.png -w "%{http_code} %{content_type} %{size_download}\n" "http://localhost:3000/blog/angular-chat-app-tutorial-with-ag-ui/opengraph-image"
+```
+
+Expected: `200 image/png` with a size over 10000 bytes. Open `/tmp/og.png` and confirm the title is not clipped for the longest post title (`Build Fullstack Agentic Angular Apps Using AG-UI`).
+
+- [ ] **Step 4: Commit**
+
+```bash
+git add "apps/website/src/app/blog/[slug]/opengraph-image.tsx"
+git commit -m "feat(website): per-post opengraph images"
+```
+
+---
+
+### Task 10: Clean heading text + agent-friendly markup
+
+Right now every docs H2 extracts as `#Prerequisites`. That glyph rides along into snippets, TOCs, and any model reading the DOM. Google's agent-friendly guidance is the same checklist as accessibility: semantic elements, meaningful link text, clean headings.
+
+**Files:**
+- Modify: `apps/website/src/components/docs/MdxRenderer.tsx`
+- Modify: `apps/website/src/app/global.css`
+
+- [ ] **Step 1: Confirm the defect on the live site**
+
+```bash
+curl -s https://threadplane.ai/docs/chat/getting-started/installation | grep -o '<h2[^>]*>.\{0,60\}' | head -3
+```
+
+Expected: heading markup where the `#` anchor precedes the text.
+
+- [ ] **Step 2: Move the anchor after the text and hide it from assistive tech and extraction**
+
+In `apps/website/src/components/docs/MdxRenderer.tsx`, at both line 37 and line 43, change the anchor so it renders **after** the heading children and carries `aria-hidden`:
+
+```tsx
+      {id ? (
+        <a href={`#${id}`} aria-hidden="true" tabIndex={-1} className="heading-anchor">
+          #
+        </a>
+      ) : null}
+```
+
+Ensure the `{children}` expression precedes this block in both heading components.
+
+- [ ] **Step 3: Keep the anchor reachable without polluting the text**
+
+Append to `apps/website/src/app/global.css`:
+
+```css
+.heading-anchor {
+  margin-left: 0.35rem;
+  opacity: 0;
+  text-decoration: none;
+  transition: opacity 120ms ease-in-out;
+}
+
+h1:hover > .heading-anchor,
+h2:hover > .heading-anchor,
+h3:hover > .heading-anchor,
+h4:hover > .heading-anchor {
+  opacity: 0.5;
+}
+```
+
+- [ ] **Step 4: Verify the extracted heading text is clean**
+
+```bash
+npx nx serve website
+```
+
+In a second shell:
+
+```bash
+curl -s http://localhost:3000/docs/chat/getting-started/installation | python3 -c "
+import sys, re
+html = sys.stdin.read()
+for level, text in re.findall(r'<h([1-3])[^>]*>(.*?)</h\1>', html, re.S)[:8]:
+    print(level, re.sub(r'<[^>]+>', '', text).strip())
+"
+```
+
+Expected: `2 Prerequisites`, `2 1. Install the packages`, … with no leading `#`.
+
+- [ ] **Step 5: Commit**
+
+```bash
+git add apps/website/src/components/docs/MdxRenderer.tsx apps/website/src/app/global.css
+git commit -m "fix(website): keep anchor glyphs out of heading text"
+```
+
+---
+
+## Phase 3 — Content and E-E-A-T
+
+### Task 11: `/about` page with a Person entity
+
+Google's guidance leans on first-hand expertise and people-first content. There is currently no page on the site that establishes who writes it. AI answer engines cite named, attributable authors far more readily than anonymous docs.
+
+**Files:**
+- Create: `apps/website/src/app/about/page.tsx`
+- Modify: `apps/website/src/lib/site-metadata.ts`
+- Modify: `apps/website/src/components/shared/Footer.tsx`
+
+- [ ] **Step 1: Create the page**
+
+Create `apps/website/src/app/about/page.tsx`:
+
+```tsx
+// SPDX-License-Identifier: MIT
+import type { Metadata } from 'next';
+import { JsonLd } from '../../components/shared/JsonLd';
+import { createPageMetadata, getCanonicalUrl } from '../../lib/site-metadata';
+import { blogAuthors } from '../../lib/blog-authors';
+
+export const metadata: Metadata = createPageMetadata({
+  title: 'About — Threadplane',
+  description:
+    'Threadplane is built by Brian Love, an Angular consultant and open-source maintainer, to give Angular teams a production UI layer for LangGraph and AG-UI agents.',
+  pathname: '/about',
+  type: 'website',
+});
+
+export default function AboutPage() {
+  const brian = blogAuthors['brian'];
+
+  return (
+    <main style={{ maxWidth: 768, margin: '0 auto', padding: '128px 24px 96px' }}>
+      <JsonLd
+        data={{
+          '@context': 'https://schema.org',
+          '@type': 'AboutPage',
+          url: getCanonicalUrl('/about'),
+          mainEntity: {
+            '@type': 'Person',
+            name: brian.name,
+            jobTitle: brian.role,
+            description: brian.bio,
+            url: getCanonicalUrl('/about'),
+            sameAs: ['https://github.com/blove'],
+            knowsAbout: ['Angular', 'LangGraph', 'AG-UI', 'Agentic UI', 'TypeScript'],
+          },
+        }}
+      />
+      <h1>About Threadplane</h1>
+      <p>
+        Threadplane is the Angular UI layer for production agent applications. It exists because
+        Angular teams shipping LangGraph and AG-UI agents kept rebuilding the same last mile:
+        streaming, durable threads, interrupts, tool calls, and generative UI.
+      </p>
+      <h2>Who builds it</h2>
+      <p>
+        {brian.name} — {brian.role}. {brian.bio}
+      </p>
+      <h2>What we will not do</h2>
+      <p>
+        No runtime lock-in and no abandoned majors. Threadplane binds to a runtime-neutral Agent
+        contract, and every adapter ships against the same conformance suite.
+      </p>
+    </main>
+  );
+}
+```
+
+Replace the prose with Brian's own words before merging — this page is an E-E-A-T signal, and boilerplate defeats the purpose. Do not fabricate biography details.
+
+- [ ] **Step 2: Add it to the sitemap**
+
+In `apps/website/src/lib/site-metadata.ts`, add `'/about'` to the `staticRoutes` array in `getSitemapRoutes`, after `'/pricing'`.
+
+- [ ] **Step 3: Link it from the footer**
+
+In `apps/website/src/components/shared/Footer.tsx`, add an `About` link to `/about` in the same group as the existing Contact link, matching the surrounding link markup exactly.
+
+- [ ] **Step 4: Verify**
+
+```bash
+npx nx test website && npx nx build website
+```
+
+Expected: PASS and a successful build. Then serve and confirm `curl -s http://localhost:3000/about | grep -c 'application/ld+json'` returns `2`.
+
+- [ ] **Step 5: Commit**
+
+```bash
+git add apps/website/src/app/about apps/website/src/lib/site-metadata.ts apps/website/src/components/shared/Footer.tsx
+git commit -m "feat(website): about page with person entity"
+```
+
+---
+
+### Task 12: Add diagrams to the blog
+
+Every blog post currently ships zero images. Google's guide asks for high-quality images and video where relevant, and a diagram is the highest-value image for an architecture tutorial.
+
+**Files:**
+- Modify: `apps/website/content/blog/2026-08-13-angular-chat-app-tutorial-with-ag-ui.mdx`
+- Modify: `apps/website/content/blog/2026-08-13-angular-chat-app-tutorial-with-langchain-langgraph.mdx`
+- Modify: `apps/website/content/blog/2026-08-09-agentic-ui-in-angular-production-patterns.mdx`
+- Create: `apps/website/public/blog/diagrams/*.svg`
+
+- [ ] **Step 1: Confirm the gap**
+
+```bash
+grep -c "!\[" apps/website/content/blog/*.mdx
+```
+
+Expected: `0` for every file.
+
+- [ ] **Step 2: Check how MDX renders images**
+
+```bash
+grep -n "img\|Image" apps/website/src/components/docs/MdxRenderer.tsx
+```
+
+If there is no `img` override, add one that renders a plain `<img>` with `loading="lazy"`, `width`, `height`, and the `alt` from the MDX — dimensions prevent CLS, which is a page-experience signal.
+
+- [ ] **Step 3: Author one SVG diagram per post**
+
+For the AG-UI tutorial, create `apps/website/public/blog/diagrams/ag-ui-event-flow.svg` showing: AG-UI backend → SSE event stream (17 event types) → `@threadplane/ag-ui` adapter → Angular signals → `@threadplane/chat` components. Use the design tokens' surface and text colors so it reads in both themes. Repeat for the LangGraph tutorial (graph → SSE → adapter → signals) and the production-patterns post (client-tool continuation loop).
+
+- [ ] **Step 4: Reference each diagram with descriptive alt text**
+
+Insert immediately after the "What are we building?" heading of the AG-UI post:
+
+```mdx
+![AG-UI backend streams 17 SSE event types into the @threadplane/ag-ui adapter, which converts them into Angular signals consumed by @threadplane/chat components.](/blog/diagrams/ag-ui-event-flow.svg)
+```
+
+The alt text is a full sentence describing the mechanism, not a label — it is extractable content, not decoration.
+
+- [ ] **Step 5: Verify**
+
+```bash
+npx nx serve website
+```
+
+In a second shell:
+
+```bash
+curl -s http://localhost:3000/blog/angular-chat-app-tutorial-with-ag-ui | grep -c "<img"
+```
+
+Expected: at least `1`, and each `<img>` has an `alt` attribute.
+
+- [ ] **Step 6: Commit**
+
+```bash
+git add apps/website/content/blog apps/website/public/blog/diagrams apps/website/src/components/docs/MdxRenderer.tsx
+git commit -m "docs(blog): architecture diagrams for the tutorial posts"
+```
+
+---
+
+### Task 13: Question-form headings across older posts and key docs
+
+The two newest blog posts already use question-form H2s. The four older posts use noun phrases. Question headings match how people phrase things in AI Mode, and give retrieval a clean question/answer pair — without any "chunking" or keyword stuffing, both of which Google explicitly calls useless.
+
+**Files:**
+- Modify: `apps/website/content/blog/2026-05-17-build-a-streaming-chat-ui-in-angular-with-langgraph.mdx`
+- Modify: `apps/website/content/blog/2026-05-21-build-fullstack-agentic-angular-apps-using-ag-ui.mdx`
+- Modify: `apps/website/content/blog/2026-05-28-human-in-the-loop-langgraph-agents-in-angular.mdx`
+- Modify: `apps/website/content/blog/2026-06-04-human-in-the-loop-ag-ui-agents-in-angular.mdx`
+
+- [ ] **Step 1: List the current headings**
+
+```bash
+grep -n "^## " apps/website/content/blog/2026-05-17-*.mdx apps/website/content/blog/2026-05-21-*.mdx apps/website/content/blog/2026-05-28-*.mdx apps/website/content/blog/2026-06-04-*.mdx
+```
+
+- [ ] **Step 2: Rewrite only the headings that are genuinely answering a question**
+
+Example, in the streaming post: `## Why streaming matters` → `## Why does streaming matter for agent UIs?`; `## The architecture in three boxes` → `## What does the architecture look like?`. Leave `## Goals` alone — it is not a question and forcing one would be exactly the "special rewrites for AI" Google warns against. Change no body copy.
+
+- [ ] **Step 3: Verify no anchors broke**
+
+```bash
+grep -rn "](#" apps/website/content/blog | grep -v node_modules
+```
+
+Any in-page anchor whose target heading you renamed must be updated to the new slug. Expected after fixing: every listed anchor resolves to a heading present in the same file.
+
+- [ ] **Step 4: Commit**
+
+```bash
+git add apps/website/content/blog
+git commit -m "docs(blog): question-form section headings in the 2026-05/06 posts"
+```
+
+---
+
+### Task 14: Freeze the programmatic `solutions/*` surface
+
+Three `solutions/*` pages generated from a 9.4 KB data file is fine. Thirty would be scaled content abuse, which Google's guide names as a policy violation. Write the rule down before someone scales it.
+
+**Files:**
+- Modify: `apps/website/src/lib/solutions-data.ts`
+
+- [ ] **Step 1: Add the constraint as a file-header comment**
+
+At the top of `apps/website/src/lib/solutions-data.ts`, below the SPDX line:
+
+```ts
+/**
+ * Solutions pages are hand-written, not templated at scale.
+ *
+ * Google's scaled-content-abuse policy targets programmatically generated
+ * page families that vary only by keyword. Every entry here must carry
+ * genuinely distinct, first-hand content — a real customer problem, a real
+ * architecture, real code. If a new entry would be a find-and-replace of an
+ * existing one, do not add it; write a blog post or a docs guide instead.
+ *
+ * See https://developers.google.com/search/docs/fundamentals/ai-optimization-guide
+ */
+```
+
+- [ ] **Step 2: Verify each existing page is genuinely distinct**
+
+```bash
+npx tsx -e "
+import('./apps/website/src/lib/solutions-data.ts').then((m) => {
+  for (const s of m.solutions ?? []) console.log(s.slug, JSON.stringify(s).length);
+});
+"
+```
+
+Read the three pages. If any two share more than boilerplate structure, rewrite the weaker one with genuinely different content or remove it from the sitemap. Record the decision in the PR description.
+
+- [ ] **Step 3: Commit**
+
+```bash
+git add apps/website/src/lib/solutions-data.ts
+git commit -m "docs(website): record the no-scaled-content rule for solutions pages"
+```
+
+---
+
+## Phase 4 — Measurement
+
+### Task 15: AI crawler and AI referral tracking
+
+AI crawlers do not execute JavaScript, so the client PostHog snippet never sees them. Edge middleware does. This gives a real answer to "are AI engines reading us, and are they sending anyone back" — the one measurement Search Console will not provide.
+
+**Files:**
+- Create: `apps/website/src/lib/analytics/ai-traffic.ts`
+- Create: `apps/website/src/lib/analytics/ai-traffic.spec.ts`
+- Modify: `apps/website/src/lib/analytics/events.ts`
+- Create: `apps/website/src/middleware.ts`
+
+- [ ] **Step 1: Write the failing test**
+
+Create `apps/website/src/lib/analytics/ai-traffic.spec.ts`:
+
+```ts
+import { describe, expect, it } from 'vitest';
+import { classifyAiCrawler, classifyAiReferrer } from './ai-traffic';
+
+describe('classifyAiCrawler', () => {
+  it('identifies the major AI crawlers', () => {
+    expect(classifyAiCrawler('Mozilla/5.0 (compatible; GPTBot/1.2; +https://openai.com/gptbot)')).toBe('gptbot');
+    expect(classifyAiCrawler('Mozilla/5.0 (compatible; ClaudeBot/1.0)')).toBe('claudebot');
+    expect(classifyAiCrawler('Mozilla/5.0 (compatible; PerplexityBot/1.0)')).toBe('perplexitybot');
+    expect(classifyAiCrawler('Mozilla/5.0 (compatible; Google-Extended)')).toBe('google-extended');
+    expect(classifyAiCrawler('Mozilla/5.0 (compatible; Googlebot/2.1)')).toBe(null);
+    expect(classifyAiCrawler('')).toBe(null);
+  });
+});
+
+describe('classifyAiReferrer', () => {
+  it('identifies referrals from AI answer engines', () => {
+    expect(classifyAiReferrer('https://chatgpt.com/c/abc')).toBe('chatgpt');
+    expect(classifyAiReferrer('https://www.perplexity.ai/search?q=x')).toBe('perplexity');
+    expect(classifyAiReferrer('https://claude.ai/chat/1')).toBe('claude');
+    expect(classifyAiReferrer('https://gemini.google.com/app')).toBe('gemini');
+    expect(classifyAiReferrer('https://www.google.com/search?q=x')).toBe(null);
+    expect(classifyAiReferrer('')).toBe(null);
+  });
+});
+```
+
+- [ ] **Step 2: Run it and confirm it fails**
+
+```bash
+npx nx test website
+```
+
+Expected: FAIL — `Failed to resolve import "./ai-traffic"`.
+
+- [ ] **Step 3: Implement the classifiers**
+
+Create `apps/website/src/lib/analytics/ai-traffic.ts`:
+
+```ts
+// SPDX-License-Identifier: MIT
+
+const CRAWLERS: [RegExp, string][] = [
+  [/GPTBot/i, 'gptbot'],
+  [/OAI-SearchBot/i, 'oai-searchbot'],
+  [/ChatGPT-User/i, 'chatgpt-user'],
+  [/ClaudeBot/i, 'claudebot'],
+  [/Claude-Web/i, 'claude-web'],
+  [/anthropic-ai/i, 'anthropic-ai'],
+  [/PerplexityBot/i, 'perplexitybot'],
+  [/Perplexity-User/i, 'perplexity-user'],
+  [/Google-Extended/i, 'google-extended'],
+  [/Google-CloudVertexBot/i, 'google-vertex'],
+  [/Applebot-Extended/i, 'applebot-extended'],
+  [/Bytespider/i, 'bytespider'],
+  [/Meta-ExternalAgent/i, 'meta-external-agent'],
+  [/CCBot/i, 'ccbot'],
+];
+
+const REFERRERS: [RegExp, string][] = [
+  [/(^|\.)chatgpt\.com$/i, 'chatgpt'],
+  [/(^|\.)chat\.openai\.com$/i, 'chatgpt'],
+  [/(^|\.)perplexity\.ai$/i, 'perplexity'],
+  [/(^|\.)claude\.ai$/i, 'claude'],
+  [/(^|\.)gemini\.google\.com$/i, 'gemini'],
+  [/(^|\.)copilot\.microsoft\.com$/i, 'copilot'],
+  [/(^|\.)you\.com$/i, 'you'],
+];
+
+/** Returns a stable crawler slug, or null for humans and non-AI bots. */
+export function classifyAiCrawler(userAgent: string): string | null {
+  if (!userAgent) return null;
+  for (const [pattern, slug] of CRAWLERS) {
+    if (pattern.test(userAgent)) return slug;
+  }
+  return null;
+}
+
+/** Returns a stable AI-engine slug for a referrer URL, or null. */
+export function classifyAiReferrer(referrer: string): string | null {
+  if (!referrer) return null;
+  let host: string;
+  try {
+    host = new URL(referrer).hostname;
+  } catch {
+    return null;
+  }
+  for (const [pattern, slug] of REFERRERS) {
+    if (pattern.test(host)) return slug;
+  }
+  return null;
+}
+```
+
+- [ ] **Step 4: Run the tests and confirm they pass**
+
+```bash
+npx nx test website
+```
+
+Expected: PASS.
+
+- [ ] **Step 5: Register the events**
+
+Open `apps/website/src/lib/analytics/events.ts` and add two entries to the `analyticsEvents` registry, following the exact shape of the entries already there:
+
+```ts
+  aiCrawlerVisit: 'ai_crawler_visit',
+  aiReferralVisit: 'ai_referral_visit',
+```
+
+Use whatever key/value convention the existing entries use — read the file first and match it rather than assuming.
+
+- [ ] **Step 6: Write the middleware**
+
+Create `apps/website/src/middleware.ts`:
+
+```ts
+// SPDX-License-Identifier: MIT
+import { NextResponse, type NextRequest } from 'next/server';
+import { classifyAiCrawler, classifyAiReferrer } from './lib/analytics/ai-traffic';
+
+export const config = {
+  // HTML routes only — skip assets, API routes, and Next internals.
+  matcher: ['/((?!api|_next/static|_next/image|ingest|favicon.ico|.*\\.(?:png|jpg|jpeg|svg|webp|ico|txt|xml|pdf)$).*)'],
+};
+
+const POSTHOG_HOST = 'https://us.i.posthog.com';
+
+async function capture(event: string, properties: Record<string, string>): Promise<void> {
+  const token = process.env['NEXT_PUBLIC_POSTHOG_TOKEN'];
+  if (!token) return;
+  try {
+    await fetch(`${POSTHOG_HOST}/capture/`, {
+      method: 'POST',
+      headers: { 'content-type': 'application/json' },
+      body: JSON.stringify({
+        api_key: token,
+        event,
+        distinct_id: `ai:${properties['source']}`,
+        properties: { ...properties, $process_person_profile: false },
+      }),
+    });
+  } catch {
+    // Analytics must never break a page render.
+  }
+}
+
+export function middleware(request: NextRequest): NextResponse {
+  const pathname = request.nextUrl.pathname;
+  const crawler = classifyAiCrawler(request.headers.get('user-agent') ?? '');
+  const referrer = crawler ? null : classifyAiReferrer(request.headers.get('referer') ?? '');
+
+  if (crawler) {
+    void capture('ai_crawler_visit', { source: crawler, path: pathname });
+  } else if (referrer) {
+    void capture('ai_referral_visit', { source: referrer, path: pathname });
+  }
+
+  return NextResponse.next();
+}
+```
+
+- [ ] **Step 7: Verify the middleware fires**
+
+```bash
+npx nx serve website
+```
+
+In a second shell:
+
+```bash
+curl -s -o /dev/null -A "Mozilla/5.0 (compatible; GPTBot/1.2; +https://openai.com/gptbot)" http://localhost:3000/docs/chat/getting-started/installation
+curl -s -o /dev/null -e "https://chatgpt.com/c/abc" http://localhost:3000/blog/angular-chat-app-tutorial-with-ag-ui
+curl -s -o /dev/null http://localhost:3000/
+```
+
+Expected: in PostHog's live-events view, exactly one `ai_crawler_visit` (source `gptbot`) and one `ai_referral_visit` (source `chatgpt`), and nothing for the third request. If `NEXT_PUBLIC_POSTHOG_TOKEN` is unset locally, assert instead that all three requests return 200 and no error is logged.
+
+- [ ] **Step 8: Confirm the production build still passes its bundle budget**
+
+```bash
+npx nx build website --configuration=production
+```
+
+Expected: success. (This project has bitten prod deploys before with prod-only budgets that dev builds never check.)
+
+- [ ] **Step 9: Commit**
+
+```bash
+git add apps/website/src/lib/analytics apps/website/src/middleware.ts
+git commit -m "feat(website): track ai crawler and ai referral traffic"
+```
+
+---
+
+### Task 16: Measurement runbook
+
+**Files:**
+- Create: `docs/gtm/ai-search-measurement.md`
+
+- [ ] **Step 1: Write the runbook**
+
+Create `docs/gtm/ai-search-measurement.md`:
+
+```markdown
+# Measuring AI search visibility for threadplane.ai
+
+## What each source can and cannot answer
+
+| Question | Source | Automated? |
+|---|---|---|
+| Impressions/clicks in AI Overviews and AI Mode | Search Console → Performance → **Generative AI** report | **No — UI only.** Not in `searchanalytics.query` (`type` accepts only web/image/video/news/discover/googleNews), not in `searchAppearance`, not in the BigQuery export, as of 2026-08. |
+| Query and page performance in classic web search | `npm run gsc:pull && npm run gsc:report` | Yes |
+| Index coverage per URL | URL Inspection API, via the same pull | Yes (quota 2000/day) |
+| Discover impressions | `type: 'discover'` in the pull | Yes |
+| Are AI crawlers fetching us | PostHog `ai_crawler_visit` | Yes |
+| Are AI engines sending referrals | PostHog `ai_referral_visit` | Yes |
+| Do we appear in a given assistant's answer | Manual spot-check | No |
+
+## Monthly routine
+
+1. `npm run gsc:pull && npm run gsc:report`, then read `apps/website/.gsc/report.md`.
+   Act on, in order: **not indexed** → **canonical mismatches** → **striking distance** →
+   **weak CTR**.
+2. In Search Console, open Performance → Generative AI, set the window to the last
+   3 months, and export the CSV. Save it as
+   `apps/website/.gsc/generative-ai-YYYY-MM.csv` (gitignored). Compare total
+   impressions and top pages against the previous month by hand. Re-check whether
+   the API has caught up — Google shipped Discover and News to the UI months before
+   the API, and this is expected to follow.
+3. In PostHog, chart `ai_crawler_visit` by `source` and `path` over 90 days. A crawler
+   that stops fetching a section is an early warning. Chart `ai_referral_visit` by
+   `source` for the conversion side.
+4. Spot-check five assistant prompts a real buyer would type — e.g. "Angular chat UI
+   for LangGraph", "how do I stream a LangGraph agent into Angular", "AG-UI Angular
+   client" — in ChatGPT, Claude, Perplexity, and Google AI Mode. Record whether
+   threadplane.ai is cited and what it is cited *for*. This is qualitative and slow,
+   and there is no honest way to automate it; do five, not fifty.
+
+## Tactics that do not work — do not add them
+
+Straight from Google's AI optimization guide: `llms.txt` and AI-specific text files do
+nothing for Google Search; content "chunking" is unnecessary; AI-specific keyword
+rewrites are unnecessary; pursuing inauthentic mentions is ineffective. Ignore any
+third-party tool claiming access to internal Google AI metrics — those numbers are
+modeled, not measured.
+
+We keep `/llms.txt` and `/llms-full.txt` because some non-Google assistants do read
+them, not because they help Google.
+```
+
+- [ ] **Step 2: Verify the referenced npm scripts exist**
+
+```bash
+grep -n "gsc:pull\|gsc:report" package.json
+```
+
+Expected: both present (added in Task 4).
+
+- [ ] **Step 3: Commit**
+
+```bash
+git add docs/gtm/ai-search-measurement.md
+git commit -m "docs(gtm): ai search measurement runbook"
+```
+
+---
+
+## Final verification
+
+- [ ] **Step 1: Full check**
+
+```bash
+npx nx test website && npx nx lint website && npx nx build website --configuration=production
+```
+
+Expected: all three pass. Lint **warnings** are tolerated by CI; lint **errors** are not. To count errors, strip ANSI first — `grep -cE ' error '` on raw output silently returns 0:
+
+```bash
+npx nx lint website 2>&1 | sed -r "s/\x1B\[[0-9;]*[mK]//g" | grep -cE '  error  '
+```
+
+Expected: `0`.
+
+- [ ] **Step 2: Verify the live-equivalent output locally**
+
+```bash
+npx nx serve website
+```
+
+In a second shell:
+
+```bash
+for u in / /about /blog/angular-chat-app-tutorial-with-ag-ui /docs/chat/getting-started/installation; do
+  echo "=== $u"
+  curl -s "http://localhost:3000$u" -o /tmp/p.html
+  echo "ld+json blocks: $(grep -c 'application/ld+json' /tmp/p.html)"
+  grep -o '<title>[^<]*</title>' /tmp/p.html
+  grep -o '<link rel="canonical" href="[^"]*"' /tmp/p.html
+done
+curl -s http://localhost:3000/sitemap.xml | grep -c "<lastmod>"
+```
+
+Expected: every page has at least one `ld+json` block, exactly one canonical, a title ending in `— Threadplane`, and the sitemap `lastmod` count equals the URL count (141 after `/about` lands).
+
+- [ ] **Step 3: Post-merge validation (record results in the PR)**
+
+1. Rich Results Test on the deployed `/blog/*` and `/docs/*` URLs → zero errors.
+2. Search Console → Sitemaps → resubmit `sitemap.xml`.
+3. Search Console → URL Inspection → Request indexing for `/about`.
+4. Re-run `npm run gsc:pull && npm run gsc:report` 14 days later and diff the index-health section against the pre-change run.

From 2ddc7884fef14afeca3f69e6aa7c29ea84d5cfe3 Mon Sep 17 00:00:00 2001
From: Brian Love <brian@liveloveapp.com>
Date: Thu, 20 Aug 2026 11:38:14 -0700
Subject: [PATCH 02/35] feat(website): search console api service-account auth

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
---
 apps/website/.gitignore            |  1 +
 apps/website/scripts/gsc/README.md | 29 ++++++++++++++
 apps/website/scripts/gsc/auth.ts   | 61 ++++++++++++++++++++++++++++++
 3 files changed, 91 insertions(+)
 create mode 100644 apps/website/.gitignore
 create mode 100644 apps/website/scripts/gsc/README.md
 create mode 100644 apps/website/scripts/gsc/auth.ts

diff --git a/apps/website/.gitignore b/apps/website/.gitignore
new file mode 100644
index 000000000..bfcc80dd7
--- /dev/null
+++ b/apps/website/.gitignore
@@ -0,0 +1 @@
+.gsc/
diff --git a/apps/website/scripts/gsc/README.md b/apps/website/scripts/gsc/README.md
new file mode 100644
index 000000000..e1763375b
--- /dev/null
+++ b/apps/website/scripts/gsc/README.md
@@ -0,0 +1,29 @@
+# Search Console API harness
+
+## One-time setup
+
+1. In Google Cloud console, create (or reuse) a project and enable the
+   **Google Search Console API** (`searchconsole.googleapis.com`).
+2. Create a service account. No project-level IAM roles are needed.
+3. Create a JSON key for that service account and download it.
+4. In Search Console, open the `threadplane.ai` **Domain property** →
+   Settings → Users and permissions → Add user → paste the service
+   account's `client_email` → permission **Full** (required: the URL
+   Inspection API rejects "Restricted" users).
+5. Export the key for local use — do NOT commit it:
+
+   export GSC_SERVICE_ACCOUNT_JSON="$(cat ~/secrets/threadplane-gsc.json)"
+   export GSC_SITE_URL="sc-domain:threadplane.ai"
+
+## Usage
+
+    npx tsx apps/website/scripts/gsc/pull.ts        # writes apps/website/.gsc/*.json
+    npx tsx apps/website/scripts/gsc/report.ts      # writes apps/website/.gsc/report.md
+
+## What this CANNOT do
+
+The Search Console **Generative AI performance report** (AI Overviews /
+AI Mode impressions and clicks) is UI-only as of 2026-08. It is not in
+`searchanalytics.query`, not in `searchAppearance`, and not in the
+BigQuery bulk export. See `docs/gtm/ai-search-measurement.md` for the
+manual export procedure.
diff --git a/apps/website/scripts/gsc/auth.ts b/apps/website/scripts/gsc/auth.ts
new file mode 100644
index 000000000..f3a44c48f
--- /dev/null
+++ b/apps/website/scripts/gsc/auth.ts
@@ -0,0 +1,61 @@
+// SPDX-License-Identifier: MIT
+import { createSign } from 'node:crypto';
+
+const TOKEN_URL = 'https://oauth2.googleapis.com/token';
+const SCOPE = 'https://www.googleapis.com/auth/webmasters.readonly';
+
+interface ServiceAccountKey {
+  client_email: string;
+  private_key: string;
+}
+
+function base64url(value: object): string {
+  return Buffer.from(JSON.stringify(value)).toString('base64url');
+}
+
+export function readServiceAccountKey(): ServiceAccountKey {
+  const raw = process.env['GSC_SERVICE_ACCOUNT_JSON'];
+  if (!raw) {
+    throw new Error(
+      'GSC_SERVICE_ACCOUNT_JSON is not set. See apps/website/scripts/gsc/README.md.',
+    );
+  }
+  const parsed = JSON.parse(raw) as Partial<ServiceAccountKey>;
+  if (!parsed.client_email || !parsed.private_key) {
+    throw new Error('GSC_SERVICE_ACCOUNT_JSON is missing client_email or private_key.');
+  }
+  return { client_email: parsed.client_email, private_key: parsed.private_key };
+}
+
+export async function getAccessToken(nowSeconds = Math.floor(Date.now() / 1000)): Promise<string> {
+  const key = readServiceAccountKey();
+  const signingInput = [
+    base64url({ alg: 'RS256', typ: 'JWT' }),
+    base64url({
+      iss: key.client_email,
+      scope: SCOPE,
+      aud: TOKEN_URL,
+      iat: nowSeconds,
+      exp: nowSeconds + 3600,
+    }),
+  ].join('.');
+  const signature = createSign('RSA-SHA256')
+    .update(signingInput)
+    .sign(key.private_key, 'base64url');
+
+  const response = await fetch(TOKEN_URL, {
+    method: 'POST',
+    headers: { 'content-type': 'application/x-www-form-urlencoded' },
+    body: new URLSearchParams({
+      grant_type: 'urn:ietf:params:oauth:grant-type:jwt-bearer',
+      assertion: `${signingInput}.${signature}`,
+    }),
+  });
+
+  if (!response.ok) {
+    throw new Error(`Token exchange failed: ${response.status} ${await response.text()}`);
+  }
+  const json = (await response.json()) as { access_token?: string };
+  if (!json.access_token) throw new Error('Token exchange returned no access_token.');
+  return json.access_token;
+}

From deaa509d0650c0d4d4df251218a0291506c072fd Mon Sep 17 00:00:00 2001
From: Brian Love <brian@liveloveapp.com>
Date: Thu, 20 Aug 2026 11:42:36 -0700
Subject: [PATCH 03/35] feat(website): typed search console api wrappers

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
---
 apps/website/scripts/gsc/api.ts | 114 ++++++++++++++++++++++++++++++++
 1 file changed, 114 insertions(+)
 create mode 100644 apps/website/scripts/gsc/api.ts

diff --git a/apps/website/scripts/gsc/api.ts b/apps/website/scripts/gsc/api.ts
new file mode 100644
index 000000000..a15089c7e
--- /dev/null
+++ b/apps/website/scripts/gsc/api.ts
@@ -0,0 +1,114 @@
+// SPDX-License-Identifier: MIT
+import { getAccessToken } from './auth';
+
+const BASE = 'https://www.googleapis.com/webmasters/v3';
+const INSPECT_URL = 'https://searchconsole.googleapis.com/v1/urlInspection/index:inspect';
+
+export type Dimension = 'query' | 'page' | 'country' | 'device' | 'date' | 'searchAppearance';
+
+export interface SearchAnalyticsRow {
+  keys: string[];
+  clicks: number;
+  impressions: number;
+  ctr: number;
+  position: number;
+}
+
+export function getSiteUrl(): string {
+  return process.env['GSC_SITE_URL'] ?? 'sc-domain:threadplane.ai';
+}
+
+async function authedFetch(url: string, init: RequestInit & { token: string }): Promise<unknown> {
+  const { token, ...rest } = init;
+  const response = await fetch(url, {
+    ...rest,
+    headers: { ...(rest.headers ?? {}), authorization: `Bearer ${token}`, 'content-type': 'application/json' },
+  });
+  if (!response.ok) {
+    throw new Error(`${url} → ${response.status} ${await response.text()}`);
+  }
+  return response.json();
+}
+
+/**
+ * Search Analytics. NOTE: `type` accepts only web|image|video|news|discover|
+ * googleNews. There is no AI Overviews / AI Mode type as of 2026-08.
+ */
+export async function querySearchAnalytics(options: {
+  startDate: string;
+  endDate: string;
+  dimensions: Dimension[];
+  rowLimit?: number;
+  startRow?: number;
+  type?: 'web' | 'image' | 'video' | 'news' | 'discover' | 'googleNews';
+}): Promise<SearchAnalyticsRow[]> {
+  const token = await getAccessToken();
+  const site = encodeURIComponent(getSiteUrl());
+  const rows: SearchAnalyticsRow[] = [];
+  let startRow = options.startRow ?? 0;
+  const rowLimit = options.rowLimit ?? 25000;
+
+  for (;;) {
+    const page = (await authedFetch(`${BASE}/sites/${site}/searchAnalytics/query`, {
+      token,
+      method: 'POST',
+      body: JSON.stringify({
+        startDate: options.startDate,
+        endDate: options.endDate,
+        dimensions: options.dimensions,
+        type: options.type ?? 'web',
+        rowLimit,
+        startRow,
+        dataState: 'all',
+      }),
+    })) as { rows?: SearchAnalyticsRow[] };
+    const batch = page.rows ?? [];
+    rows.push(...batch);
+    if (batch.length < rowLimit) break;
+    startRow += rowLimit;
+  }
+  return rows;
+}
+
+export async function listSitemaps(): Promise<unknown> {
+  const token = await getAccessToken();
+  return authedFetch(`${BASE}/sites/${encodeURIComponent(getSiteUrl())}/sitemaps`, {
+    token,
+    method: 'GET',
+  });
+}
+
+export interface InspectionResult {
+  url: string;
+  verdict: string;
+  coverageState: string;
+  lastCrawlTime: string | null;
+  robotsTxtState: string;
+  indexingState: string;
+  googleCanonical: string | null;
+  userCanonical: string | null;
+}
+
+export async function inspectUrl(inspectionUrl: string): Promise<InspectionResult> {
+  const token = await getAccessToken();
+  const raw = (await authedFetch(INSPECT_URL, {
+    token,
+    method: 'POST',
+    body: JSON.stringify({ inspectionUrl, siteUrl: getSiteUrl(), languageCode: 'en-US' }),
+  })) as {
+    inspectionResult?: {
+      indexStatusResult?: Record<string, string | undefined>;
+    };
+  };
+  const status = raw.inspectionResult?.indexStatusResult ?? {};
+  return {
+    url: inspectionUrl,
+    verdict: status['verdict'] ?? 'UNKNOWN',
+    coverageState: status['coverageState'] ?? 'UNKNOWN',
+    lastCrawlTime: status['lastCrawlTime'] ?? null,
+    robotsTxtState: status['robotsTxtState'] ?? 'UNKNOWN',
+    indexingState: status['indexingState'] ?? 'UNKNOWN',
+    googleCanonical: status['googleCanonical'] ?? null,
+    userCanonical: status['userCanonical'] ?? null,
+  };
+}

From 93b66174a26499fad64862749d8eb39a331e2fb3 Mon Sep 17 00:00:00 2001
From: Brian Love <brian@liveloveapp.com>
Date: Thu, 20 Aug 2026 11:46:16 -0700
Subject: [PATCH 04/35] fix(website): cache search console access tokens

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
---
 apps/website/scripts/gsc/auth.ts | 46 +++++++++++++++++++++++++++++---
 1 file changed, 43 insertions(+), 3 deletions(-)

diff --git a/apps/website/scripts/gsc/auth.ts b/apps/website/scripts/gsc/auth.ts
index f3a44c48f..d2b880750 100644
--- a/apps/website/scripts/gsc/auth.ts
+++ b/apps/website/scripts/gsc/auth.ts
@@ -4,11 +4,20 @@ import { createSign } from 'node:crypto';
 const TOKEN_URL = 'https://oauth2.googleapis.com/token';
 const SCOPE = 'https://www.googleapis.com/auth/webmasters.readonly';
 
+/** Refresh this many seconds before the token's actual expiry, not exactly at it. */
+const REFRESH_SKEW_SECONDS = 60;
+
 interface ServiceAccountKey {
   client_email: string;
   private_key: string;
 }
 
+interface CachedToken {
+  accessToken: string;
+  /** Epoch seconds at which the token stops being usable (server-reported expiry). */
+  expiresAtSeconds: number;
+}
+
 function base64url(value: object): string {
   return Buffer.from(JSON.stringify(value)).toString('base64url');
 }
@@ -27,7 +36,19 @@ export function readServiceAccountKey(): ServiceAccountKey {
   return { client_email: parsed.client_email, private_key: parsed.private_key };
 }
 
-export async function getAccessToken(nowSeconds = Math.floor(Date.now() / 1000)): Promise<string> {
+let cachedToken: CachedToken | null = null;
+let inFlightExchange: Promise<CachedToken> | null = null;
+
+/**
+ * Clears the in-process access-token cache. Exists so tests (and long-lived
+ * callers that suspect a revoked/expired token) can force a fresh exchange.
+ */
+export function resetAccessTokenCache(): void {
+  cachedToken = null;
+  inFlightExchange = null;
+}
+
+async function exchangeAccessToken(nowSeconds: number): Promise<CachedToken> {
   const key = readServiceAccountKey();
   const signingInput = [
     base64url({ alg: 'RS256', typ: 'JWT' }),
@@ -55,7 +76,26 @@ export async function getAccessToken(nowSeconds = Math.floor(Date.now() / 1000))
   if (!response.ok) {
     throw new Error(`Token exchange failed: ${response.status} ${await response.text()}`);
   }
-  const json = (await response.json()) as { access_token?: string };
+  const json = (await response.json()) as { access_token?: string; expires_in?: number };
   if (!json.access_token) throw new Error('Token exchange returned no access_token.');
-  return json.access_token;
+  return {
+    accessToken: json.access_token,
+    expiresAtSeconds: nowSeconds + (json.expires_in ?? 3600),
+  };
+}
+
+export async function getAccessToken(nowSeconds = Math.floor(Date.now() / 1000)): Promise<string> {
+  if (cachedToken && cachedToken.expiresAtSeconds - REFRESH_SKEW_SECONDS > nowSeconds) {
+    return cachedToken.accessToken;
+  }
+
+  if (!inFlightExchange) {
+    inFlightExchange = exchangeAccessToken(nowSeconds).finally(() => {
+      inFlightExchange = null;
+    });
+  }
+
+  const token = await inFlightExchange;
+  cachedToken = token;
+  return token.accessToken;
 }

From 3ddf41b2c82110b9628ef8de4c4291a265d2b3af Mon Sep 17 00:00:00 2001
From: Brian Love <brian@liveloveapp.com>
Date: Thu, 20 Aug 2026 11:48:19 -0700
Subject: [PATCH 05/35] feat(website): search console snapshot puller

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
---
 apps/website/scripts/gsc/pull.ts | 57 ++++++++++++++++++++++++++++++++
 1 file changed, 57 insertions(+)
 create mode 100644 apps/website/scripts/gsc/pull.ts

diff --git a/apps/website/scripts/gsc/pull.ts b/apps/website/scripts/gsc/pull.ts
new file mode 100644
index 000000000..46e1ccb41
--- /dev/null
+++ b/apps/website/scripts/gsc/pull.ts
@@ -0,0 +1,57 @@
+// SPDX-License-Identifier: MIT
+import fs from 'node:fs';
+import path from 'node:path';
+import { inspectUrl, listSitemaps, querySearchAnalytics, type InspectionResult } from './api';
+
+const OUT_DIR = path.join(process.cwd(), 'apps', 'website', '.gsc');
+
+function isoDaysAgo(days: number): string {
+  const date = new Date(Date.now() - days * 86_400_000);
+  return date.toISOString().slice(0, 10);
+}
+
+function write(name: string, value: unknown): void {
+  fs.mkdirSync(OUT_DIR, { recursive: true });
+  fs.writeFileSync(path.join(OUT_DIR, name), JSON.stringify(value, null, 2));
+  console.log(`wrote .gsc/${name}`);
+}
+
+async function sitemapUrls(): Promise<string[]> {
+  const response = await fetch('https://threadplane.ai/sitemap.xml');
+  const xml = await response.text();
+  return [...xml.matchAll(/<loc>([^<]+)<\/loc>/g)].map((m) => m[1]);
+}
+
+async function main(): Promise<void> {
+  // Search Analytics data lags ~2 days; end 3 days back for a stable window.
+  const endDate = isoDaysAgo(3);
+  const startDate = isoDaysAgo(93);
+
+  write('meta.json', { startDate, endDate, pulledAt: new Date().toISOString() });
+  write('queries.json', await querySearchAnalytics({ startDate, endDate, dimensions: ['query'] }));
+  write('pages.json', await querySearchAnalytics({ startDate, endDate, dimensions: ['page'] }));
+  write(
+    'query-page.json',
+    await querySearchAnalytics({ startDate, endDate, dimensions: ['query', 'page'] }),
+  );
+  write('dates.json', await querySearchAnalytics({ startDate, endDate, dimensions: ['date'] }));
+  write(
+    'discover.json',
+    await querySearchAnalytics({ startDate, endDate, dimensions: ['page'], type: 'discover' }),
+  );
+  write('sitemaps.json', await listSitemaps());
+
+  // URL Inspection is quota-limited (2000/day, 600/min). Serialize with a small delay.
+  const urls = await sitemapUrls();
+  const inspections: InspectionResult[] = [];
+  for (const url of urls) {
+    inspections.push(await inspectUrl(url));
+    await new Promise((resolve) => setTimeout(resolve, 150));
+  }
+  write('inspections.json', inspections);
+}
+
+main().catch((error: unknown) => {
+  console.error(error);
+  process.exitCode = 1;
+});

From 3d3f3d2274e0e68fa169dc42f4a60928a7d52156 Mon Sep 17 00:00:00 2001
From: Brian Love <brian@liveloveapp.com>
Date: Thu, 20 Aug 2026 11:52:45 -0700
Subject: [PATCH 06/35] fix(website): keep partial inspection results and fail
 loudly on a bad sitemap

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
---
 apps/website/scripts/gsc/pull.ts | 36 +++++++++++++++++++++++++++++---
 1 file changed, 33 insertions(+), 3 deletions(-)

diff --git a/apps/website/scripts/gsc/pull.ts b/apps/website/scripts/gsc/pull.ts
index 46e1ccb41..23971c178 100644
--- a/apps/website/scripts/gsc/pull.ts
+++ b/apps/website/scripts/gsc/pull.ts
@@ -18,8 +18,20 @@ function write(name: string, value: unknown): void {
 
 async function sitemapUrls(): Promise<string[]> {
   const response = await fetch('https://threadplane.ai/sitemap.xml');
+  if (!response.ok) {
+    throw new Error(`sitemap fetch failed: ${response.status} ${response.statusText}`);
+  }
   const xml = await response.text();
-  return [...xml.matchAll(/<loc>([^<]+)<\/loc>/g)].map((m) => m[1]);
+  const urls = [...xml.matchAll(/<loc>([^<]+)<\/loc>/g)].map((m) => m[1]);
+  if (urls.length === 0) {
+    throw new Error('sitemap.xml matched zero <loc> entries; treating as a broken fetch, not empty inventory.');
+  }
+  return urls;
+}
+
+interface InspectionFailure {
+  url: string;
+  error: string;
 }
 
 async function main(): Promise<void> {
@@ -42,13 +54,31 @@ async function main(): Promise<void> {
   write('sitemaps.json', await listSitemaps());
 
   // URL Inspection is quota-limited (2000/day, 600/min). Serialize with a small delay.
+  // Failures are collected separately rather than dropped or faked, so a partial
+  // sweep still yields a usable inspections.json plus a visible error trail.
   const urls = await sitemapUrls();
   const inspections: InspectionResult[] = [];
-  for (const url of urls) {
-    inspections.push(await inspectUrl(url));
+  const failures: InspectionFailure[] = [];
+  for (const [index, url] of urls.entries()) {
+    try {
+      inspections.push(await inspectUrl(url));
+    } catch (error) {
+      failures.push({ url, error: error instanceof Error ? error.message : String(error) });
+    }
+    const done = index + 1;
+    if (done % 25 === 0 || done === urls.length) {
+      console.log(`inspected ${done}/${urls.length} urls`);
+    }
     await new Promise((resolve) => setTimeout(resolve, 150));
   }
   write('inspections.json', inspections);
+  if (failures.length > 0) {
+    write('inspection-errors.json', failures);
+  }
+  console.log(
+    `inspected ${inspections.length}/${urls.length} urls, ${failures.length} failed` +
+      (failures.length > 0 ? ' (see .gsc/inspection-errors.json)' : ''),
+  );
 }
 
 main().catch((error: unknown) => {

From 5852de3d9efebf77ba653cbbf99b43fc9344670f Mon Sep 17 00:00:00 2001
From: Brian Love <brian@liveloveapp.com>
Date: Thu, 20 Aug 2026 12:01:33 -0700
Subject: [PATCH 07/35] feat(website): search console analysis report

Pure analysis helpers (striking distance, zero-impression pages,
unindexed, canonical mismatches, weak CTR) plus a markdown report
generator over the .gsc snapshots.

The report reads inspection-errors.json when present so a partial
inspection sweep is stated as partial: failed URLs stay in the sitemap
inventory, the failure count is reported, and the index-health counts
are labelled lower bounds rather than implying a clean bill of health.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
---
 apps/website/scripts/gsc/analysis.spec.ts |  88 +++++++++++++
 apps/website/scripts/gsc/analysis.ts      |  76 +++++++++++
 apps/website/scripts/gsc/report.ts        | 150 ++++++++++++++++++++++
 apps/website/vite.config.mts              |   2 +-
 package.json                              |   2 +
 5 files changed, 317 insertions(+), 1 deletion(-)
 create mode 100644 apps/website/scripts/gsc/analysis.spec.ts
 create mode 100644 apps/website/scripts/gsc/analysis.ts
 create mode 100644 apps/website/scripts/gsc/report.ts

diff --git a/apps/website/scripts/gsc/analysis.spec.ts b/apps/website/scripts/gsc/analysis.spec.ts
new file mode 100644
index 000000000..4e048f457
--- /dev/null
+++ b/apps/website/scripts/gsc/analysis.spec.ts
@@ -0,0 +1,88 @@
+import { describe, expect, it } from 'vitest';
+import {
+  capList,
+  describeInspectionCoverage,
+  findStrikingDistance,
+  findUnindexed,
+  findZeroImpressionPages,
+} from './analysis';
+
+const rows = [
+  { keys: ['angular langgraph chat'], clicks: 0, impressions: 400, ctr: 0, position: 11.2 },
+  { keys: ['threadplane'], clicks: 90, impressions: 100, ctr: 0.9, position: 1.1 },
+  { keys: ['obscure long tail'], clicks: 0, impressions: 3, ctr: 0, position: 42 },
+];
+
+describe('findStrikingDistance', () => {
+  it('returns rows ranking 5-20 with meaningful impressions, best opportunity first', () => {
+    const result = findStrikingDistance(rows, { minImpressions: 50 });
+    expect(result.map((r) => r.keys[0])).toEqual(['angular langgraph chat']);
+  });
+});
+
+describe('findZeroImpressionPages', () => {
+  it('lists sitemap URLs that earned no impressions in the window', () => {
+    const result = findZeroImpressionPages(
+      ['https://threadplane.ai/a', 'https://threadplane.ai/b'],
+      [{ keys: ['https://threadplane.ai/a'], clicks: 1, impressions: 10, ctr: 0.1, position: 5 }],
+    );
+    expect(result).toEqual(['https://threadplane.ai/b']);
+  });
+});
+
+describe('findUnindexed', () => {
+  it('flags inspections whose verdict is not PASS', () => {
+    const result = findUnindexed([
+      {
+        url: 'https://threadplane.ai/a',
+        verdict: 'PASS',
+        coverageState: 'Submitted and indexed',
+        lastCrawlTime: null,
+        robotsTxtState: 'ALLOWED',
+        indexingState: 'INDEXING_ALLOWED',
+        googleCanonical: null,
+        userCanonical: null,
+      },
+      {
+        url: 'https://threadplane.ai/b',
+        verdict: 'NEUTRAL',
+        coverageState: 'Discovered - currently not indexed',
+        lastCrawlTime: null,
+        robotsTxtState: 'ALLOWED',
+        indexingState: 'INDEXING_ALLOWED',
+        googleCanonical: null,
+        userCanonical: null,
+      },
+    ]);
+    expect(result.map((r) => r.url)).toEqual(['https://threadplane.ai/b']);
+  });
+});
+
+describe('describeInspectionCoverage', () => {
+  it('reports a complete sweep when nothing failed', () => {
+    expect(describeInspectionCoverage({ inspected: 42, failed: 0 })).toBe(
+      'Coverage: complete — all 42 sitemap URLs inspected.',
+    );
+  });
+
+  it('warns that counts are lower bounds when inspections failed', () => {
+    const text = describeInspectionCoverage({ inspected: 8, failed: 2 });
+    expect(text).toContain('PARTIAL');
+    expect(text).toContain('2 of 10');
+    expect(text).toContain('lower bound');
+  });
+});
+
+describe('capList', () => {
+  it('passes a short list through with nothing withheld', () => {
+    expect(capList(['a', 'b'], 20)).toEqual({ shown: ['a', 'b'], remaining: 0 });
+  });
+
+  it('trims an overflowing list and counts the remainder', () => {
+    const items = Array.from({ length: 23 }, (_, i) => `url-${i}`);
+    const result = capList(items, 20);
+    expect(result.shown).toHaveLength(20);
+    expect(result.shown[19]).toBe('url-19');
+    expect(result.remaining).toBe(3);
+  });
+});
diff --git a/apps/website/scripts/gsc/analysis.ts b/apps/website/scripts/gsc/analysis.ts
new file mode 100644
index 000000000..9c834bc14
--- /dev/null
+++ b/apps/website/scripts/gsc/analysis.ts
@@ -0,0 +1,76 @@
+// SPDX-License-Identifier: MIT
+import type { InspectionResult, SearchAnalyticsRow } from './api';
+
+/** Queries ranking just off page one — the cheapest ranking wins available. */
+export function findStrikingDistance(
+  rows: SearchAnalyticsRow[],
+  options: { minImpressions: number },
+): SearchAnalyticsRow[] {
+  return rows
+    .filter(
+      (row) =>
+        row.position >= 5 && row.position <= 20 && row.impressions >= options.minImpressions,
+    )
+    .sort((a, b) => b.impressions - a.impressions);
+}
+
+/** Sitemap URLs Google never showed for anything in the window. */
+export function findZeroImpressionPages(
+  sitemapUrls: string[],
+  pageRows: SearchAnalyticsRow[],
+): string[] {
+  const seen = new Set(pageRows.map((row) => row.keys[0].replace(/\/$/, '')));
+  return sitemapUrls.filter((url) => !seen.has(url.replace(/\/$/, '')));
+}
+
+/** Inspections that are not cleanly indexed. */
+export function findUnindexed(inspections: InspectionResult[]): InspectionResult[] {
+  return inspections.filter((inspection) => inspection.verdict !== 'PASS');
+}
+
+/** Pages Google canonicalized somewhere other than where we asked — duplicate-content smell. */
+export function findCanonicalMismatches(inspections: InspectionResult[]): InspectionResult[] {
+  return inspections.filter(
+    (inspection) =>
+      inspection.googleCanonical !== null &&
+      inspection.userCanonical !== null &&
+      inspection.googleCanonical !== inspection.userCanonical,
+  );
+}
+
+/** Queries with strong impressions but a CTR well below the position-typical rate. */
+export function findWeakCtr(
+  rows: SearchAnalyticsRow[],
+  options: { minImpressions: number; maxCtr: number },
+): SearchAnalyticsRow[] {
+  return rows
+    .filter(
+      (row) =>
+        row.impressions >= options.minImpressions &&
+        row.position <= 10 &&
+        row.ctr < options.maxCtr,
+    )
+    .sort((a, b) => b.impressions - a.impressions);
+}
+
+/**
+ * How complete an inspection sweep was. `pull.ts` records every URL Inspection
+ * failure in `inspection-errors.json`, so a sweep can cover fewer URLs than the
+ * sitemap lists — in which case every index-health count is a lower bound and
+ * the report has to say so rather than imply a clean bill of health.
+ */
+export function describeInspectionCoverage(counts: { inspected: number; failed: number }): string {
+  const total = counts.inspected + counts.failed;
+  if (counts.failed === 0) {
+    return `Coverage: complete — all ${total} sitemap URLs inspected.`;
+  }
+  return (
+    `Coverage: PARTIAL — ${counts.failed} of ${total} sitemap URLs could not be inspected. ` +
+    `Every count below is a lower bound: an uninspected page may also be unindexed or canonicalized elsewhere.`
+  );
+}
+
+/** Trim a list for display, reporting how much was withheld. */
+export function capList(items: string[], limit: number): { shown: string[]; remaining: number } {
+  return { shown: items.slice(0, limit), remaining: Math.max(0, items.length - limit) };
+}
diff --git a/apps/website/scripts/gsc/report.ts b/apps/website/scripts/gsc/report.ts
new file mode 100644
index 000000000..52167b2ea
--- /dev/null
+++ b/apps/website/scripts/gsc/report.ts
@@ -0,0 +1,150 @@
+// SPDX-License-Identifier: MIT
+import fs from 'node:fs';
+import path from 'node:path';
+import type { InspectionResult, SearchAnalyticsRow } from './api';
+import {
+  capList,
+  describeInspectionCoverage,
+  findCanonicalMismatches,
+  findStrikingDistance,
+  findUnindexed,
+  findWeakCtr,
+  findZeroImpressionPages,
+} from './analysis';
+
+const DIR = path.join(process.cwd(), 'apps', 'website', '.gsc');
+
+/** A URL Inspection call that failed during the pull, as recorded by pull.ts. */
+interface InspectionFailure {
+  url: string;
+  error: string;
+}
+
+function read<T>(name: string): T {
+  return JSON.parse(fs.readFileSync(path.join(DIR, name), 'utf8')) as T;
+}
+
+/** Like `read`, for a file the pull only writes on a partial sweep. Absent is null; nothing else is swallowed. */
+function readOptional<T>(name: string): T | null {
+  try {
+    return read<T>(name);
+  } catch (error) {
+    if ((error as NodeJS.ErrnoException).code === 'ENOENT') {
+      return null;
+    }
+    throw error;
+  }
+}
+
+function table(rows: SearchAnalyticsRow[], headers: string[], limit = 30): string {
+  const head = `| ${headers.join(' | ')} |\n| ${headers.map(() => '---').join(' | ')} |`;
+  const body = rows
+    .slice(0, limit)
+    .map(
+      (row) =>
+        `| ${row.keys.join(' | ')} | ${row.clicks} | ${row.impressions} | ${(row.ctr * 100).toFixed(1)}% | ${row.position.toFixed(1)} |`,
+    )
+    .join('\n');
+  return `${head}\n${body}`;
+}
+
+function main(): void {
+  const meta = read<{ startDate: string; endDate: string }>('meta.json');
+  const queries = read<SearchAnalyticsRow[]>('queries.json');
+  const pages = read<SearchAnalyticsRow[]>('pages.json');
+  const inspections = read<InspectionResult[]>('inspections.json');
+  const failures = readOptional<InspectionFailure[]>('inspection-errors.json') ?? [];
+  // Sitemap inventory = URLs we inspected PLUS URLs we failed to inspect, so a
+  // failed URL still reaches the zero-impression analysis instead of vanishing.
+  const sitemapUrls = [...inspections.map((i) => i.url), ...failures.map((f) => f.url)];
+
+  const totals = queries.reduce(
+    (acc, row) => ({
+      clicks: acc.clicks + row.clicks,
+      impressions: acc.impressions + row.impressions,
+    }),
+    { clicks: 0, impressions: 0 },
+  );
+
+  const unindexed = findUnindexed(inspections);
+  const mismatches = findCanonicalMismatches(inspections);
+  const orphans = findZeroImpressionPages(sitemapUrls, pages);
+  const failed = capList(
+    failures.map((failure) => `${failure.url} — ${failure.error}`),
+    20,
+  );
+
+  const report = [
+    `# threadplane.ai — Search Console report`,
+    ``,
+    `Window: ${meta.startDate} → ${meta.endDate}. Total clicks ${totals.clicks}, impressions ${totals.impressions}.`,
+    ``,
+    `> Google's AI Overviews / AI Mode impressions are NOT included — that report is UI-only.`,
+    `> See docs/gtm/ai-search-measurement.md.`,
+    ``,
+    `## Index health`,
+    ``,
+    describeInspectionCoverage({ inspected: inspections.length, failed: failures.length }),
+    ``,
+    `- Sitemap URLs inspected: ${inspections.length}`,
+    `- Inspections that failed: ${failures.length}`,
+    `- Not cleanly indexed: ${unindexed.length}`,
+    `- Google canonical ≠ our canonical: ${mismatches.length}`,
+    `- Zero-impression pages in window: ${orphans.length}`,
+    ``,
+    ...(failures.length > 0
+      ? [
+          `### Failed inspections`,
+          ``,
+          failed.shown.map((line) => `- ${line}`).join('\n'),
+          ...(failed.remaining > 0 ? [``, `_…and ${failed.remaining} more._`] : []),
+          ``,
+        ]
+      : []),
+    `### Not indexed`,
+    ``,
+    unindexed.length ? unindexed.map((i) => `- ${i.url} — ${i.coverageState}`).join('\n') : '_none_',
+    ``,
+    `### Canonical mismatches`,
+    ``,
+    mismatches.length
+      ? mismatches.map((i) => `- ${i.url} → Google chose ${i.googleCanonical}`).join('\n')
+      : '_none_',
+    ``,
+    `### Zero-impression pages`,
+    ``,
+    orphans.length ? orphans.map((url) => `- ${url}`).join('\n') : '_none_',
+    ``,
+    `## Striking distance (position 5–20, ≥50 impressions)`,
+    ``,
+    table(findStrikingDistance(queries, { minImpressions: 50 }), [
+      'Query',
+      'Clicks',
+      'Impr',
+      'CTR',
+      'Pos',
+    ]),
+    ``,
+    `## Weak CTR on page one (≥100 impressions, CTR < 2%)`,
+    ``,
+    `Title/description rewrite candidates.`,
+    ``,
+    table(findWeakCtr(queries, { minImpressions: 100, maxCtr: 0.02 }), [
+      'Query',
+      'Clicks',
+      'Impr',
+      'CTR',
+      'Pos',
+    ]),
+    ``,
+    `## Top pages`,
+    ``,
+    table(pages.slice(0, 30), ['Page', 'Clicks', 'Impr', 'CTR', 'Pos']),
+    ``,
+  ].join('\n');
+
+  fs.writeFileSync(path.join(DIR, 'report.md'), report);
+  console.log('wrote .gsc/report.md');
+}
+
+main();
diff --git a/apps/website/vite.config.mts b/apps/website/vite.config.mts
index 29ba3befa..2fd9a3a69 100644
--- a/apps/website/vite.config.mts
+++ b/apps/website/vite.config.mts
@@ -10,6 +10,6 @@ export default defineConfig({
   test: {
     environment: 'jsdom',
     globals: true,
-    include: ['src/**/*.spec.ts', 'src/**/*.spec.tsx'],
+    include: ['src/**/*.spec.ts', 'src/**/*.spec.tsx', 'scripts/**/*.spec.ts'],
   },
 });
diff --git a/package.json b/package.json
index a1bb71ae0..f413e66b6 100644
--- a/package.json
+++ b/package.json
@@ -4,6 +4,8 @@
   "license": "MIT",
   "scripts": {
     "postinstall": "node libs/licensing/scripts/generate-public-key.mjs",
+    "gsc:pull": "npx tsx apps/website/scripts/gsc/pull.ts",
+    "gsc:report": "npx tsx apps/website/scripts/gsc/report.ts",
     "generate-agent-context": "npx tsx --tsconfig apps/website/tsconfig.json apps/website/scripts/generate-agent-context.ts",
     "generate-api-docs": "npx tsx apps/website/scripts/generate-api-docs.ts",
     "generate-narrative-docs": "npx tsx apps/website/scripts/generate-narrative-docs.ts",

From c7cd9078485c8d44f3997a4a24f201a84fd9704e Mon Sep 17 00:00:00 2001
From: Brian Love <brian@liveloveapp.com>
Date: Thu, 20 Aug 2026 12:13:24 -0700
Subject: [PATCH 08/35] test(website): cover analysis boundaries and harden the
 gsc report

Tests: real ordering assertions for findStrikingDistance and findWeakCtr
(the previous one-row fixture passed with .sort() deleted), table-driven
filter boundaries including the inclusive/exclusive asymmetry between
impressions and ctr, and first coverage for findCanonicalMismatches and
findWeakCtr. The both-canonicals-required policy is now pinned by test
and stated in the doc comment.

Report: InspectionFailure moves to api.ts so the pull/report
serialization contract is declared once; snapshot reads report a missing
or corrupt file by name and point at the pull instead of throwing a raw
ENOENT, with readOptional keeping its own existence check so genuine
absence stays distinguishable; URL comparison normalizes protocol, host
case, www, fragment and query string so a tagged URL is no longer
reported as a page with zero impressions; all four bullet lists are
capped, not just the failures.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
---
 apps/website/scripts/gsc/README.md         |  17 ++-
 apps/website/scripts/gsc/analysis.spec.ts  | 142 +++++++++++++++++++++
 apps/website/scripts/gsc/analysis.ts       |  52 +++++++-
 apps/website/scripts/gsc/api.ts            |  11 ++
 apps/website/scripts/gsc/pull.ts           |  13 +-
 apps/website/scripts/gsc/report.ts         | 103 +++++++--------
 apps/website/scripts/gsc/snapshots.spec.ts |  48 +++++++
 apps/website/scripts/gsc/snapshots.ts      |  41 ++++++
 8 files changed, 360 insertions(+), 67 deletions(-)
 create mode 100644 apps/website/scripts/gsc/snapshots.spec.ts
 create mode 100644 apps/website/scripts/gsc/snapshots.ts

diff --git a/apps/website/scripts/gsc/README.md b/apps/website/scripts/gsc/README.md
index e1763375b..b82898740 100644
--- a/apps/website/scripts/gsc/README.md
+++ b/apps/website/scripts/gsc/README.md
@@ -17,8 +17,21 @@
 
 ## Usage
 
-    npx tsx apps/website/scripts/gsc/pull.ts        # writes apps/website/.gsc/*.json
-    npx tsx apps/website/scripts/gsc/report.ts      # writes apps/website/.gsc/report.md
+    npm run gsc:pull      # writes apps/website/.gsc/*.json
+    npm run gsc:report    # writes apps/website/.gsc/report.md
+
+`gsc:report` reads the snapshots `gsc:pull` wrote, so run the pull first.
+
+Both scripts resolve their `.gsc` directory relative to the current working
+directory (`<cwd>/apps/website/.gsc`), so the raw form must be invoked from the
+repo root:
+
+    npx tsx apps/website/scripts/gsc/pull.ts
+    npx tsx apps/website/scripts/gsc/report.ts
+
+If the URL Inspection sweep hits quota or transient errors, `pull.ts` also
+writes `.gsc/inspection-errors.json` and the report labels its index-health
+counts as lower bounds.
 
 ## What this CANNOT do
 
diff --git a/apps/website/scripts/gsc/analysis.spec.ts b/apps/website/scripts/gsc/analysis.spec.ts
index 4e048f457..91cbe7487 100644
--- a/apps/website/scripts/gsc/analysis.spec.ts
+++ b/apps/website/scripts/gsc/analysis.spec.ts
@@ -1,12 +1,42 @@
 import { describe, expect, it } from 'vitest';
+import type { InspectionResult } from './api';
 import {
   capList,
   describeInspectionCoverage,
+  findCanonicalMismatches,
   findStrikingDistance,
   findUnindexed,
+  findWeakCtr,
   findZeroImpressionPages,
+  normalizeUrl,
 } from './analysis';
 
+/** A row with sane defaults, so each test states only the field it is about. */
+function row(overrides: Partial<{ key: string; clicks: number; impressions: number; ctr: number; position: number }>) {
+  return {
+    keys: [overrides.key ?? 'q'],
+    clicks: overrides.clicks ?? 0,
+    impressions: overrides.impressions ?? 500,
+    ctr: overrides.ctr ?? 0,
+    position: overrides.position ?? 8,
+  };
+}
+
+/** An inspection with sane defaults, so each test states only the field it is about. */
+function inspection(overrides: Partial<InspectionResult>): InspectionResult {
+  return {
+    url: 'https://threadplane.ai/a',
+    verdict: 'PASS',
+    coverageState: 'Submitted and indexed',
+    lastCrawlTime: null,
+    robotsTxtState: 'ALLOWED',
+    indexingState: 'INDEXING_ALLOWED',
+    googleCanonical: null,
+    userCanonical: null,
+    ...overrides,
+  };
+}
+
 const rows = [
   { keys: ['angular langgraph chat'], clicks: 0, impressions: 400, ctr: 0, position: 11.2 },
   { keys: ['threadplane'], clicks: 90, impressions: 100, ctr: 0.9, position: 1.1 },
@@ -18,6 +48,102 @@ describe('findStrikingDistance', () => {
     const result = findStrikingDistance(rows, { minImpressions: 50 });
     expect(result.map((r) => r.keys[0])).toEqual(['angular langgraph chat']);
   });
+
+  it('orders surviving rows by descending impressions, not input order', () => {
+    const result = findStrikingDistance(
+      [
+        row({ key: 'middle', impressions: 200 }),
+        row({ key: 'smallest', impressions: 60 }),
+        row({ key: 'biggest', impressions: 900 }),
+      ],
+      { minImpressions: 50 },
+    );
+    expect(result.map((r) => r.keys[0])).toEqual(['biggest', 'middle', 'smallest']);
+  });
+
+  it.each([
+    ['position exactly 5 is included', { position: 5 }, true],
+    ['position exactly 20 is included', { position: 20 }, true],
+    ['position just above page one at 4.9 is excluded', { position: 4.9 }, false],
+    ['position just past 20 at 20.1 is excluded', { position: 20.1 }, false],
+    ['impressions exactly at the floor are included', { impressions: 50 }, true],
+    ['impressions one below the floor are excluded', { impressions: 49 }, false],
+  ])('%s', (_name, overrides, kept) => {
+    const result = findStrikingDistance([row(overrides)], { minImpressions: 50 });
+    expect(result).toHaveLength(kept ? 1 : 0);
+  });
+});
+
+describe('findWeakCtr', () => {
+  it('orders surviving rows by descending impressions', () => {
+    const result = findWeakCtr(
+      [
+        row({ key: 'fewer', impressions: 150, ctr: 0.01, position: 3 }),
+        row({ key: 'more', impressions: 800, ctr: 0.01, position: 3 }),
+      ],
+      { minImpressions: 100, maxCtr: 0.02 },
+    );
+    expect(result.map((r) => r.keys[0])).toEqual(['more', 'fewer']);
+  });
+
+  it.each([
+    ['position exactly 10 is included', { position: 10, ctr: 0.01 }, true],
+    ['position 10.1 is off page one and excluded', { position: 10.1, ctr: 0.01 }, false],
+    ['impressions exactly at the floor are included', { impressions: 100, ctr: 0.01 }, true],
+    ['impressions one below the floor are excluded', { impressions: 99, ctr: 0.01 }, false],
+    ['ctr exactly at the ceiling is EXCLUDED — the bound is strict', { ctr: 0.02 }, false],
+    ['ctr just under the ceiling is included', { ctr: 0.0199 }, true],
+  ])('%s', (_name, overrides, kept) => {
+    const result = findWeakCtr([row({ position: 3, impressions: 500, ...overrides })], {
+      minImpressions: 100,
+      maxCtr: 0.02,
+    });
+    expect(result).toHaveLength(kept ? 1 : 0);
+  });
+});
+
+describe('findCanonicalMismatches', () => {
+  it('flags a page Google canonicalized away from our declared canonical', () => {
+    const result = findCanonicalMismatches([
+      inspection({
+        url: 'https://threadplane.ai/pricing',
+        googleCanonical: 'https://threadplane.ai/plans',
+        userCanonical: 'https://threadplane.ai/pricing',
+      }),
+    ]);
+    expect(result.map((i) => i.url)).toEqual(['https://threadplane.ai/pricing']);
+  });
+
+  it.each([
+    ['both canonicals absent', null, null],
+    ['Google reports one but we declared none — deliberately NOT a mismatch', '/g', null],
+    ['we declared one but Google reports none', null, '/u'],
+    ['both present and in agreement', '/same', '/same'],
+  ])('does not flag when %s', (_name, googleCanonical, userCanonical) => {
+    expect(findCanonicalMismatches([inspection({ googleCanonical, userCanonical })])).toEqual([]);
+  });
+});
+
+describe('normalizeUrl', () => {
+  it.each([
+    ['protocol differs', 'http://threadplane.ai/blog/foo', 'https://threadplane.ai/blog/foo'],
+    ['host case differs', 'https://ThreadPlane.AI/blog/foo', 'https://threadplane.ai/blog/foo'],
+    ['leading www differs', 'https://www.threadplane.ai/blog/foo', 'https://threadplane.ai/blog/foo'],
+    ['trailing slash differs', 'https://threadplane.ai/blog/foo/', 'https://threadplane.ai/blog/foo'],
+    ['a fragment is present', 'https://threadplane.ai/blog/foo#intro', 'https://threadplane.ai/blog/foo'],
+    ['a query string is present', 'https://threadplane.ai/blog/foo?ref=x', 'https://threadplane.ai/blog/foo'],
+  ])('treats two URLs as the same page when %s', (_name, a, b) => {
+    expect(normalizeUrl(a)).toBe(normalizeUrl(b));
+  });
+
+  it('keeps genuinely different paths apart', () => {
+    expect(normalizeUrl('https://threadplane.ai/a')).not.toBe(normalizeUrl('https://threadplane.ai/b'));
+  });
+
+  it('falls back to a textual cleanup instead of throwing on unparseable input', () => {
+    expect(normalizeUrl('  not a url?ref=x  ')).toBe('not a url');
+    expect(normalizeUrl('')).toBe('');
+  });
 });
 
 describe('findZeroImpressionPages', () => {
@@ -28,6 +154,22 @@ describe('findZeroImpressionPages', () => {
     );
     expect(result).toEqual(['https://threadplane.ai/b']);
   });
+
+  it('does not report a page as invisible just because Search Console tagged the URL', () => {
+    const result = findZeroImpressionPages(
+      ['https://threadplane.ai/blog/foo'],
+      [
+        {
+          keys: ['https://www.threadplane.ai/blog/foo/?ref=newsletter#top'],
+          clicks: 4,
+          impressions: 90,
+          ctr: 0.044,
+          position: 6,
+        },
+      ],
+    );
+    expect(result).toEqual([]);
+  });
 });
 
 describe('findUnindexed', () => {
diff --git a/apps/website/scripts/gsc/analysis.ts b/apps/website/scripts/gsc/analysis.ts
index 9c834bc14..6c8f8b980 100644
--- a/apps/website/scripts/gsc/analysis.ts
+++ b/apps/website/scripts/gsc/analysis.ts
@@ -14,13 +14,41 @@ export function findStrikingDistance(
     .sort((a, b) => b.impressions - a.impressions);
 }
 
+/**
+ * Reduce a URL to the identity we compare on: no protocol, no `www.`, lowercased
+ * host, no trailing slash, no fragment, and NO QUERY STRING.
+ *
+ * Dropping the query string is a judgement call. Search Console's `page`
+ * dimension reports campaign- and referral-tagged URLs (`/blog/foo?ref=x`)
+ * that never appear in sitemap `<loc>` entries, and treating those as separate
+ * pages would report a page with real impressions as invisible. The cost is
+ * that a site where the query string genuinely selects content (`?page=2`,
+ * `?id=`) would collapse distinct pages together; threadplane.ai has no such
+ * routes. Total function — unparseable input falls back to a textual cleanup
+ * rather than throwing, since a single odd row must not kill the report.
+ */
+export function normalizeUrl(raw: string): string {
+  const trimmed = raw.trim();
+  try {
+    const url = new URL(trimmed);
+    return `${url.hostname.toLowerCase().replace(/^www\./, '')}${url.pathname.replace(/\/$/, '')}`;
+  } catch {
+    return trimmed
+      .toLowerCase()
+      .replace(/^[a-z][a-z0-9+.-]*:\/\//, '')
+      .replace(/^www\./, '')
+      .replace(/[?#].*$/, '')
+      .replace(/\/$/, '');
+  }
+}
+
 /** Sitemap URLs Google never showed for anything in the window. */
 export function findZeroImpressionPages(
   sitemapUrls: string[],
   pageRows: SearchAnalyticsRow[],
 ): string[] {
-  const seen = new Set(pageRows.map((row) => row.keys[0].replace(/\/$/, '')));
-  return sitemapUrls.filter((url) => !seen.has(url.replace(/\/$/, '')));
+  const seen = new Set(pageRows.map((row) => normalizeUrl(row.keys[0])));
+  return sitemapUrls.filter((url) => !seen.has(normalizeUrl(url)));
 }
 
 /** Inspections that are not cleanly indexed. */
@@ -28,7 +56,15 @@ export function findUnindexed(inspections: InspectionResult[]): InspectionResult
   return inspections.filter((inspection) => inspection.verdict !== 'PASS');
 }
 
-/** Pages Google canonicalized somewhere other than where we asked — duplicate-content smell. */
+/**
+ * Pages Google canonicalized somewhere other than where we asked — duplicate-content smell.
+ *
+ * Policy: BOTH canonicals must be present. A page where Google reports a
+ * canonical but `userCanonical` is null (i.e. we emitted no `<link rel=canonical>`)
+ * is deliberately NOT flagged here — it is a finding in its own right, but a
+ * different one, and folding it in would make "mismatch" mean two things. It is
+ * still visible in the raw `.gsc/inspections.json` snapshot.
+ */
 export function findCanonicalMismatches(inspections: InspectionResult[]): InspectionResult[] {
   return inspections.filter(
     (inspection) =>
@@ -38,7 +74,15 @@ export function findCanonicalMismatches(inspections: InspectionResult[]): Inspec
   );
 }
 
-/** Queries with strong impressions but a CTR well below the position-typical rate. */
+/**
+ * Queries with strong impressions that sit on page one yet convert below one
+ * flat CTR threshold.
+ *
+ * Limitation: the threshold does not vary with position, so a 1.9% CTR at
+ * position 1 (alarming) is reported identically to 1.9% at position 10
+ * (unremarkable). Read the Pos column before acting; ranking the output by
+ * position-relative expected CTR would need a baseline curve we do not have.
+ */
 export function findWeakCtr(
   rows: SearchAnalyticsRow[],
   options: { minImpressions: number; maxCtr: number },
diff --git a/apps/website/scripts/gsc/api.ts b/apps/website/scripts/gsc/api.ts
index a15089c7e..15555d73a 100644
--- a/apps/website/scripts/gsc/api.ts
+++ b/apps/website/scripts/gsc/api.ts
@@ -89,6 +89,17 @@ export interface InspectionResult {
   userCanonical: string | null;
 }
 
+/**
+ * A URL Inspection call that failed during a pull. Serialization contract:
+ * `pull.ts` writes these to `.gsc/inspection-errors.json`, `report.ts` reads
+ * them back — so the shape lives here, next to InspectionResult, rather than
+ * being restated at each end.
+ */
+export interface InspectionFailure {
+  url: string;
+  error: string;
+}
+
 export async function inspectUrl(inspectionUrl: string): Promise<InspectionResult> {
   const token = await getAccessToken();
   const raw = (await authedFetch(INSPECT_URL, {
diff --git a/apps/website/scripts/gsc/pull.ts b/apps/website/scripts/gsc/pull.ts
index 23971c178..2d787e6f2 100644
--- a/apps/website/scripts/gsc/pull.ts
+++ b/apps/website/scripts/gsc/pull.ts
@@ -1,7 +1,13 @@
 // SPDX-License-Identifier: MIT
 import fs from 'node:fs';
 import path from 'node:path';
-import { inspectUrl, listSitemaps, querySearchAnalytics, type InspectionResult } from './api';
+import {
+  inspectUrl,
+  listSitemaps,
+  querySearchAnalytics,
+  type InspectionFailure,
+  type InspectionResult,
+} from './api';
 
 const OUT_DIR = path.join(process.cwd(), 'apps', 'website', '.gsc');
 
@@ -29,11 +35,6 @@ async function sitemapUrls(): Promise<string[]> {
   return urls;
 }
 
-interface InspectionFailure {
-  url: string;
-  error: string;
-}
-
 async function main(): Promise<void> {
   // Search Analytics data lags ~2 days; end 3 days back for a stable window.
   const endDate = isoDaysAgo(3);
diff --git a/apps/website/scripts/gsc/report.ts b/apps/website/scripts/gsc/report.ts
index 52167b2ea..34c4565d4 100644
--- a/apps/website/scripts/gsc/report.ts
+++ b/apps/website/scripts/gsc/report.ts
@@ -1,7 +1,7 @@
 // SPDX-License-Identifier: MIT
 import fs from 'node:fs';
 import path from 'node:path';
-import type { InspectionResult, SearchAnalyticsRow } from './api';
+import type { InspectionFailure, InspectionResult, SearchAnalyticsRow } from './api';
 import {
   capList,
   describeInspectionCoverage,
@@ -11,30 +11,12 @@ import {
   findWeakCtr,
   findZeroImpressionPages,
 } from './analysis';
+import { read, readOptional } from './snapshots';
 
 const DIR = path.join(process.cwd(), 'apps', 'website', '.gsc');
 
-/** A URL Inspection call that failed during the pull, as recorded by pull.ts. */
-interface InspectionFailure {
-  url: string;
-  error: string;
-}
-
-function read<T>(name: string): T {
-  return JSON.parse(fs.readFileSync(path.join(DIR, name), 'utf8')) as T;
-}
-
-/** Like `read`, for a file the pull only writes on a partial sweep. Absent is null; nothing else is swallowed. */
-function readOptional<T>(name: string): T | null {
-  try {
-    return read<T>(name);
-  } catch (error) {
-    if ((error as NodeJS.ErrnoException).code === 'ENOENT') {
-      return null;
-    }
-    throw error;
-  }
-}
+/** Longest any bullet list in the report gets before it is trimmed with a count. */
+const LIST_LIMIT = 20;
 
 function table(rows: SearchAnalyticsRow[], headers: string[], limit = 30): string {
   const head = `| ${headers.join(' | ')} |\n| ${headers.map(() => '---').join(' | ')} |`;
@@ -48,12 +30,27 @@ function table(rows: SearchAnalyticsRow[], headers: string[], limit = 30): strin
   return `${head}\n${body}`;
 }
 
+/** A `###` heading over a capped bullet list, or `_none_` when there is nothing to say. */
+function bulletSection(heading: string, items: string[]): string[] {
+  if (items.length === 0) {
+    return [`### ${heading}`, ``, `_none_`, ``];
+  }
+  const { shown, remaining } = capList(items, LIST_LIMIT);
+  return [
+    `### ${heading}`,
+    ``,
+    shown.map((item) => `- ${item}`).join('\n'),
+    ...(remaining > 0 ? [``, `_…and ${remaining} more._`] : []),
+    ``,
+  ];
+}
+
 function main(): void {
-  const meta = read<{ startDate: string; endDate: string }>('meta.json');
-  const queries = read<SearchAnalyticsRow[]>('queries.json');
-  const pages = read<SearchAnalyticsRow[]>('pages.json');
-  const inspections = read<InspectionResult[]>('inspections.json');
-  const failures = readOptional<InspectionFailure[]>('inspection-errors.json') ?? [];
+  const meta = read<{ startDate: string; endDate: string }>(DIR, 'meta.json');
+  const queries = read<SearchAnalyticsRow[]>(DIR, 'queries.json');
+  const pages = read<SearchAnalyticsRow[]>(DIR, 'pages.json');
+  const inspections = read<InspectionResult[]>(DIR, 'inspections.json');
+  const failures = readOptional<InspectionFailure[]>(DIR, 'inspection-errors.json') ?? [];
   // Sitemap inventory = URLs we inspected PLUS URLs we failed to inspect, so a
   // failed URL still reaches the zero-impression analysis instead of vanishing.
   const sitemapUrls = [...inspections.map((i) => i.url), ...failures.map((f) => f.url)];
@@ -69,10 +66,6 @@ function main(): void {
   const unindexed = findUnindexed(inspections);
   const mismatches = findCanonicalMismatches(inspections);
   const orphans = findZeroImpressionPages(sitemapUrls, pages);
-  const failed = capList(
-    failures.map((failure) => `${failure.url} — ${failure.error}`),
-    20,
-  );
 
   const report = [
     `# threadplane.ai — Search Console report`,
@@ -92,29 +85,22 @@ function main(): void {
     `- Google canonical ≠ our canonical: ${mismatches.length}`,
     `- Zero-impression pages in window: ${orphans.length}`,
     ``,
+    // Only rendered on a partial sweep; a clean run should not carry an empty section.
     ...(failures.length > 0
-      ? [
-          `### Failed inspections`,
-          ``,
-          failed.shown.map((line) => `- ${line}`).join('\n'),
-          ...(failed.remaining > 0 ? [``, `_…and ${failed.remaining} more._`] : []),
-          ``,
-        ]
+      ? bulletSection(
+          'Failed inspections',
+          failures.map((failure) => `${failure.url} — ${failure.error}`),
+        )
       : []),
-    `### Not indexed`,
-    ``,
-    unindexed.length ? unindexed.map((i) => `- ${i.url} — ${i.coverageState}`).join('\n') : '_none_',
-    ``,
-    `### Canonical mismatches`,
-    ``,
-    mismatches.length
-      ? mismatches.map((i) => `- ${i.url} → Google chose ${i.googleCanonical}`).join('\n')
-      : '_none_',
-    ``,
-    `### Zero-impression pages`,
-    ``,
-    orphans.length ? orphans.map((url) => `- ${url}`).join('\n') : '_none_',
-    ``,
+    ...bulletSection(
+      'Not indexed',
+      unindexed.map((i) => `${i.url} — ${i.coverageState}`),
+    ),
+    ...bulletSection(
+      'Canonical mismatches',
+      mismatches.map((i) => `${i.url} → Google chose ${i.googleCanonical}`),
+    ),
+    ...bulletSection('Zero-impression pages', orphans),
     `## Striking distance (position 5–20, ≥50 impressions)`,
     ``,
     table(findStrikingDistance(queries, { minImpressions: 50 }), [
@@ -127,7 +113,7 @@ function main(): void {
     ``,
     `## Weak CTR on page one (≥100 impressions, CTR < 2%)`,
     ``,
-    `Title/description rewrite candidates.`,
+    `Title/description rewrite candidates. The threshold is flat across positions 1–10 — read the Pos column before acting.`,
     ``,
     table(findWeakCtr(queries, { minImpressions: 100, maxCtr: 0.02 }), [
       'Query',
@@ -139,7 +125,7 @@ function main(): void {
     ``,
     `## Top pages`,
     ``,
-    table(pages.slice(0, 30), ['Page', 'Clicks', 'Impr', 'CTR', 'Pos']),
+    table(pages, ['Page', 'Clicks', 'Impr', 'CTR', 'Pos']),
     ``,
   ].join('\n');
 
@@ -147,4 +133,11 @@ function main(): void {
   console.log('wrote .gsc/report.md');
 }
 
-main();
+try {
+  main();
+} catch (error) {
+  // The likely failures here are "you have not run the pull yet" and "a snapshot
+  // is corrupt", both of which read better as one line than as a stack trace.
+  console.error(error instanceof Error ? error.message : String(error));
+  process.exitCode = 1;
+}
diff --git a/apps/website/scripts/gsc/snapshots.spec.ts b/apps/website/scripts/gsc/snapshots.spec.ts
new file mode 100644
index 000000000..886a60254
--- /dev/null
+++ b/apps/website/scripts/gsc/snapshots.spec.ts
@@ -0,0 +1,48 @@
+import fs from 'node:fs';
+import os from 'node:os';
+import path from 'node:path';
+import { afterEach, beforeEach, describe, expect, it } from 'vitest';
+import { read, readOptional } from './snapshots';
+
+let dir: string;
+
+beforeEach(() => {
+  dir = fs.mkdtempSync(path.join(os.tmpdir(), 'gsc-snapshots-'));
+});
+
+afterEach(() => {
+  fs.rmSync(dir, { recursive: true, force: true });
+});
+
+describe('read', () => {
+  it('parses a snapshot file', () => {
+    fs.writeFileSync(path.join(dir, 'meta.json'), '{"startDate":"2026-01-01"}');
+    expect(read<{ startDate: string }>(dir, 'meta.json')).toEqual({ startDate: '2026-01-01' });
+  });
+
+  it('names the missing file and points at the pull instead of throwing ENOENT', () => {
+    expect(() => read(dir, 'queries.json')).toThrow(/Missing snapshot .*queries\.json/);
+    expect(() => read(dir, 'queries.json')).toThrow(/npm run gsc:pull/);
+  });
+
+  it('reports malformed JSON with the offending file', () => {
+    fs.writeFileSync(path.join(dir, 'pages.json'), '{ broken');
+    expect(() => read(dir, 'pages.json')).toThrow(/Malformed JSON in .*pages\.json/);
+  });
+});
+
+describe('readOptional', () => {
+  it('returns null when the file is genuinely absent', () => {
+    expect(readOptional(dir, 'inspection-errors.json')).toBeNull();
+  });
+
+  it('still rethrows on malformed JSON rather than reporting absence', () => {
+    fs.writeFileSync(path.join(dir, 'inspection-errors.json'), '{ broken');
+    expect(() => readOptional(dir, 'inspection-errors.json')).toThrow(/Malformed JSON/);
+  });
+
+  it('parses the file when it is present', () => {
+    fs.writeFileSync(path.join(dir, 'inspection-errors.json'), '[{"url":"u","error":"429"}]');
+    expect(readOptional(dir, 'inspection-errors.json')).toEqual([{ url: 'u', error: '429' }]);
+  });
+});
diff --git a/apps/website/scripts/gsc/snapshots.ts b/apps/website/scripts/gsc/snapshots.ts
new file mode 100644
index 000000000..9b181d6da
--- /dev/null
+++ b/apps/website/scripts/gsc/snapshots.ts
@@ -0,0 +1,41 @@
+// SPDX-License-Identifier: MIT
+import fs from 'node:fs';
+import path from 'node:path';
+
+/**
+ * Read one snapshot file written by `pull.ts`. The overwhelmingly likely error
+ * is running the report before the pull, so say that in the message instead of
+ * surfacing a raw ENOENT stack.
+ */
+export function read<T>(dir: string, name: string): T {
+  const file = path.join(dir, name);
+  let raw: string;
+  try {
+    raw = fs.readFileSync(file, 'utf8');
+  } catch (error) {
+    if ((error as NodeJS.ErrnoException).code === 'ENOENT') {
+      throw new Error(`Missing snapshot ${file}. Run \`npm run gsc:pull\` first.`);
+    }
+    throw error;
+  }
+  try {
+    return JSON.parse(raw) as T;
+  } catch (error) {
+    throw new Error(
+      `Malformed JSON in ${file}: ${(error as Error).message}. Re-run \`npm run gsc:pull\`.`,
+    );
+  }
+}
+
+/**
+ * Like {@link read}, for a file `pull.ts` writes only on a partial sweep.
+ * Genuine absence is `null`; every other failure — malformed JSON, permissions —
+ * still throws. The existence check is deliberate: `read` now reports a missing
+ * file as a friendly Error, so `.code` is no longer available to discriminate on.
+ */
+export function readOptional<T>(dir: string, name: string): T | null {
+  if (!fs.existsSync(path.join(dir, name))) {
+    return null;
+  }
+  return read<T>(dir, name);
+}

From 68f1eece2bcfabd2b41fb317082dc75e346794d2 Mon Sep 17 00:00:00 2001
From: Brian Love <brian@liveloveapp.com>
Date: Thu, 20 Aug 2026 12:14:09 -0700
Subject: [PATCH 09/35] docs(plan): correct website test command (no nx test
 target exists)

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
---
 .../2026-08-20-ai-search-optimization.md      | 24 +++++++++----------
 1 file changed, 12 insertions(+), 12 deletions(-)

diff --git a/docs/superpowers/plans/2026-08-20-ai-search-optimization.md b/docs/superpowers/plans/2026-08-20-ai-search-optimization.md
index 3d56fc8d9..2662b1df6 100644
--- a/docs/superpowers/plans/2026-08-20-ai-search-optimization.md
+++ b/docs/superpowers/plans/2026-08-20-ai-search-optimization.md
@@ -522,7 +522,7 @@ describe('findUnindexed', () => {
 - [ ] **Step 3: Run it and confirm it fails**
 
 ```bash
-npx nx test website
+cd apps/website && npx vitest run --config vite.config.mts
 ```
 
 Expected: FAIL — `Failed to resolve import "./analysis"`.
@@ -593,7 +593,7 @@ export function findWeakCtr(
 - [ ] **Step 5: Run the tests and confirm they pass**
 
 ```bash
-npx nx test website
+cd apps/website && npx vitest run --config vite.config.mts
 ```
 
 Expected: PASS.
@@ -767,7 +767,7 @@ describe('getSitemapEntries', () => {
 - [ ] **Step 2: Run it and confirm it fails**
 
 ```bash
-npx nx test website
+cd apps/website && npx vitest run --config vite.config.mts
 ```
 
 Expected: FAIL — `getSitemapEntries is not a function`.
@@ -839,7 +839,7 @@ export default function sitemap(): MetadataRoute.Sitemap {
 - [ ] **Step 5: Run the tests and confirm they pass**
 
 ```bash
-npx nx test website
+cd apps/website && npx vitest run --config vite.config.mts
 ```
 
 Expected: PASS.
@@ -921,7 +921,7 @@ Add `SITE_NAME` to the existing import list at the top of that spec file.
 - [ ] **Step 2: Run it and confirm it fails**
 
 ```bash
-npx nx test website
+cd apps/website && npx vitest run --config vite.config.mts
 ```
 
 Expected: FAIL — `publishedTime` is `undefined`.
@@ -1043,7 +1043,7 @@ Expected: `0`.
 - [ ] **Step 7: Run the tests and confirm they pass**
 
 ```bash
-npx nx test website
+cd apps/website && npx vitest run --config vite.config.mts
 ```
 
 Expected: PASS.
@@ -1150,7 +1150,7 @@ describe('softwareSourceCodeJsonLd', () => {
 - [ ] **Step 2: Run it and confirm it fails**
 
 ```bash
-npx nx test website
+cd apps/website && npx vitest run --config vite.config.mts
 ```
 
 Expected: FAIL — `Failed to resolve import "./structured-data"`.
@@ -1281,7 +1281,7 @@ export function faqJsonLd(entries: { question: string; answer: string }[]): Json
 - [ ] **Step 4: Run the tests and confirm they pass**
 
 ```bash
-npx nx test website
+cd apps/website && npx vitest run --config vite.config.mts
 ```
 
 Expected: PASS. If `organizationJsonLd` fails on the logo path, run `ls apps/website/public/logos` and use the actual filename.
@@ -1684,7 +1684,7 @@ In `apps/website/src/components/shared/Footer.tsx`, add an `About` link to `/abo
 - [ ] **Step 4: Verify**
 
 ```bash
-npx nx test website && npx nx build website
+cd apps/website && npx vitest run --config vite.config.mts && npx nx build website
 ```
 
 Expected: PASS and a successful build. Then serve and confirm `curl -s http://localhost:3000/about | grep -c 'application/ld+json'` returns `2`.
@@ -1890,7 +1890,7 @@ describe('classifyAiReferrer', () => {
 - [ ] **Step 2: Run it and confirm it fails**
 
 ```bash
-npx nx test website
+cd apps/website && npx vitest run --config vite.config.mts
 ```
 
 Expected: FAIL — `Failed to resolve import "./ai-traffic"`.
@@ -1957,7 +1957,7 @@ export function classifyAiReferrer(referrer: string): string | null {
 - [ ] **Step 4: Run the tests and confirm they pass**
 
 ```bash
-npx nx test website
+cd apps/website && npx vitest run --config vite.config.mts
 ```
 
 Expected: PASS.
@@ -2134,7 +2134,7 @@ git commit -m "docs(gtm): ai search measurement runbook"
 - [ ] **Step 1: Full check**
 
 ```bash
-npx nx test website && npx nx lint website && npx nx build website --configuration=production
+cd apps/website && npx vitest run --config vite.config.mts && npx nx lint website && npx nx build website --configuration=production
 ```
 
 Expected: all three pass. Lint **warnings** are tolerated by CI; lint **errors** are not. To count errors, strip ANSI first — `grep -cE ' error '` on raw output silently returns 0:

From 2c435fc209169a36447742628a946b6b4b556ab0 Mon Sep 17 00:00:00 2001
From: Brian Love <brian@liveloveapp.com>
Date: Thu, 20 Aug 2026 12:15:34 -0700
Subject: [PATCH 10/35] test(website): fix stale positioning proof-point
 assertion

---
 apps/website/src/lib/site-metadata.spec.ts | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/apps/website/src/lib/site-metadata.spec.ts b/apps/website/src/lib/site-metadata.spec.ts
index ffdb37680..5e9db745d 100644
--- a/apps/website/src/lib/site-metadata.spec.ts
+++ b/apps/website/src/lib/site-metadata.spec.ts
@@ -25,7 +25,7 @@ describe('site positioning copy', () => {
       'json-render + A2UI',
     ]);
     expect(POSITIONING_PROOF_POINTS.map((p) => p.href)).toEqual([
-      '/docs/langgraph/concepts/langgraph-basics',
+      '/docs/choosing-an-adapter',
       '/docs/langgraph/guides/persistence',
       '/docs/langgraph/guides/interrupts',
       '/docs/langgraph/guides/subgraphs',

From 87a7979d8bb7fdcf23e77c0f59da2a2bb370ce67 Mon Sep 17 00:00:00 2001
From: Brian Love <brian@liveloveapp.com>
Date: Thu, 20 Aug 2026 12:24:10 -0700
Subject: [PATCH 11/35] feat(website): emit honest lastmod in sitemap

Google ignores changefreq/priority and uses lastmod when it is honest, so
the sitemap now emits only lastmod, derived per route from its real source:
blog frontmatter dates, docs .mdx files, and page.tsx templates (plus the
solutions data module for the programmatic /solutions/* pages).

Times come from git commit history rather than file mtimes: a fresh CI
checkout rewrites every mtime to clone time, which would claim the whole
site changed on every deploy. Shallow clones are detected and their grafted
boundary commits discarded, and any route we cannot date honestly simply
omits lastmod rather than fabricating one.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
---
 apps/website/src/app/sitemap.ts            |  11 +-
 apps/website/src/lib/site-metadata.spec.ts |  35 ++++
 apps/website/src/lib/site-metadata.ts      | 192 +++++++++++++++++++++
 3 files changed, 233 insertions(+), 5 deletions(-)

diff --git a/apps/website/src/app/sitemap.ts b/apps/website/src/app/sitemap.ts
index 3165aabbf..832172709 100644
--- a/apps/website/src/app/sitemap.ts
+++ b/apps/website/src/app/sitemap.ts
@@ -1,10 +1,11 @@
 import type { MetadataRoute } from 'next';
-import { getCanonicalUrl, getSitemapRoutes } from '../lib/site-metadata';
+import { getCanonicalUrl, getSitemapEntries } from '../lib/site-metadata';
 
+// `changefreq`/`priority` are ignored by Google; `lastmod` is used when it is
+// honest, so this emits only that.
 export default function sitemap(): MetadataRoute.Sitemap {
-  return getSitemapRoutes().map((route) => ({
-    url: getCanonicalUrl(route),
-    changeFrequency: route.startsWith('/docs') ? 'weekly' : 'monthly',
-    priority: route === '/' ? 1 : route.startsWith('/docs') ? 0.8 : 0.7,
+  return getSitemapEntries().map((entry) => ({
+    url: getCanonicalUrl(entry.route),
+    ...(entry.lastModified ? { lastModified: entry.lastModified } : {}),
   }));
 }
diff --git a/apps/website/src/lib/site-metadata.spec.ts b/apps/website/src/lib/site-metadata.spec.ts
index 5e9db745d..15380cb98 100644
--- a/apps/website/src/lib/site-metadata.spec.ts
+++ b/apps/website/src/lib/site-metadata.spec.ts
@@ -49,3 +49,38 @@ describe('site positioning copy', () => {
     expect(metadata.twitter?.description).toBe(DEFAULT_META_DESCRIPTION);
   });
 });
+
+describe('getSitemapEntries', () => {
+  it('emits a valid lastModified date for every route', async () => {
+    const { getSitemapEntries } = await import('./site-metadata');
+    const entries = getSitemapEntries();
+    expect(entries.length).toBeGreaterThan(100);
+    const unresolved = entries.filter(
+      (e) => !(e.lastModified instanceof Date) || Number.isNaN(e.lastModified.getTime()),
+    );
+    expect(unresolved.map((e) => e.route)).toEqual([]);
+  });
+
+  it('uses the post date as lastModified for blog routes', async () => {
+    const { getSitemapEntries } = await import('./site-metadata');
+    const entry = getSitemapEntries().find((e) => e.route === '/blog/angular-chat-app-tutorial-with-ag-ui');
+    expect(entry?.lastModified?.toISOString().slice(0, 10)).toBe('2026-08-13');
+  });
+
+  it('derives distinct, non-"now" dates rather than stamping the whole site with build time', async () => {
+    const { getSitemapEntries } = await import('./site-metadata');
+    const entries = getSitemapEntries();
+    const distinct = new Set(entries.map((e) => e.lastModified?.toISOString().slice(0, 10)));
+    expect(distinct.size).toBeGreaterThan(5);
+
+    const docsEntry = entries.find((e) => e.route === '/docs/langgraph/getting-started/introduction');
+    expect(docsEntry?.lastModified).toBeInstanceOf(Date);
+    expect(docsEntry?.lastModified?.getTime()).toBeLessThan(Date.now());
+  });
+
+  it('resolves the special docs pages whose route shape differs from library docs', async () => {
+    const { getSitemapEntries } = await import('./site-metadata');
+    const entry = getSitemapEntries().find((e) => e.route === '/docs/choosing-an-adapter');
+    expect(entry?.lastModified).toBeInstanceOf(Date);
+  });
+});
diff --git a/apps/website/src/lib/site-metadata.ts b/apps/website/src/lib/site-metadata.ts
index 6a5744005..b7d724d26 100644
--- a/apps/website/src/lib/site-metadata.ts
+++ b/apps/website/src/lib/site-metadata.ts
@@ -1,3 +1,6 @@
+import { execFileSync } from 'node:child_process';
+import fs from 'node:fs';
+import path from 'node:path';
 import type { Metadata } from 'next';
 import { getAllSolutionSlugs } from './solutions-data';
 import { docsConfig, specialDocsPages } from './docs-config';
@@ -74,3 +77,192 @@ export function getSitemapRoutes(): string[] {
 
   return [...staticRoutes, ...solutionRoutes, ...docsRoutes, ...specialDocsRoutes, ...blogRoutes];
 }
+
+/** A sitemap URL plus the honest last-modified time of the source it renders from. */
+export interface SitemapEntry {
+  route: string;
+  /**
+   * Omitted when no honest value can be determined. An absent `<lastmod>` is
+   * valid sitemap XML; a fabricated one (e.g. "now" on every build, which is
+   * what raw file mtimes give you on a fresh CI checkout) teaches crawlers to
+   * ignore the signal across the whole site.
+   */
+  lastModified?: Date;
+}
+
+/** Website-relative source paths that a route's content is rendered from. */
+function sourcePathsForRoute(route: string): string[] {
+  const special = specialDocsPages.find((page) => page.path === route);
+  if (special) return [path.join('content', 'docs', special.contentPath)];
+
+  if (route.startsWith('/docs/')) {
+    const [, , library, section, slug] = route.split('/');
+    if (library && section && slug) {
+      return [path.join('content', 'docs', library, section, `${slug}.mdx`)];
+    }
+    // Anything else under /docs is a hand-written route, dated like any other.
+  }
+
+  if (route.startsWith('/solutions/')) {
+    // Programmatic pages: one dynamic route template rendering data from a
+    // single module, so a change to either re-renders the page.
+    return [
+      path.join('src', 'app', 'solutions', '[slug]', 'page.tsx'),
+      path.join('src', 'lib', 'solutions-data.ts'),
+    ];
+  }
+
+  const routeDir = route === '/' ? '' : route.replace(/^\//, '');
+  return [path.join('src', 'app', routeDir, 'page.tsx')];
+}
+
+// `nx build website` and a standalone `next build` disagree about cwd, exactly
+// as `blog.ts` already has to handle.
+const WEBSITE_DIR_CANDIDATES = [path.join(process.cwd(), 'apps', 'website'), process.cwd()];
+
+/** Absolute path for a website-relative source path, or null when it is missing. */
+function resolveSourcePath(relativePath: string): string | null {
+  for (const dir of WEBSITE_DIR_CANDIDATES) {
+    const candidate = path.join(dir, relativePath);
+    if (fs.existsSync(candidate)) return candidate;
+  }
+  return null;
+}
+
+const GIT_LOG_MARKER = 'commit-time ';
+
+interface GitTimes {
+  /** Last commit time (epoch seconds) keyed by website-relative path. */
+  times: Map<string, number>;
+  /**
+   * True when the clone has full history, which is also the only situation in
+   * which a file's absence from `times` means "never committed" (and so its
+   * mtime is a real edit time rather than a checkout timestamp).
+   */
+  complete: boolean;
+}
+
+let gitTimesCache: GitTimes | null | undefined;
+
+/**
+ * Last commit time (epoch seconds) keyed by website-relative path.
+ *
+ * Returns null when git history yields nothing usable (no git, not a repo, or a
+ * clone so shallow that only grafted commits are visible).
+ *
+ * Shallow clones — which is what CI hosts do by default — need care: a grafted
+ * boundary commit has no parent, so `git log --name-only` reports *every* file
+ * in the tree as changed at that commit's timestamp. Those entries are dropped;
+ * files git genuinely saw change in the visible history keep real dates, and
+ * everything older simply gets no `lastmod`.
+ */
+function computeGitTimes(): GitTimes | null {
+  try {
+    const git = (args: string[], cwd: string): string =>
+      execFileSync('git', args, {
+        cwd,
+        encoding: 'utf8',
+        maxBuffer: 64 * 1024 * 1024,
+        stdio: ['ignore', 'pipe', 'ignore'],
+      });
+
+    const root = git(['rev-parse', '--show-toplevel'], process.cwd()).trim();
+    const graftedCommits = new Set<string>();
+    if (git(['rev-parse', '--is-shallow-repository'], root).trim() === 'true') {
+      const shallowFile = path.join(git(['rev-parse', '--absolute-git-dir'], root).trim(), 'shallow');
+      if (!fs.existsSync(shallowFile)) return null;
+      for (const sha of fs.readFileSync(shallowFile, 'utf8').split('\n')) {
+        if (sha.trim()) graftedCommits.add(sha.trim());
+      }
+    }
+
+    const prefix = fs.existsSync(path.join(root, 'apps', 'website')) ? 'apps/website/' : '';
+    const log = git(
+      [
+        'log',
+        `--format=${GIT_LOG_MARKER}%ct %H`,
+        '--name-only',
+        '--',
+        `${prefix}content`,
+        `${prefix}src/app`,
+        `${prefix}src/lib`,
+      ],
+      root,
+    );
+
+    const times = new Map<string, number>();
+    let commitTime = 0;
+    for (const line of log.split('\n')) {
+      if (line.startsWith(GIT_LOG_MARKER)) {
+        const [seconds, sha] = line.slice(GIT_LOG_MARKER.length).split(' ');
+        commitTime = graftedCommits.has(sha) ? 0 : Number(seconds);
+        continue;
+      }
+      const file = line.trim();
+      if (!file || !commitTime) continue;
+      const relative = prefix && file.startsWith(prefix) ? file.slice(prefix.length) : file;
+      // `git log` walks newest-first, so the first mention of a path wins.
+      if (!times.has(relative)) times.set(relative, commitTime);
+    }
+    return times.size > 0 ? { times, complete: graftedCommits.size === 0 } : null;
+  } catch {
+    return null;
+  }
+}
+
+function getGitTimes(): GitTimes | null {
+  if (gitTimesCache !== undefined) return gitTimesCache;
+  gitTimesCache = computeGitTimes();
+
+  if (gitTimesCache === null) {
+    // Visible in the build log: the sitemap will carry `lastmod` only for blog
+    // posts (which date themselves in frontmatter) until history is available.
+    console.warn('[sitemap] git history unavailable; omitting <lastmod> for file-derived routes.');
+  }
+
+  return gitTimesCache;
+}
+
+/**
+ * Newest honest modification time across a route's sources.
+ *
+ * Git commit time is authoritative. A file mtime is only trusted when the clone
+ * has full history and git still has no record of the file — i.e. uncommitted
+ * local work. Without that guard every URL would carry the checkout time, since
+ * a fresh CI clone rewrites every mtime to the moment it ran.
+ */
+function sourceModifiedTime(relativePaths: string[]): Date | undefined {
+  const git = getGitTimes();
+  let newest: number | undefined;
+
+  for (const relativePath of relativePaths) {
+    const absolute = resolveSourcePath(relativePath);
+    if (!absolute) continue;
+
+    const gitSeconds = git?.times.get(relativePath.split(path.sep).join('/'));
+    const millis =
+      gitSeconds !== undefined
+        ? gitSeconds * 1000
+        : git?.complete
+          ? fs.statSync(absolute).mtimeMs
+          : undefined;
+    if (millis === undefined) continue;
+    if (newest === undefined || millis > newest) newest = millis;
+  }
+
+  return newest === undefined ? undefined : new Date(newest);
+}
+
+export function getSitemapEntries(): SitemapEntry[] {
+  const blogDates = new Map(
+    getAllPosts().map((post) => [`/blog/${post.slug}`, new Date(`${post.frontmatter.date}T00:00:00Z`)]),
+  );
+
+  return getSitemapRoutes().map((route) => {
+    const blogDate = blogDates.get(route);
+    if (blogDate && !Number.isNaN(blogDate.getTime())) return { route, lastModified: blogDate };
+
+    const lastModified = sourceModifiedTime(sourcePathsForRoute(route));
+    return lastModified ? { route, lastModified } : { route };
+  });
+}

From 160f84e4a865bc21d0a4da84d0bdffc97ac25fde Mon Sep 17 00:00:00 2001
From: Brian Love <brian@liveloveapp.com>
Date: Thu, 20 Aug 2026 12:32:24 -0700
Subject: [PATCH 12/35] fix(website): detect shallow clones through the common
 git dir

The `shallow` marker lives in the common git dir, not the per-worktree
gitdir, so `--absolute-git-dir` misses it inside a linked worktree
(.git/worktrees/<name> vs .git) and the sitemap silently dropped lastmod
for every file-derived route.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
---
 apps/website/src/lib/site-metadata.ts | 7 ++++++-
 1 file changed, 6 insertions(+), 1 deletion(-)

diff --git a/apps/website/src/lib/site-metadata.ts b/apps/website/src/lib/site-metadata.ts
index b7d724d26..ac1fdc60d 100644
--- a/apps/website/src/lib/site-metadata.ts
+++ b/apps/website/src/lib/site-metadata.ts
@@ -169,7 +169,12 @@ function computeGitTimes(): GitTimes | null {
     const root = git(['rev-parse', '--show-toplevel'], process.cwd()).trim();
     const graftedCommits = new Set<string>();
     if (git(['rev-parse', '--is-shallow-repository'], root).trim() === 'true') {
-      const shallowFile = path.join(git(['rev-parse', '--absolute-git-dir'], root).trim(), 'shallow');
+      // Must be the COMMON git dir, not `--absolute-git-dir`: in a linked
+      // worktree those differ (`.git/worktrees/<name>` vs `.git`) and `shallow`
+      // only ever lives in the common dir. Output can be relative, and git runs
+      // with cwd=root, so resolve it against root.
+      const commonDir = path.resolve(root, git(['rev-parse', '--git-common-dir'], root).trim());
+      const shallowFile = path.join(commonDir, 'shallow');
       if (!fs.existsSync(shallowFile)) return null;
       for (const sha of fs.readFileSync(shallowFile, 'utf8').split('\n')) {
         if (sha.trim()) graftedCommits.add(sha.trim());

From 207e49a928cb2b9be1374f4b57716c018b13d05b Mon Sep 17 00:00:00 2001
From: Brian Love <brian@liveloveapp.com>
Date: Thu, 20 Aug 2026 12:40:39 -0700
Subject: [PATCH 13/35] refactor(website): extract sitemap dates and close
 date-fabrication paths
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Moves the sitemap date logic out of site-metadata.ts into sitemap-dates.ts
and removes the remaining ways a date could be invented:

- Delete the file-mtime fallback. "Not shallow" never implied "committed" —
  a fresh full clone also rewrites every mtime to checkout time, so a single
  lookup miss could publish a build-time lastmod.
- Run git with core.quotePath=false (octal-escaped non-ASCII paths would
  never match a lookup, silently falling through) and log.showSignature=false
  (a user's config could interleave gpg: lines into the file list).
- Bound the subprocess with timeout/SIGKILL so a stalled git cannot hang the
  build; a kill throws and degrades like any other git failure.
- Require a well-formed "<epoch> <sha1>" remainder before treating a line as
  a commit header, and take paths verbatim so leading whitespace survives.

Blog routes now take the later of the frontmatter date and their .mdx commit
time, since lastmod means last modified rather than published.

Extracts parseGitLog as a pure function and unit-tests the degradation the
design rests on — most importantly that a grafted shallow-boundary commit
yields no entry rather than a clone-time one — plus a test pinning the
absence of changeFrequency/priority. Integration tests now tolerate a
history-less checkout instead of asserting completeness unconditionally.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
---
 apps/website/src/app/sitemap.ts            |   3 +-
 apps/website/src/lib/blog.ts               |   8 +-
 apps/website/src/lib/site-metadata.spec.ts |  35 ---
 apps/website/src/lib/site-metadata.ts      | 197 -----------------
 apps/website/src/lib/sitemap-dates.spec.ts | 139 ++++++++++++
 apps/website/src/lib/sitemap-dates.ts      | 242 +++++++++++++++++++++
 apps/website/src/lib/website-dir.ts        |  12 +
 7 files changed, 397 insertions(+), 239 deletions(-)
 create mode 100644 apps/website/src/lib/sitemap-dates.spec.ts
 create mode 100644 apps/website/src/lib/sitemap-dates.ts
 create mode 100644 apps/website/src/lib/website-dir.ts

diff --git a/apps/website/src/app/sitemap.ts b/apps/website/src/app/sitemap.ts
index 832172709..b1c73eb00 100644
--- a/apps/website/src/app/sitemap.ts
+++ b/apps/website/src/app/sitemap.ts
@@ -1,5 +1,6 @@
 import type { MetadataRoute } from 'next';
-import { getCanonicalUrl, getSitemapEntries } from '../lib/site-metadata';
+import { getCanonicalUrl } from '../lib/site-metadata';
+import { getSitemapEntries } from '../lib/sitemap-dates';
 
 // `changefreq`/`priority` are ignored by Google; `lastmod` is used when it is
 // honest, so this emits only that.
diff --git a/apps/website/src/lib/blog.ts b/apps/website/src/lib/blog.ts
index 7c090e85e..8ad405ae6 100644
--- a/apps/website/src/lib/blog.ts
+++ b/apps/website/src/lib/blog.ts
@@ -2,9 +2,7 @@
 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');
+import { resolveWebsiteDir } from './website-dir';
 
 export interface PostFrontmatter {
   title: string;
@@ -27,9 +25,7 @@ export interface Post {
 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;
+  return path.join(resolveWebsiteDir(), 'content', 'blog');
 }
 
 function readPost(dir: string, filename: string): Post | null {
diff --git a/apps/website/src/lib/site-metadata.spec.ts b/apps/website/src/lib/site-metadata.spec.ts
index 15380cb98..5e9db745d 100644
--- a/apps/website/src/lib/site-metadata.spec.ts
+++ b/apps/website/src/lib/site-metadata.spec.ts
@@ -49,38 +49,3 @@ describe('site positioning copy', () => {
     expect(metadata.twitter?.description).toBe(DEFAULT_META_DESCRIPTION);
   });
 });
-
-describe('getSitemapEntries', () => {
-  it('emits a valid lastModified date for every route', async () => {
-    const { getSitemapEntries } = await import('./site-metadata');
-    const entries = getSitemapEntries();
-    expect(entries.length).toBeGreaterThan(100);
-    const unresolved = entries.filter(
-      (e) => !(e.lastModified instanceof Date) || Number.isNaN(e.lastModified.getTime()),
-    );
-    expect(unresolved.map((e) => e.route)).toEqual([]);
-  });
-
-  it('uses the post date as lastModified for blog routes', async () => {
-    const { getSitemapEntries } = await import('./site-metadata');
-    const entry = getSitemapEntries().find((e) => e.route === '/blog/angular-chat-app-tutorial-with-ag-ui');
-    expect(entry?.lastModified?.toISOString().slice(0, 10)).toBe('2026-08-13');
-  });
-
-  it('derives distinct, non-"now" dates rather than stamping the whole site with build time', async () => {
-    const { getSitemapEntries } = await import('./site-metadata');
-    const entries = getSitemapEntries();
-    const distinct = new Set(entries.map((e) => e.lastModified?.toISOString().slice(0, 10)));
-    expect(distinct.size).toBeGreaterThan(5);
-
-    const docsEntry = entries.find((e) => e.route === '/docs/langgraph/getting-started/introduction');
-    expect(docsEntry?.lastModified).toBeInstanceOf(Date);
-    expect(docsEntry?.lastModified?.getTime()).toBeLessThan(Date.now());
-  });
-
-  it('resolves the special docs pages whose route shape differs from library docs', async () => {
-    const { getSitemapEntries } = await import('./site-metadata');
-    const entry = getSitemapEntries().find((e) => e.route === '/docs/choosing-an-adapter');
-    expect(entry?.lastModified).toBeInstanceOf(Date);
-  });
-});
diff --git a/apps/website/src/lib/site-metadata.ts b/apps/website/src/lib/site-metadata.ts
index ac1fdc60d..6a5744005 100644
--- a/apps/website/src/lib/site-metadata.ts
+++ b/apps/website/src/lib/site-metadata.ts
@@ -1,6 +1,3 @@
-import { execFileSync } from 'node:child_process';
-import fs from 'node:fs';
-import path from 'node:path';
 import type { Metadata } from 'next';
 import { getAllSolutionSlugs } from './solutions-data';
 import { docsConfig, specialDocsPages } from './docs-config';
@@ -77,197 +74,3 @@ export function getSitemapRoutes(): string[] {
 
   return [...staticRoutes, ...solutionRoutes, ...docsRoutes, ...specialDocsRoutes, ...blogRoutes];
 }
-
-/** A sitemap URL plus the honest last-modified time of the source it renders from. */
-export interface SitemapEntry {
-  route: string;
-  /**
-   * Omitted when no honest value can be determined. An absent `<lastmod>` is
-   * valid sitemap XML; a fabricated one (e.g. "now" on every build, which is
-   * what raw file mtimes give you on a fresh CI checkout) teaches crawlers to
-   * ignore the signal across the whole site.
-   */
-  lastModified?: Date;
-}
-
-/** Website-relative source paths that a route's content is rendered from. */
-function sourcePathsForRoute(route: string): string[] {
-  const special = specialDocsPages.find((page) => page.path === route);
-  if (special) return [path.join('content', 'docs', special.contentPath)];
-
-  if (route.startsWith('/docs/')) {
-    const [, , library, section, slug] = route.split('/');
-    if (library && section && slug) {
-      return [path.join('content', 'docs', library, section, `${slug}.mdx`)];
-    }
-    // Anything else under /docs is a hand-written route, dated like any other.
-  }
-
-  if (route.startsWith('/solutions/')) {
-    // Programmatic pages: one dynamic route template rendering data from a
-    // single module, so a change to either re-renders the page.
-    return [
-      path.join('src', 'app', 'solutions', '[slug]', 'page.tsx'),
-      path.join('src', 'lib', 'solutions-data.ts'),
-    ];
-  }
-
-  const routeDir = route === '/' ? '' : route.replace(/^\//, '');
-  return [path.join('src', 'app', routeDir, 'page.tsx')];
-}
-
-// `nx build website` and a standalone `next build` disagree about cwd, exactly
-// as `blog.ts` already has to handle.
-const WEBSITE_DIR_CANDIDATES = [path.join(process.cwd(), 'apps', 'website'), process.cwd()];
-
-/** Absolute path for a website-relative source path, or null when it is missing. */
-function resolveSourcePath(relativePath: string): string | null {
-  for (const dir of WEBSITE_DIR_CANDIDATES) {
-    const candidate = path.join(dir, relativePath);
-    if (fs.existsSync(candidate)) return candidate;
-  }
-  return null;
-}
-
-const GIT_LOG_MARKER = 'commit-time ';
-
-interface GitTimes {
-  /** Last commit time (epoch seconds) keyed by website-relative path. */
-  times: Map<string, number>;
-  /**
-   * True when the clone has full history, which is also the only situation in
-   * which a file's absence from `times` means "never committed" (and so its
-   * mtime is a real edit time rather than a checkout timestamp).
-   */
-  complete: boolean;
-}
-
-let gitTimesCache: GitTimes | null | undefined;
-
-/**
- * Last commit time (epoch seconds) keyed by website-relative path.
- *
- * Returns null when git history yields nothing usable (no git, not a repo, or a
- * clone so shallow that only grafted commits are visible).
- *
- * Shallow clones — which is what CI hosts do by default — need care: a grafted
- * boundary commit has no parent, so `git log --name-only` reports *every* file
- * in the tree as changed at that commit's timestamp. Those entries are dropped;
- * files git genuinely saw change in the visible history keep real dates, and
- * everything older simply gets no `lastmod`.
- */
-function computeGitTimes(): GitTimes | null {
-  try {
-    const git = (args: string[], cwd: string): string =>
-      execFileSync('git', args, {
-        cwd,
-        encoding: 'utf8',
-        maxBuffer: 64 * 1024 * 1024,
-        stdio: ['ignore', 'pipe', 'ignore'],
-      });
-
-    const root = git(['rev-parse', '--show-toplevel'], process.cwd()).trim();
-    const graftedCommits = new Set<string>();
-    if (git(['rev-parse', '--is-shallow-repository'], root).trim() === 'true') {
-      // Must be the COMMON git dir, not `--absolute-git-dir`: in a linked
-      // worktree those differ (`.git/worktrees/<name>` vs `.git`) and `shallow`
-      // only ever lives in the common dir. Output can be relative, and git runs
-      // with cwd=root, so resolve it against root.
-      const commonDir = path.resolve(root, git(['rev-parse', '--git-common-dir'], root).trim());
-      const shallowFile = path.join(commonDir, 'shallow');
-      if (!fs.existsSync(shallowFile)) return null;
-      for (const sha of fs.readFileSync(shallowFile, 'utf8').split('\n')) {
-        if (sha.trim()) graftedCommits.add(sha.trim());
-      }
-    }
-
-    const prefix = fs.existsSync(path.join(root, 'apps', 'website')) ? 'apps/website/' : '';
-    const log = git(
-      [
-        'log',
-        `--format=${GIT_LOG_MARKER}%ct %H`,
-        '--name-only',
-        '--',
-        `${prefix}content`,
-        `${prefix}src/app`,
-        `${prefix}src/lib`,
-      ],
-      root,
-    );
-
-    const times = new Map<string, number>();
-    let commitTime = 0;
-    for (const line of log.split('\n')) {
-      if (line.startsWith(GIT_LOG_MARKER)) {
-        const [seconds, sha] = line.slice(GIT_LOG_MARKER.length).split(' ');
-        commitTime = graftedCommits.has(sha) ? 0 : Number(seconds);
-        continue;
-      }
-      const file = line.trim();
-      if (!file || !commitTime) continue;
-      const relative = prefix && file.startsWith(prefix) ? file.slice(prefix.length) : file;
-      // `git log` walks newest-first, so the first mention of a path wins.
-      if (!times.has(relative)) times.set(relative, commitTime);
-    }
-    return times.size > 0 ? { times, complete: graftedCommits.size === 0 } : null;
-  } catch {
-    return null;
-  }
-}
-
-function getGitTimes(): GitTimes | null {
-  if (gitTimesCache !== undefined) return gitTimesCache;
-  gitTimesCache = computeGitTimes();
-
-  if (gitTimesCache === null) {
-    // Visible in the build log: the sitemap will carry `lastmod` only for blog
-    // posts (which date themselves in frontmatter) until history is available.
-    console.warn('[sitemap] git history unavailable; omitting <lastmod> for file-derived routes.');
-  }
-
-  return gitTimesCache;
-}
-
-/**
- * Newest honest modification time across a route's sources.
- *
- * Git commit time is authoritative. A file mtime is only trusted when the clone
- * has full history and git still has no record of the file — i.e. uncommitted
- * local work. Without that guard every URL would carry the checkout time, since
- * a fresh CI clone rewrites every mtime to the moment it ran.
- */
-function sourceModifiedTime(relativePaths: string[]): Date | undefined {
-  const git = getGitTimes();
-  let newest: number | undefined;
-
-  for (const relativePath of relativePaths) {
-    const absolute = resolveSourcePath(relativePath);
-    if (!absolute) continue;
-
-    const gitSeconds = git?.times.get(relativePath.split(path.sep).join('/'));
-    const millis =
-      gitSeconds !== undefined
-        ? gitSeconds * 1000
-        : git?.complete
-          ? fs.statSync(absolute).mtimeMs
-          : undefined;
-    if (millis === undefined) continue;
-    if (newest === undefined || millis > newest) newest = millis;
-  }
-
-  return newest === undefined ? undefined : new Date(newest);
-}
-
-export function getSitemapEntries(): SitemapEntry[] {
-  const blogDates = new Map(
-    getAllPosts().map((post) => [`/blog/${post.slug}`, new Date(`${post.frontmatter.date}T00:00:00Z`)]),
-  );
-
-  return getSitemapRoutes().map((route) => {
-    const blogDate = blogDates.get(route);
-    if (blogDate && !Number.isNaN(blogDate.getTime())) return { route, lastModified: blogDate };
-
-    const lastModified = sourceModifiedTime(sourcePathsForRoute(route));
-    return lastModified ? { route, lastModified } : { route };
-  });
-}
diff --git a/apps/website/src/lib/sitemap-dates.spec.ts b/apps/website/src/lib/sitemap-dates.spec.ts
new file mode 100644
index 000000000..bdc7f2eb2
--- /dev/null
+++ b/apps/website/src/lib/sitemap-dates.spec.ts
@@ -0,0 +1,139 @@
+import { describe, expect, it } from 'vitest';
+import sitemap from '../app/sitemap';
+import { getSitemapEntries, hasGitHistory, parseGitLog } from './sitemap-dates';
+
+const SHA_A = 'a'.repeat(40);
+const SHA_B = 'b'.repeat(40);
+const GRAFT = 'c'.repeat(40);
+
+function header(seconds: number, sha: string): string {
+  return `commit-time ${seconds} ${sha}`;
+}
+
+describe('parseGitLog', () => {
+  it('takes the newest commit that touched each path', () => {
+    const log = [
+      header(3000, SHA_A),
+      'apps/website/content/docs/a.mdx',
+      '',
+      header(1000, SHA_B),
+      'apps/website/content/docs/a.mdx',
+      'apps/website/content/docs/b.mdx',
+      '',
+    ].join('\n');
+
+    const times = parseGitLog(log, 'apps/website/', new Set());
+
+    expect(Object.fromEntries(times)).toEqual({ 'content/docs/a.mdx': 3000, 'content/docs/b.mdx': 1000 });
+  });
+
+  it('drops every file a grafted shallow-boundary commit claims to have changed', () => {
+    const log = [header(9000, GRAFT), 'content/docs/a.mdx', 'content/docs/b.mdx', ''].join('\n');
+
+    const times = parseGitLog(log, '', new Set([GRAFT]));
+
+    // Not "dated 9000" — a graft reports the whole tree, so those dates are
+    // clone time, not change time, and must not be emitted at all.
+    expect(times.size).toBe(0);
+  });
+
+  it('keeps real commits in a stream that also contains a graft', () => {
+    const log = [
+      header(4000, SHA_A),
+      'content/docs/a.mdx',
+      '',
+      header(9000, GRAFT),
+      'content/docs/a.mdx',
+      'content/docs/b.mdx',
+      '',
+    ].join('\n');
+
+    const times = parseGitLog(log, '', new Set([GRAFT]));
+
+    expect(Object.fromEntries(times)).toEqual({ 'content/docs/a.mdx': 4000 });
+  });
+
+  it('handles a merge commit that lists no files', () => {
+    const log = [header(5000, SHA_A), '', header(4000, SHA_B), 'content/docs/a.mdx', ''].join('\n');
+
+    expect(Object.fromEntries(parseGitLog(log, '', new Set()))).toEqual({ 'content/docs/a.mdx': 4000 });
+  });
+
+  it('takes paths verbatim, including non-ASCII and leading whitespace', () => {
+    const log = [header(7000, SHA_A), 'content/blog/café niño.mdx', ' leading-space.mdx', ''].join('\n');
+
+    expect(Object.fromEntries(parseGitLog(log, '', new Set()))).toEqual({
+      'content/blog/café niño.mdx': 7000,
+      ' leading-space.mdx': 7000,
+    });
+  });
+
+  it('treats a path that begins with the marker text as a path, not a header', () => {
+    const log = [header(8000, SHA_A), 'commit-time notes.mdx', 'commit-time 123 nonsense', ''].join('\n');
+
+    expect(Object.fromEntries(parseGitLog(log, '', new Set()))).toEqual({
+      'commit-time notes.mdx': 8000,
+      'commit-time 123 nonsense': 8000,
+    });
+  });
+
+  it('ignores files listed before any commit header', () => {
+    expect(parseGitLog('stray.mdx\n', '', new Set()).size).toBe(0);
+  });
+});
+
+describe('getSitemapEntries', () => {
+  it('covers every sitemap route with a valid date, or none at all', () => {
+    const entries = getSitemapEntries();
+    expect(entries.length).toBeGreaterThan(100);
+
+    const invalid = entries.filter((e) => e.lastModified !== undefined && Number.isNaN(e.lastModified.getTime()));
+    expect(invalid.map((e) => e.route)).toEqual([]);
+
+    const unresolved = entries.filter((e) => !e.lastModified);
+    if (hasGitHistory()) {
+      // A full checkout can date everything; anything missing is a mapping bug.
+      expect(unresolved.map((e) => e.route)).toEqual([]);
+    } else {
+      // Degraded environment (no git, or shallow): blog posts still date
+      // themselves from frontmatter, and nothing is fabricated.
+      expect(entries.filter((e) => e.lastModified).every((e) => e.route.startsWith('/blog/'))).toBe(true);
+    }
+  });
+
+  it('dates a blog route no earlier than its publish date', () => {
+    const entry = getSitemapEntries().find((e) => e.route === '/blog/angular-chat-app-tutorial-with-ag-ui');
+    expect(entry?.lastModified).toBeInstanceOf(Date);
+    // lastmod is last *modified*: the post's own file may have been edited after
+    // it was published, never before.
+    expect(entry?.lastModified?.getTime()).toBeGreaterThanOrEqual(Date.parse('2026-08-13T00:00:00Z'));
+  });
+
+  it('never claims a route changed in the future', () => {
+    const now = Date.now();
+    const future = getSitemapEntries().filter((e) => (e.lastModified?.getTime() ?? 0) > now);
+    expect(future.map((e) => e.route)).toEqual([]);
+  });
+
+  it('resolves the special docs pages whose route shape differs from library docs', () => {
+    const entry = getSitemapEntries().find((e) => e.route === '/docs/choosing-an-adapter');
+    if (hasGitHistory()) expect(entry?.lastModified).toBeInstanceOf(Date);
+  });
+});
+
+describe('sitemap route', () => {
+  it('emits lastModified only — Google ignores changefreq and priority', () => {
+    const urls = sitemap();
+    expect(urls.length).toBeGreaterThan(100);
+
+    for (const url of urls) {
+      expect(url.url.startsWith('https://')).toBe(true);
+      expect('changeFrequency' in url).toBe(false);
+      expect('priority' in url).toBe(false);
+    }
+
+    if (hasGitHistory()) {
+      expect(urls.every((url) => url.lastModified instanceof Date)).toBe(true);
+    }
+  });
+});
diff --git a/apps/website/src/lib/sitemap-dates.ts b/apps/website/src/lib/sitemap-dates.ts
new file mode 100644
index 000000000..82045ae5a
--- /dev/null
+++ b/apps/website/src/lib/sitemap-dates.ts
@@ -0,0 +1,242 @@
+// SPDX-License-Identifier: MIT
+import { execFileSync } from 'node:child_process';
+import fs from 'node:fs';
+import path from 'node:path';
+import { getAllPosts, type Post } from './blog';
+import { specialDocsPages } from './docs-config';
+import { getSitemapRoutes } from './site-metadata';
+import { resolveWebsiteDir } from './website-dir';
+
+/** A sitemap URL plus the honest last-modified time of the source it renders from. */
+export interface SitemapEntry {
+  route: string;
+  /**
+   * Omitted when no honest value can be determined. An absent `<lastmod>` is
+   * valid sitemap XML; a fabricated one (e.g. "now" on every build, which is
+   * what file mtimes give you on any fresh checkout) teaches crawlers to ignore
+   * the signal across the whole site.
+   */
+  lastModified?: Date;
+}
+
+/** Website-relative source paths that a route's content is rendered from. */
+function sourcePathsForRoute(route: string, postsBySlug: Map<string, Post>): string[] {
+  const post = postsBySlug.get(route);
+  if (post) return [path.join('content', 'blog', post.filename)];
+
+  const special = specialDocsPages.find((page) => page.path === route);
+  if (special) return [path.join('content', 'docs', special.contentPath)];
+
+  if (route.startsWith('/docs/')) {
+    const [, , library, section, slug] = route.split('/');
+    if (library && section && slug) {
+      return [path.join('content', 'docs', library, section, `${slug}.mdx`)];
+    }
+    // Anything else under /docs is a hand-written route, dated like any other.
+  }
+
+  if (route.startsWith('/solutions/')) {
+    // Programmatic pages: one dynamic route template rendering data from a
+    // single module, so a change to either re-renders the page.
+    return [
+      path.join('src', 'app', 'solutions', '[slug]', 'page.tsx'),
+      path.join('src', 'lib', 'solutions-data.ts'),
+    ];
+  }
+
+  const routeDir = route === '/' ? '' : route.replace(/^\//, '');
+  return [path.join('src', 'app', routeDir, 'page.tsx')];
+}
+
+/** Absolute path for a website-relative source path, or null when it is missing. */
+function resolveSourcePath(relativePath: string): string | null {
+  const candidate = path.join(resolveWebsiteDir(), relativePath);
+  return fs.existsSync(candidate) ? candidate : null;
+}
+
+const GIT_LOG_MARKER = 'commit-time ';
+const GIT_LOG_HEADER = /^(\d+) ([0-9a-f]{40})$/;
+const GIT_TIMEOUT_MS = 30_000;
+
+export interface GitTimes {
+  /** Last commit time (epoch seconds) keyed by website-relative path. */
+  times: Map<string, number>;
+  /**
+   * False when the clone is shallow. It says nothing about whether a given file
+   * appears in `times` — an absent path may be uncommitted, or may simply
+   * predate the visible history — which is why nothing here ever falls back to
+   * a file mtime. It only sharpens the build-log diagnostic.
+   */
+  hasFullHistory: boolean;
+}
+
+/**
+ * Parse `git log --format='commit-time %ct %H' --name-only` output into last
+ * commit time (epoch seconds) per repo path, with `prefix` stripped.
+ *
+ * Files attributed to a grafted (shallow-boundary) commit are dropped: such a
+ * commit has no parent, so git reports the *entire tree* as changed at its
+ * timestamp. Emitting those would claim the whole site changed at clone time,
+ * which is exactly the fabrication this module exists to avoid.
+ */
+export function parseGitLog(text: string, prefix: string, graftedShas: ReadonlySet<string>): Map<string, number> {
+  const times = new Map<string, number>();
+  let commitTime = 0;
+
+  for (const line of text.split('\n')) {
+    if (line.startsWith(GIT_LOG_MARKER)) {
+      const header = GIT_LOG_HEADER.exec(line.slice(GIT_LOG_MARKER.length));
+      // A path can legitimately begin with the marker text; only a well-formed
+      // "<epoch> <sha1>" remainder is a commit header.
+      if (header) {
+        commitTime = graftedShas.has(header[2]) ? 0 : Number(header[1]);
+        continue;
+      }
+    }
+    // Paths are emitted verbatim (core.quotePath=false), so leading whitespace
+    // is part of the name; only truly empty lines are separators.
+    if (line.length === 0 || !commitTime) continue;
+    const relative = prefix && line.startsWith(prefix) ? line.slice(prefix.length) : line;
+    // `git log` walks newest-first, so the first mention of a path wins.
+    if (!times.has(relative)) times.set(relative, commitTime);
+  }
+
+  return times;
+}
+
+/**
+ * Read last-commit times for the website's content and sources from git.
+ *
+ * Returns null when git history yields nothing usable (no git, not a repo, a
+ * clone so shallow that only grafted commits are visible, or a git invocation
+ * that overflows its buffer or times out — all of which throw rather than
+ * returning partial output).
+ */
+function computeGitTimes(): GitTimes | null {
+  try {
+    const git = (args: string[], cwd: string): string =>
+      execFileSync(
+        'git',
+        [
+          // Emit paths verbatim instead of octal-escaping non-ASCII and quoting
+          // them, which would make every such path miss its lookup.
+          '-c',
+          'core.quotePath=false',
+          // A user's `log.showSignature=true` would interleave `gpg:` lines
+          // into the file list.
+          '-c',
+          'log.showSignature=false',
+          ...args,
+        ],
+        {
+          cwd,
+          encoding: 'utf8',
+          maxBuffer: 64 * 1024 * 1024,
+          timeout: GIT_TIMEOUT_MS,
+          killSignal: 'SIGKILL',
+          stdio: ['ignore', 'pipe', 'ignore'],
+        },
+      );
+
+    const root = git(['rev-parse', '--show-toplevel'], process.cwd()).trim();
+    const graftedShas = new Set<string>();
+    const shallow = git(['rev-parse', '--is-shallow-repository'], root).trim() === 'true';
+    if (shallow) {
+      // Must be the COMMON git dir, not `--absolute-git-dir`: in a linked
+      // worktree those differ (`.git/worktrees/<name>` vs `.git`) and `shallow`
+      // only ever lives in the common dir. Output can be relative, and git runs
+      // with cwd=root, so resolve it against root.
+      const commonDir = path.resolve(root, git(['rev-parse', '--git-common-dir'], root).trim());
+      const shallowFile = path.join(commonDir, 'shallow');
+      if (!fs.existsSync(shallowFile)) return null;
+      for (const sha of fs.readFileSync(shallowFile, 'utf8').split('\n')) {
+        if (sha.trim()) graftedShas.add(sha.trim());
+      }
+    }
+
+    const prefix = fs.existsSync(path.join(root, 'apps', 'website')) ? 'apps/website/' : '';
+    const log = git(
+      [
+        'log',
+        `--format=${GIT_LOG_MARKER}%ct %H`,
+        '--name-only',
+        '--',
+        `${prefix}content`,
+        `${prefix}src/app`,
+        `${prefix}src/lib`,
+      ],
+      root,
+    );
+
+    const times = parseGitLog(log, prefix, graftedShas);
+    return times.size > 0 ? { times, hasFullHistory: !shallow } : null;
+  } catch {
+    return null;
+  }
+}
+
+let gitTimesCache: GitTimes | null | undefined;
+
+function getGitTimes(): GitTimes | null {
+  if (gitTimesCache !== undefined) return gitTimesCache;
+  gitTimesCache = computeGitTimes();
+
+  if (gitTimesCache === null) {
+    // Visible in the build log: the sitemap will carry `lastmod` only for blog
+    // posts (which date themselves in frontmatter) until history is available.
+    console.warn('[sitemap] git history unavailable; omitting <lastmod> for file-derived routes.');
+  } else if (!gitTimesCache.hasFullHistory) {
+    console.warn('[sitemap] shallow clone; omitting <lastmod> for routes older than the visible history.');
+  }
+
+  return gitTimesCache;
+}
+
+/** True when git can date at least some sources. Exposed for tests. */
+export function hasGitHistory(): boolean {
+  return getGitTimes() !== null;
+}
+
+/**
+ * Newest commit time across a route's sources, or undefined when git cannot
+ * date any of them. File mtimes are deliberately never consulted: any fresh
+ * clone — shallow or not — rewrites every mtime to checkout time, so a single
+ * lookup miss would silently publish a build-time `lastmod`.
+ */
+function sourceModifiedTime(relativePaths: string[]): Date | undefined {
+  const git = getGitTimes();
+  if (!git) return undefined;
+
+  let newest: number | undefined;
+  for (const relativePath of relativePaths) {
+    if (!resolveSourcePath(relativePath)) continue;
+    const seconds = git.times.get(relativePath.split(path.sep).join('/'));
+    if (seconds === undefined) continue;
+    if (newest === undefined || seconds > newest) newest = seconds;
+  }
+
+  return newest === undefined ? undefined : new Date(newest * 1000);
+}
+
+/** Frontmatter publish date as UTC midnight, or undefined when unparseable. */
+function publishedDate(post: Post): Date | undefined {
+  const date = new Date(`${post.frontmatter.date}T00:00:00Z`);
+  return Number.isNaN(date.getTime()) ? undefined : date;
+}
+
+export function getSitemapEntries(): SitemapEntry[] {
+  const postsBySlug = new Map(getAllPosts().map((post) => [`/blog/${post.slug}`, post]));
+
+  return getSitemapRoutes().map((route) => {
+    const committed = sourceModifiedTime(sourcePathsForRoute(route, postsBySlug));
+
+    // `lastmod` means last *modified*, so an edited post outranks its own
+    // publish date; the frontmatter date still covers posts git cannot date.
+    const post = postsBySlug.get(route);
+    const published = post ? publishedDate(post) : undefined;
+    const lastModified =
+      committed && published ? (committed > published ? committed : published) : (committed ?? published);
+
+    return lastModified ? { route, lastModified } : { route };
+  });
+}
diff --git a/apps/website/src/lib/website-dir.ts b/apps/website/src/lib/website-dir.ts
new file mode 100644
index 000000000..605184dbc
--- /dev/null
+++ b/apps/website/src/lib/website-dir.ts
@@ -0,0 +1,12 @@
+// SPDX-License-Identifier: MIT
+import fs from 'node:fs';
+import path from 'node:path';
+
+/**
+ * Absolute path to `apps/website`, whether the process was started from the
+ * workspace root (`nx build website`) or from the app itself (`next build`).
+ */
+export function resolveWebsiteDir(): string {
+  const workspace = path.join(process.cwd(), 'apps', 'website');
+  return fs.existsSync(workspace) ? workspace : process.cwd();
+}

From 532b8b17a32fbb06b80451f9537e23463eb18048 Mon Sep 17 00:00:00 2001
From: Brian Love <brian@liveloveapp.com>
Date: Thu, 20 Aug 2026 12:45:43 -0700
Subject: [PATCH 14/35] feat(website): article metadata + canonical brand
 spelling

Emit article:published_time / modified_time / author / tag on blog posts,
with modified_time derived from real git commit times (sitemap-dates)
rather than defaulting to the publish date. createPageMetadata gains an
optional per-page social image for the Task 9 OG-image routes.

Unify the brand on "Threadplane" (was "ThreadPlane" in blog titles and
prose) and the docs title separator on an em dash.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
---
 ...stack-agentic-angular-apps-using-ag-ui.mdx |  6 +--
 apps/website/e2e/blog.spec.ts                 |  2 +-
 apps/website/e2e/website.spec.ts              |  4 +-
 apps/website/src/app/blog/[slug]/page.tsx     | 24 +++++++++--
 apps/website/src/app/blog/page.tsx            |  4 +-
 .../docs/[library]/[section]/[slug]/page.tsx  |  2 +-
 apps/website/src/lib/docs.spec.ts             |  6 +--
 apps/website/src/lib/docs.ts                  |  2 +-
 apps/website/src/lib/site-metadata.spec.ts    | 40 +++++++++++++++++++
 apps/website/src/lib/site-metadata.ts         | 29 +++++++++++++-
 apps/website/src/lib/sitemap-dates.ts         | 31 +++++++++-----
 11 files changed, 123 insertions(+), 27 deletions(-)

diff --git a/apps/website/content/blog/2026-05-21-build-fullstack-agentic-angular-apps-using-ag-ui.mdx b/apps/website/content/blog/2026-05-21-build-fullstack-agentic-angular-apps-using-ag-ui.mdx
index 87be3b491..a790bf58f 100644
--- a/apps/website/content/blog/2026-05-21-build-fullstack-agentic-angular-apps-using-ag-ui.mdx
+++ b/apps/website/content/blog/2026-05-21-build-fullstack-agentic-angular-apps-using-ag-ui.mdx
@@ -57,7 +57,7 @@ Three boxes. Two seams.
 
 **The wire.** Server-Sent Events. Plain HTTP, no WebSocket gymnastics, no custom binary framing. Your firewall, load balancer, and reverse proxy already know what to do with it.
 
-**The Angular side.** This is what ThreadPlane provides. `@threadplane/ag-ui` is the adapter. It consumes the AG-UI event stream and exposes a runtime-neutral `Agent` contract built from signals. `@threadplane/chat` is the UI. It reads from that contract and renders. The two are decoupled on purpose. We'll get to why.
+**The Angular side.** This is what Threadplane provides. `@threadplane/ag-ui` is the adapter. It consumes the AG-UI event stream and exposes a runtime-neutral `Agent` contract built from signals. `@threadplane/chat` is the UI. It reads from that contract and renders. The two are decoupled on purpose. We'll get to why.
 
 ## Let's wire it up
 
@@ -164,7 +164,7 @@ The AG-UI protocol has seventeen event types, grouped into five families:
 
 The families each do specific work. Lifecycle answers "is something happening?" Text messages are the streaming triad familiar from chat UIs. Tool calls are deliberately incremental so you can render the *intent* before the arguments are fully formed. State sync uses RFC 6902 JSON Patch so the wire stays small even when the agent's state is large.
 
-ThreadPlane's `@threadplane/ag-ui` runs each event through a small reducer that updates a handful of signals on the `Agent` contract:
+Threadplane's `@threadplane/ag-ui` runs each event through a small reducer that updates a handful of signals on the `Agent` contract:
 
 - `messages()`: `Message[]`, the chat history. `TEXT_MESSAGE_CONTENT` appends a delta to the in-flight assistant message.
 - `status()`: `'idle' | 'running' | 'error' | 'paused'`. Driven by the `RUN_*` events.
@@ -300,6 +300,6 @@ Each of those is its own post. The point here is just that the protocol-to-signa
 
 ## Conclusion
 
-AG-UI standardizes the wire between the agent and the UI: it's small enough to hold in your head, and the event model maps onto Angular signals cleanly. With ThreadPlane (`@threadplane/ag-ui` and `@threadplane/chat` on npm), the wiring is three lines — a provider, an inject, and a `<chat>` — which leaves the interesting work (tool cards, interrupt flows, generative UI, your design system) as the part you spend the day on.
+AG-UI standardizes the wire between the agent and the UI: it's small enough to hold in your head, and the event model maps onto Angular signals cleanly. With Threadplane (`@threadplane/ag-ui` and `@threadplane/chat` on npm), the wiring is three lines — a provider, an inject, and a `<chat>` — which leaves the interesting work (tool cards, interrupt flows, generative UI, your design system) as the part you spend the day on.
 
 The adapters are MIT; `@threadplane/chat` is source-available with a free non-commercial tier. If you're building this inside an enterprise Angular app (design system, multi-tenant, regulated), [talk to us](/contact?source=blog_ag_ui_pillar&track=enterprise).
diff --git a/apps/website/e2e/blog.spec.ts b/apps/website/e2e/blog.spec.ts
index 1c187dda9..2b667d485 100644
--- a/apps/website/e2e/blog.spec.ts
+++ b/apps/website/e2e/blog.spec.ts
@@ -6,7 +6,7 @@ test.describe('Blog landing page', () => {
 
     // Brand eyebrow + H1
     await expect(page.getByText('Blog', { exact: true }).first()).toBeVisible();
-    await expect(page.getByRole('heading', { level: 1, name: /Articles from ThreadPlane/i })).toBeVisible();
+    await expect(page.getByRole('heading', { level: 1, name: /Articles from Threadplane/i })).toBeVisible();
 
     // Filter row contains the "All" chip in active state
     await expect(page.getByText('All', { exact: true })).toBeVisible();
diff --git a/apps/website/e2e/website.spec.ts b/apps/website/e2e/website.spec.ts
index 21490729f..038aa67a4 100644
--- a/apps/website/e2e/website.spec.ts
+++ b/apps/website/e2e/website.spec.ts
@@ -237,7 +237,7 @@ test('docs pages render canonical and social metadata', async ({ page }) => {
   );
   await expect(page.locator('meta[property="og:title"]')).toHaveAttribute(
     'content',
-    'Streaming - LangGraph Docs - Threadplane',
+    'Streaming — LangGraph Docs — Threadplane',
   );
   await expect(page.locator('meta[property="og:url"]')).toHaveAttribute(
     'content',
@@ -245,7 +245,7 @@ test('docs pages render canonical and social metadata', async ({ page }) => {
   );
   await expect(page.locator('meta[name="twitter:title"]')).toHaveAttribute(
     'content',
-    'Streaming - LangGraph Docs - Threadplane',
+    'Streaming — LangGraph Docs — Threadplane',
   );
 });
 
diff --git a/apps/website/src/app/blog/[slug]/page.tsx b/apps/website/src/app/blog/[slug]/page.tsx
index d666fd023..408b01332 100644
--- a/apps/website/src/app/blog/[slug]/page.tsx
+++ b/apps/website/src/app/blog/[slug]/page.tsx
@@ -10,6 +10,7 @@ import { getAllPosts, getPostBySlug, formatPostDate, readingTimeMin } from '../.
 import { getAuthor } from '../../../lib/blog-authors';
 import { extractHeadings } from '../../../lib/extract-headings';
 import { createPageMetadata } from '../../../lib/site-metadata';
+import { getRouteLastModified } from '../../../lib/sitemap-dates';
 
 interface Params {
   params: Promise<{ slug: string }>;
@@ -23,13 +24,30 @@ 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 — ThreadPlane' };
+    return { title: 'Post not found — Threadplane' };
   }
+  const author = getAuthor(post.frontmatter.author);
+  const pathname = `/blog/${post.slug}`;
+  // Only claim a modification when git actually shows the post was edited after
+  // its publish date; otherwise `createPageMetadata` reports it unmodified.
+  const published = new Date(`${post.frontmatter.date}T00:00:00Z`);
+  const lastModified = getRouteLastModified(pathname);
+  const modifiedTime =
+    lastModified && lastModified.getTime() > published.getTime() ? lastModified.toISOString() : undefined;
+
   return createPageMetadata({
-    title: `${post.frontmatter.title} — ThreadPlane`,
+    title: `${post.frontmatter.title} — Threadplane`,
     description: post.frontmatter.description,
-    pathname: `/blog/${post.slug}`,
+    pathname,
     type: 'article',
+    // TODO(task 9): point at `${pathname}/opengraph-image` once that route
+    // exists; naming it before then would emit an og:image URL that 404s.
+    article: {
+      publishedTime: post.frontmatter.date,
+      modifiedTime,
+      authors: [author.name],
+      tags: post.frontmatter.tags,
+    },
   });
 }
 
diff --git a/apps/website/src/app/blog/page.tsx b/apps/website/src/app/blog/page.tsx
index 212e09916..67a2bb25d 100644
--- a/apps/website/src/app/blog/page.tsx
+++ b/apps/website/src/app/blog/page.tsx
@@ -8,7 +8,7 @@ import { BlogTagFilter } from '../../components/blog/BlogTagFilter';
 import { Eyebrow } from '../../components/ui/Eyebrow';
 
 export const metadata = createPageMetadata({
-  title: 'Blog — ThreadPlane',
+  title: 'Blog — Threadplane',
   description:
     'Long-form writing on agent UI for Angular: streaming, generative UI, threads, interrupts, production patterns.',
   pathname: '/blog',
@@ -51,7 +51,7 @@ export default async function BlogIndexPage({ searchParams }: Props) {
               margin: '0 0 16px',
             }}
           >
-            Articles from ThreadPlane
+            Articles from Threadplane
           </h1>
           <p
             style={{
diff --git a/apps/website/src/app/docs/[library]/[section]/[slug]/page.tsx b/apps/website/src/app/docs/[library]/[section]/[slug]/page.tsx
index 8f88adbee..bf4cad00b 100644
--- a/apps/website/src/app/docs/[library]/[section]/[slug]/page.tsx
+++ b/apps/website/src/app/docs/[library]/[section]/[slug]/page.tsx
@@ -38,7 +38,7 @@ export function generateStaticParams() {
 export async function generateMetadata({ params }: DocsRouteProps): Promise<Metadata> {
   const { library, section, slug } = await params;
   return getDocMetadata(library, section, slug) ?? {
-    title: 'Docs - Threadplane',
+    title: 'Docs — Threadplane',
     description: 'Threadplane documentation',
   };
 }
diff --git a/apps/website/src/lib/docs.spec.ts b/apps/website/src/lib/docs.spec.ts
index 9616730ab..2a986ecd2 100644
--- a/apps/website/src/lib/docs.spec.ts
+++ b/apps/website/src/lib/docs.spec.ts
@@ -99,17 +99,17 @@ describe('website docs bindings', () => {
     const metadata = getDocMetadata('ag-ui', 'reference', 'event-mapping');
 
     expect(metadata).toMatchObject({
-      title: 'Event Mapping - AG-UI Docs - Threadplane',
+      title: 'Event Mapping — AG-UI Docs — Threadplane',
       alternates: {
         canonical: '/docs/ag-ui/reference/event-mapping',
       },
       openGraph: {
-        title: 'Event Mapping - AG-UI Docs - Threadplane',
+        title: 'Event Mapping — AG-UI Docs — Threadplane',
         url: '/docs/ag-ui/reference/event-mapping',
       },
       twitter: {
         card: 'summary_large_image',
-        title: 'Event Mapping - AG-UI Docs - Threadplane',
+        title: 'Event Mapping — AG-UI Docs — Threadplane',
       },
     });
     expect(metadata?.description).toContain('AG-UI protocol events');
diff --git a/apps/website/src/lib/docs.ts b/apps/website/src/lib/docs.ts
index 28d637541..02b57ec13 100644
--- a/apps/website/src/lib/docs.ts
+++ b/apps/website/src/lib/docs.ts
@@ -86,7 +86,7 @@ export function getDocMetadata(
 
   const lib = getLibraryConfig(library);
   const libraryTitle = lib?.title ?? 'Docs';
-  const title = `${doc.title} - ${libraryTitle} Docs - Threadplane`;
+  const title = `${doc.title} — ${libraryTitle} Docs — Threadplane`;
   const description = getDocDescription(doc.content, lib?.description ?? 'Threadplane documentation');
   const pathname = `/docs/${library}/${section}/${slug}`;
 
diff --git a/apps/website/src/lib/site-metadata.spec.ts b/apps/website/src/lib/site-metadata.spec.ts
index 5e9db745d..7984383fa 100644
--- a/apps/website/src/lib/site-metadata.spec.ts
+++ b/apps/website/src/lib/site-metadata.spec.ts
@@ -6,6 +6,7 @@ import {
   POSITIONING_PROOF_POINTS,
   PRIMARY_TAGLINE,
   SHORT_POSITIONING_DESCRIPTION,
+  SITE_NAME,
   createPageMetadata,
 } from './site-metadata';
 
@@ -49,3 +50,42 @@ describe('site positioning copy', () => {
     expect(metadata.twitter?.description).toBe(DEFAULT_META_DESCRIPTION);
   });
 });
+
+describe('createPageMetadata article fields', () => {
+  it('emits openGraph article dates, authors, and tags', () => {
+    const metadata = createPageMetadata({
+      title: 'Post — Threadplane',
+      description: 'A post.',
+      pathname: '/blog/post',
+      type: 'article',
+      article: {
+        publishedTime: '2026-08-13',
+        modifiedTime: '2026-08-14',
+        authors: ['Brian Love'],
+        tags: ['angular', 'ag-ui'],
+      },
+    });
+    const openGraph = metadata.openGraph as Record<string, unknown>;
+    expect(openGraph['publishedTime']).toBe('2026-08-13');
+    expect(openGraph['modifiedTime']).toBe('2026-08-14');
+    expect(openGraph['authors']).toEqual(['Brian Love']);
+    expect(openGraph['tags']).toEqual(['angular', 'ag-ui']);
+  });
+
+  it('accepts a page-specific social image', () => {
+    const metadata = createPageMetadata({
+      title: 'Post — Threadplane',
+      description: 'A post.',
+      pathname: '/blog/post',
+      image: '/blog/post/opengraph-image',
+    });
+    const openGraph = metadata.openGraph as { images: string[] };
+    expect(openGraph.images).toEqual(['/blog/post/opengraph-image']);
+  });
+});
+
+describe('brand name', () => {
+  it('uses one canonical spelling', () => {
+    expect(SITE_NAME).toBe('Threadplane');
+  });
+});
diff --git a/apps/website/src/lib/site-metadata.ts b/apps/website/src/lib/site-metadata.ts
index 6a5744005..ce9260e11 100644
--- a/apps/website/src/lib/site-metadata.ts
+++ b/apps/website/src/lib/site-metadata.ts
@@ -25,16 +25,33 @@ export function getCanonicalUrl(pathname: string): string {
   return new URL(getCanonicalPath(pathname), SITE_ORIGIN).toString();
 }
 
+/** Article-specific OpenGraph fields (freshness + attribution signals). */
+export interface ArticleMetadata {
+  /** ISO 8601 publish date or timestamp. */
+  publishedTime: string;
+  /**
+   * ISO 8601 last-modified timestamp. Omit only when the content genuinely has
+   * not changed since publication — it then falls back to `publishedTime`.
+   */
+  modifiedTime?: string;
+  authors?: string[];
+  tags?: string[];
+}
+
 export function createPageMetadata({
   title,
   description,
   pathname,
   type = 'article',
+  image = DEFAULT_SOCIAL_IMAGE,
+  article,
 }: {
   title: string;
   description: string;
   pathname: string;
   type?: 'article' | 'website';
+  image?: string;
+  article?: ArticleMetadata;
 }): Metadata {
   const canonicalPath = getCanonicalPath(pathname);
 
@@ -50,13 +67,21 @@ export function createPageMetadata({
       url: canonicalPath,
       siteName: SITE_NAME,
       type,
-      images: [DEFAULT_SOCIAL_IMAGE],
+      images: [image],
+      ...(article
+        ? {
+            publishedTime: article.publishedTime,
+            modifiedTime: article.modifiedTime ?? article.publishedTime,
+            authors: article.authors,
+            tags: article.tags,
+          }
+        : {}),
     },
     twitter: {
       card: 'summary_large_image',
       title,
       description,
-      images: [DEFAULT_SOCIAL_IMAGE],
+      images: [image],
     },
   };
 }
diff --git a/apps/website/src/lib/sitemap-dates.ts b/apps/website/src/lib/sitemap-dates.ts
index 82045ae5a..cc4f7d283 100644
--- a/apps/website/src/lib/sitemap-dates.ts
+++ b/apps/website/src/lib/sitemap-dates.ts
@@ -224,19 +224,32 @@ function publishedDate(post: Post): Date | undefined {
   return Number.isNaN(date.getTime()) ? undefined : date;
 }
 
+/**
+ * Honest last-modified time for one route, or undefined when nothing can date
+ * it. Shared by the sitemap and by article metadata (`og:modified_time`), so
+ * both surfaces make the same freshness claim.
+ *
+ * `postsBySlug` is an optional cache: callers walking every route build it once
+ * rather than re-reading the blog directory per route.
+ */
+export function getRouteLastModified(route: string, postsBySlug?: Map<string, Post>): Date | undefined {
+  const posts =
+    postsBySlug ??
+    new Map(getAllPosts({ includeDrafts: true }).map((post) => [`/blog/${post.slug}`, post]));
+  const committed = sourceModifiedTime(sourcePathsForRoute(route, posts));
+
+  // "Modified" means last *modified*, so an edited post outranks its own
+  // publish date; the frontmatter date still covers posts git cannot date.
+  const post = posts.get(route);
+  const published = post ? publishedDate(post) : undefined;
+  return committed && published ? (committed > published ? committed : published) : (committed ?? published);
+}
+
 export function getSitemapEntries(): SitemapEntry[] {
   const postsBySlug = new Map(getAllPosts().map((post) => [`/blog/${post.slug}`, post]));
 
   return getSitemapRoutes().map((route) => {
-    const committed = sourceModifiedTime(sourcePathsForRoute(route, postsBySlug));
-
-    // `lastmod` means last *modified*, so an edited post outranks its own
-    // publish date; the frontmatter date still covers posts git cannot date.
-    const post = postsBySlug.get(route);
-    const published = post ? publishedDate(post) : undefined;
-    const lastModified =
-      committed && published ? (committed > published ? committed : published) : (committed ?? published);
-
+    const lastModified = getRouteLastModified(route, postsBySlug);
     return lastModified ? { route, lastModified } : { route };
   });
 }

From 7c88eaeb6fb2c6b731a275eea011229ce3dd1eb0 Mon Sep 17 00:00:00 2001
From: Brian Love <brian@liveloveapp.com>
Date: Thu, 20 Aug 2026 12:55:17 -0700
Subject: [PATCH 15/35] refactor(website): single-source the blog modified time

Drop the redundant `lastModified > published` guard in the blog route: it
could never change the value (getRouteLastModified already returns the
max) and its only effect was flipping modifiedTime to undefined, which
made unedited posts emit a date-only article:published_time while edited
ones emitted a full ISO timestamp. The `?? publishedTime` fallback in
createPageMetadata is now the one place that rule lives, and both fields
are ISO timestamps on every post.

Date parsing moves to the shared `publishedDate()` helper, so a malformed
frontmatter date drops the article block instead of shipping NaN-adjacent
garbage as article:published_time.

getRouteLastModified's post index is now a required `postsByRoute`
(renamed: the keys are route paths) rather than an optional argument with
a drafts policy that diverged from the caller's, which could return
different answers for the same route. Callers build it with the new
getPostsByRoute() or pass the post they already hold.

Replaces the tautological SITE_NAME assertion with a real scan of src,
content, scripts, and e2e for the mis-cased brand, and covers the
modifiedTime fallback plus the absence of article keys on non-article
pages.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
---
 apps/website/src/app/blog/[slug]/page.tsx  | 30 ++++-----
 apps/website/src/lib/site-metadata.spec.ts | 72 +++++++++++++++++++++-
 apps/website/src/lib/site-metadata.ts      | 41 ++++++------
 apps/website/src/lib/sitemap-dates.ts      | 37 ++++++-----
 4 files changed, 132 insertions(+), 48 deletions(-)

diff --git a/apps/website/src/app/blog/[slug]/page.tsx b/apps/website/src/app/blog/[slug]/page.tsx
index 408b01332..a3bed5312 100644
--- a/apps/website/src/app/blog/[slug]/page.tsx
+++ b/apps/website/src/app/blog/[slug]/page.tsx
@@ -10,7 +10,7 @@ import { getAllPosts, getPostBySlug, formatPostDate, readingTimeMin } from '../.
 import { getAuthor } from '../../../lib/blog-authors';
 import { extractHeadings } from '../../../lib/extract-headings';
 import { createPageMetadata } from '../../../lib/site-metadata';
-import { getRouteLastModified } from '../../../lib/sitemap-dates';
+import { getRouteLastModified, publishedDate } from '../../../lib/sitemap-dates';
 
 interface Params {
   params: Promise<{ slug: string }>;
@@ -28,26 +28,28 @@ export async function generateMetadata({ params }: Params): Promise<Metadata> {
   }
   const author = getAuthor(post.frontmatter.author);
   const pathname = `/blog/${post.slug}`;
-  // Only claim a modification when git actually shows the post was edited after
-  // its publish date; otherwise `createPageMetadata` reports it unmodified.
-  const published = new Date(`${post.frontmatter.date}T00:00:00Z`);
-  const lastModified = getRouteLastModified(pathname);
-  const modifiedTime =
-    lastModified && lastModified.getTime() > published.getTime() ? lastModified.toISOString() : undefined;
+  // The post is already resolved, so index just it: no drafts policy to inherit
+  // and no second read of the blog directory.
+  const lastModified = getRouteLastModified(pathname, new Map([[pathname, post]]));
+  // Undefined for an unparseable frontmatter date, which drops the article
+  // block rather than shipping the bad string as `article:published_time`.
+  const published = publishedDate(post);
 
   return createPageMetadata({
     title: `${post.frontmatter.title} — Threadplane`,
     description: post.frontmatter.description,
     pathname,
     type: 'article',
-    // TODO(task 9): point at `${pathname}/opengraph-image` once that route
+    // TODO(task 9): set image to "<pathname>/opengraph-image" once that route
     // exists; naming it before then would emit an og:image URL that 404s.
-    article: {
-      publishedTime: post.frontmatter.date,
-      modifiedTime,
-      authors: [author.name],
-      tags: post.frontmatter.tags,
-    },
+    article: published
+      ? {
+          publishedTime: published.toISOString(),
+          modifiedTime: lastModified?.toISOString(),
+          authors: [author.name],
+          tags: post.frontmatter.tags,
+        }
+      : undefined,
   });
 }
 
diff --git a/apps/website/src/lib/site-metadata.spec.ts b/apps/website/src/lib/site-metadata.spec.ts
index 7984383fa..84559a11c 100644
--- a/apps/website/src/lib/site-metadata.spec.ts
+++ b/apps/website/src/lib/site-metadata.spec.ts
@@ -1,3 +1,5 @@
+import fs from 'node:fs';
+import path from 'node:path';
 import { describe, expect, it } from 'vitest';
 import {
   DEFAULT_META_DESCRIPTION,
@@ -9,6 +11,7 @@ import {
   SITE_NAME,
   createPageMetadata,
 } from './site-metadata';
+import { resolveWebsiteDir } from './website-dir';
 
 describe('site positioning copy', () => {
   it('exports the approved primary tagline and supporting copy', () => {
@@ -84,8 +87,75 @@ describe('createPageMetadata article fields', () => {
   });
 });
 
+describe('createPageMetadata article fallback', () => {
+  it('advertises the publish date as the modification when none is known', () => {
+    const metadata = createPageMetadata({
+      title: 'Post — Threadplane',
+      description: 'A post.',
+      pathname: '/blog/post',
+      article: { publishedTime: '2026-08-13T00:00:00.000Z' },
+    });
+    const openGraph = metadata.openGraph as Record<string, unknown>;
+    expect(openGraph['modifiedTime']).toBe('2026-08-13T00:00:00.000Z');
+  });
+
+  it('omits article fields entirely for a non-article page', () => {
+    const metadata = createPageMetadata({
+      title: 'Home — Threadplane',
+      description: 'A page.',
+      pathname: '/',
+      type: 'website',
+    });
+    const openGraph = metadata.openGraph as Record<string, unknown>;
+    // Absent, not undefined: Next emits a meta tag for a present-but-undefined
+    // key in some shapes, and a landing page has no publication to date.
+    expect('publishedTime' in openGraph).toBe(false);
+    expect('modifiedTime' in openGraph).toBe(false);
+    expect('authors' in openGraph).toBe(false);
+    expect('tags' in openGraph).toBe(false);
+  });
+});
+
 describe('brand name', () => {
-  it('uses one canonical spelling', () => {
+  // Built at runtime so this spec file — which lives under a scanned root —
+  // does not match its own needle.
+  const MISSPELLING = new RegExp(['Thread', 'Plane'].join(''), 'g');
+  const SCAN_ROOTS = ['src', 'content', 'scripts', 'e2e'];
+  const ALLOWED = new Set([
+    // A deliberate mixed-case URL fixture for host-case normalization.
+    path.join('scripts', 'gsc', 'analysis.spec.ts'),
+  ]);
+  const SKIP_DIRS = new Set(['node_modules', '.next', 'dist']);
+
+  function walk(dir: string, root: string, out: string[]): string[] {
+    for (const entry of fs.readdirSync(dir, { withFileTypes: true })) {
+      const full = path.join(dir, entry.name);
+      if (entry.isDirectory()) {
+        if (!SKIP_DIRS.has(entry.name)) walk(full, root, out);
+      } else if (entry.isFile()) {
+        out.push(path.relative(root, full));
+      }
+    }
+    return out;
+  }
+
+  it('is spelled the same way everywhere it ships', () => {
+    const websiteDir = resolveWebsiteDir();
+    const offenders: string[] = [];
+
+    for (const root of SCAN_ROOTS) {
+      const rootDir = path.join(websiteDir, root);
+      if (!fs.existsSync(rootDir)) continue;
+      for (const relative of walk(rootDir, websiteDir, [])) {
+        if (ALLOWED.has(relative)) continue;
+        if (MISSPELLING.test(fs.readFileSync(path.join(websiteDir, relative), 'utf8'))) {
+          offenders.push(relative);
+        }
+        MISSPELLING.lastIndex = 0;
+      }
+    }
+
+    expect(offenders).toEqual([]);
     expect(SITE_NAME).toBe('Threadplane');
   });
 });
diff --git a/apps/website/src/lib/site-metadata.ts b/apps/website/src/lib/site-metadata.ts
index ce9260e11..28e7809cd 100644
--- a/apps/website/src/lib/site-metadata.ts
+++ b/apps/website/src/lib/site-metadata.ts
@@ -30,14 +30,26 @@ export interface ArticleMetadata {
   /** ISO 8601 publish date or timestamp. */
   publishedTime: string;
   /**
-   * ISO 8601 last-modified timestamp. Omit only when the content genuinely has
-   * not changed since publication — it then falls back to `publishedTime`.
+   * ISO 8601 last-modified timestamp. Omit when no modification is known; it
+   * then falls back to `publishedTime`.
    */
   modifiedTime?: string;
   authors?: string[];
   tags?: string[];
 }
 
+/** Options for {@link createPageMetadata}. */
+export interface PageMetadataOptions {
+  title: string;
+  description: string;
+  pathname: string;
+  type?: 'article' | 'website';
+  /** Social image path; resolved against `metadataBase` from the root layout. */
+  image?: string;
+  /** Present only for article-type pages; omitted entirely for landing pages. */
+  article?: ArticleMetadata;
+}
+
 export function createPageMetadata({
   title,
   description,
@@ -45,14 +57,7 @@ export function createPageMetadata({
   type = 'article',
   image = DEFAULT_SOCIAL_IMAGE,
   article,
-}: {
-  title: string;
-  description: string;
-  pathname: string;
-  type?: 'article' | 'website';
-  image?: string;
-  article?: ArticleMetadata;
-}): Metadata {
+}: PageMetadataOptions): Metadata {
   const canonicalPath = getCanonicalPath(pathname);
 
   return {
@@ -68,14 +73,14 @@ export function createPageMetadata({
       siteName: SITE_NAME,
       type,
       images: [image],
-      ...(article
-        ? {
-            publishedTime: article.publishedTime,
-            modifiedTime: article.modifiedTime ?? article.publishedTime,
-            authors: article.authors,
-            tags: article.tags,
-          }
-        : {}),
+      ...(article && {
+        publishedTime: article.publishedTime,
+        // The single place the "unmodified" rule lives: an article with no
+        // known modification advertises its publish date as the modification.
+        modifiedTime: article.modifiedTime ?? article.publishedTime,
+        authors: article.authors,
+        tags: article.tags,
+      }),
     },
     twitter: {
       card: 'summary_large_image',
diff --git a/apps/website/src/lib/sitemap-dates.ts b/apps/website/src/lib/sitemap-dates.ts
index cc4f7d283..9b4fd502b 100644
--- a/apps/website/src/lib/sitemap-dates.ts
+++ b/apps/website/src/lib/sitemap-dates.ts
@@ -20,8 +20,8 @@ export interface SitemapEntry {
 }
 
 /** Website-relative source paths that a route's content is rendered from. */
-function sourcePathsForRoute(route: string, postsBySlug: Map<string, Post>): string[] {
-  const post = postsBySlug.get(route);
+function sourcePathsForRoute(route: string, postsByRoute: ReadonlyMap<string, Post>): string[] {
+  const post = postsByRoute.get(route);
   if (post) return [path.join('content', 'blog', post.filename)];
 
   const special = specialDocsPages.find((page) => page.path === route);
@@ -219,37 +219,44 @@ function sourceModifiedTime(relativePaths: string[]): Date | undefined {
 }
 
 /** Frontmatter publish date as UTC midnight, or undefined when unparseable. */
-function publishedDate(post: Post): Date | undefined {
+export function publishedDate(post: Post): Date | undefined {
   const date = new Date(`${post.frontmatter.date}T00:00:00Z`);
   return Number.isNaN(date.getTime()) ? undefined : date;
 }
 
+/** Index the posts a caller wants visible, keyed by route path. */
+export function getPostsByRoute(options: { includeDrafts?: boolean } = {}): Map<string, Post> {
+  return new Map(getAllPosts(options).map((post) => [`/blog/${post.slug}`, post]));
+}
+
 /**
  * Honest last-modified time for one route, or undefined when nothing can date
- * it. Shared by the sitemap and by article metadata (`og:modified_time`), so
- * both surfaces make the same freshness claim.
+ * it. Shared by the sitemap and by article metadata (`article:modified_time`),
+ * so both surfaces make the same freshness claim for the same route.
  *
- * `postsBySlug` is an optional cache: callers walking every route build it once
- * rather than re-reading the blog directory per route.
+ * `postsByRoute` is required rather than defaulted: a route's answer depends on
+ * whether its post is visible in the map (a missing one loses its frontmatter
+ * date and falls through to a page source that does not exist for blog posts),
+ * so every caller states which posts it means instead of inheriting a drafts
+ * policy chosen here. Build it with {@link getPostsByRoute}, or pass a
+ * single-entry map when the post is already in hand.
  */
-export function getRouteLastModified(route: string, postsBySlug?: Map<string, Post>): Date | undefined {
-  const posts =
-    postsBySlug ??
-    new Map(getAllPosts({ includeDrafts: true }).map((post) => [`/blog/${post.slug}`, post]));
-  const committed = sourceModifiedTime(sourcePathsForRoute(route, posts));
+export function getRouteLastModified(route: string, postsByRoute: ReadonlyMap<string, Post>): Date | undefined {
+  const committed = sourceModifiedTime(sourcePathsForRoute(route, postsByRoute));
 
   // "Modified" means last *modified*, so an edited post outranks its own
   // publish date; the frontmatter date still covers posts git cannot date.
-  const post = posts.get(route);
+  const post = postsByRoute.get(route);
   const published = post ? publishedDate(post) : undefined;
   return committed && published ? (committed > published ? committed : published) : (committed ?? published);
 }
 
 export function getSitemapEntries(): SitemapEntry[] {
-  const postsBySlug = new Map(getAllPosts().map((post) => [`/blog/${post.slug}`, post]));
+  // Drafts are not in `getSitemapRoutes()`, so they are not indexed either.
+  const postsByRoute = getPostsByRoute();
 
   return getSitemapRoutes().map((route) => {
-    const lastModified = getRouteLastModified(route, postsBySlug);
+    const lastModified = getRouteLastModified(route, postsByRoute);
     return lastModified ? { route, lastModified } : { route };
   });
 }

From 65aa7c7bf0f9c60b8fbb9a33dec4f70750f77fea Mon Sep 17 00:00:00 2001
From: Brian Love <brian@liveloveapp.com>
Date: Thu, 20 Aug 2026 13:00:41 -0700
Subject: [PATCH 16/35] feat(website): schema.org json-ld builders

Pure builders for Organization, WebSite, SoftwareSourceCode, BlogPosting,
TechArticle, and BreadcrumbList nodes, plus a JsonLd render component. Not
mounted on any route yet.

Every emitted URL was verified to resolve: the repository is
cacheplane/angular-agent-framework (not blove/...), sameAs links the public
package page rather than the member-gated npm org page, and the author URL
and per-post OG image are omitted until /about and the fixed image route
exist.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
---
 .../src/components/shared/JsonLd.spec.tsx     |  46 +++++
 apps/website/src/components/shared/JsonLd.tsx |  13 ++
 apps/website/src/lib/structured-data.spec.ts  | 169 ++++++++++++++++++
 apps/website/src/lib/structured-data.ts       | 149 +++++++++++++++
 4 files changed, 377 insertions(+)
 create mode 100644 apps/website/src/components/shared/JsonLd.spec.tsx
 create mode 100644 apps/website/src/components/shared/JsonLd.tsx
 create mode 100644 apps/website/src/lib/structured-data.spec.ts
 create mode 100644 apps/website/src/lib/structured-data.ts

diff --git a/apps/website/src/components/shared/JsonLd.spec.tsx b/apps/website/src/components/shared/JsonLd.spec.tsx
new file mode 100644
index 000000000..b8626a6d2
--- /dev/null
+++ b/apps/website/src/components/shared/JsonLd.spec.tsx
@@ -0,0 +1,46 @@
+// @vitest-environment jsdom
+// SPDX-License-Identifier: MIT
+import { describe, expect, it } from 'vitest';
+import { render } from '@testing-library/react';
+import { JsonLd } from './JsonLd';
+
+function renderScript(data: Parameters<typeof JsonLd>[0]['data']): HTMLScriptElement {
+  const { container } = render(<JsonLd data={data} />);
+  const script = container.querySelector('script[type="application/ld+json"]');
+  expect(script).not.toBeNull();
+  return script as HTMLScriptElement;
+}
+
+describe('JsonLd', () => {
+  it('emits a parseable ld+json script', () => {
+    const script = renderScript({ '@type': 'Organization', name: 'Threadplane' });
+    expect(JSON.parse(script.textContent ?? '')).toEqual({
+      '@type': 'Organization',
+      name: 'Threadplane',
+    });
+  });
+
+  it('accepts an array of nodes', () => {
+    const script = renderScript([{ '@type': 'WebSite' }, { '@type': 'Organization' }]);
+    expect(JSON.parse(script.textContent ?? '')).toHaveLength(2);
+  });
+
+  it('escapes < so a value cannot close the script tag', () => {
+    const hostile = '</script><img src=x onerror=alert(1)>';
+    const script = renderScript({ '@type': 'Organization', name: hostile });
+
+    // The raw markup must contain no literal `<` inside the script body...
+    expect(script.innerHTML).not.toContain('<');
+    expect(script.innerHTML).toContain('\\u003c/script>');
+    // ...and the escape is lossless: the value round-trips exactly.
+    expect(JSON.parse(script.textContent ?? '')['name']).toBe(hostile);
+  });
+
+  it('does not inject a sibling element when a value looks like markup', () => {
+    const { container } = render(
+      <JsonLd data={{ name: '</script><b id="pwned">x</b>' }} />,
+    );
+    expect(container.querySelector('#pwned')).toBeNull();
+    expect(container.childElementCount).toBe(1);
+  });
+});
diff --git a/apps/website/src/components/shared/JsonLd.tsx b/apps/website/src/components/shared/JsonLd.tsx
new file mode 100644
index 000000000..8b46e224a
--- /dev/null
+++ b/apps/website/src/components/shared/JsonLd.tsx
@@ -0,0 +1,13 @@
+// SPDX-License-Identifier: MIT
+import type { JsonLdNode } from '../../lib/structured-data';
+
+/**
+ * Renders schema.org JSON-LD. Content is generated from our own data, never
+ * from user input, so `dangerouslySetInnerHTML` is safe here; `<` is still
+ * escaped so a stray value cannot close the script tag. `<` is a valid
+ * JSON string escape, so the escaped payload still parses back identically.
+ */
+export function JsonLd({ data }: { data: JsonLdNode | JsonLdNode[] }) {
+  const json = JSON.stringify(data).replace(/</g, '\\u003c');
+  return <script type="application/ld+json" dangerouslySetInnerHTML={{ __html: json }} />;
+}
diff --git a/apps/website/src/lib/structured-data.spec.ts b/apps/website/src/lib/structured-data.spec.ts
new file mode 100644
index 000000000..3f6541734
--- /dev/null
+++ b/apps/website/src/lib/structured-data.spec.ts
@@ -0,0 +1,169 @@
+// SPDX-License-Identifier: MIT
+import { describe, expect, it } from 'vitest';
+import {
+  breadcrumbJsonLd,
+  organizationJsonLd,
+  softwareSourceCodeJsonLd,
+  techArticleJsonLd,
+  websiteJsonLd,
+  blogPostingJsonLd,
+  type JsonLdNode,
+} from './structured-data';
+
+/** Every builder's output must survive a JSON round-trip unchanged. */
+function expectSerializable(data: JsonLdNode): Record<string, unknown> {
+  const json = JSON.stringify(data);
+  expect(() => JSON.parse(json)).not.toThrow();
+  return JSON.parse(json) as Record<string, unknown>;
+}
+
+describe('organizationJsonLd', () => {
+  it('describes Threadplane with an absolute url and logo', () => {
+    const data = organizationJsonLd();
+    expect(data['@type']).toBe('Organization');
+    expect(data['name']).toBe('Threadplane');
+    expect(String(data['url'])).toBe('https://threadplane.ai/');
+    expect(String(data['logo'])).toMatch(/^https:\/\/threadplane\.ai\//);
+  });
+
+  it('only links to profiles that exist', () => {
+    const sameAs = organizationJsonLd()['sameAs'] as string[];
+    expect(sameAs).toContain('https://github.com/cacheplane/angular-agent-framework');
+    for (const url of sameAs) expect(url).toMatch(/^https:\/\//);
+  });
+
+  it('serializes to JSON', () => {
+    expect(expectSerializable(organizationJsonLd())['@context']).toBe('https://schema.org');
+  });
+});
+
+describe('websiteJsonLd', () => {
+  it('is a WebSite node pointing at the origin', () => {
+    expect(websiteJsonLd()['@type']).toBe('WebSite');
+  });
+
+  it('attributes the site to the Organization node', () => {
+    const publisher = websiteJsonLd()['publisher'] as Record<string, unknown>;
+    expect(publisher['@id']).toBe(organizationJsonLd()['@id']);
+  });
+
+  it('serializes to JSON', () => {
+    expectSerializable(websiteJsonLd());
+  });
+});
+
+describe('blogPostingJsonLd', () => {
+  it('carries headline, dates, author, and absolute urls', () => {
+    const data = blogPostingJsonLd({
+      title: 'A Post',
+      description: 'About things.',
+      slug: 'a-post',
+      datePublished: '2026-08-13',
+      authorName: 'Brian Love',
+      tags: ['angular'],
+    });
+    expect(data['@type']).toBe('BlogPosting');
+    expect(data['headline']).toBe('A Post');
+    expect(data['datePublished']).toBe('2026-08-13');
+    expect(data['dateModified']).toBe('2026-08-13');
+    expect((data['author'] as Record<string, unknown>)['name']).toBe('Brian Love');
+    expect(String(data['url'])).toBe('https://threadplane.ai/blog/a-post');
+  });
+
+  it('prefers an explicit dateModified when one is known', () => {
+    const data = blogPostingJsonLd({
+      title: 'A Post',
+      description: 'About things.',
+      slug: 'a-post',
+      datePublished: '2026-08-13',
+      dateModified: '2026-08-19',
+      authorName: 'Brian Love',
+    });
+    expect(data['dateModified']).toBe('2026-08-19');
+  });
+
+  it('emits an absolute image url', () => {
+    const data = blogPostingJsonLd({
+      title: 'A Post',
+      description: 'About things.',
+      slug: 'a-post',
+      datePublished: '2026-08-13',
+      authorName: 'Brian Love',
+    });
+    expect(String(data['image'])).toMatch(/^https:\/\/threadplane\.ai\//);
+  });
+
+  it('serializes to JSON', () => {
+    expectSerializable(
+      blogPostingJsonLd({
+        title: 'A Post',
+        description: 'About things.',
+        slug: 'a-post',
+        datePublished: '2026-08-13',
+        authorName: 'Brian Love',
+      }),
+    );
+  });
+});
+
+describe('techArticleJsonLd', () => {
+  it('describes a docs page', () => {
+    const data = techArticleJsonLd({
+      title: 'Installation',
+      description: 'Install it.',
+      pathname: '/docs/chat/getting-started/installation',
+    });
+    expect(data['@type']).toBe('TechArticle');
+    expect(String(data['url'])).toBe('https://threadplane.ai/docs/chat/getting-started/installation');
+  });
+
+  it('omits dateModified entirely when none is known', () => {
+    const data = techArticleJsonLd({
+      title: 'Installation',
+      description: 'Install it.',
+      pathname: '/docs/chat/getting-started/installation',
+    });
+    expect('dateModified' in data).toBe(false);
+  });
+
+  it('serializes to JSON', () => {
+    expectSerializable(
+      techArticleJsonLd({ title: 'Installation', description: 'Install it.', pathname: '/docs' }),
+    );
+  });
+});
+
+describe('breadcrumbJsonLd', () => {
+  it('numbers positions from 1 and resolves absolute urls', () => {
+    const data = breadcrumbJsonLd([
+      { name: 'Docs', pathname: '/docs' },
+      { name: 'Chat', pathname: '/docs/chat' },
+    ]);
+    const items = data['itemListElement'] as Record<string, unknown>[];
+    expect(items).toHaveLength(2);
+    expect(items[0]['position']).toBe(1);
+    expect(String(items[1]['item'])).toBe('https://threadplane.ai/docs/chat');
+  });
+
+  it('serializes to JSON', () => {
+    expectSerializable(breadcrumbJsonLd([{ name: 'Docs', pathname: '/docs' }]));
+  });
+});
+
+describe('softwareSourceCodeJsonLd', () => {
+  it('marks Threadplane as an Angular TypeScript library', () => {
+    const data = softwareSourceCodeJsonLd();
+    expect(data['@type']).toBe('SoftwareSourceCode');
+    expect(data['programmingLanguage']).toBe('TypeScript');
+  });
+
+  it('points at the real repository', () => {
+    expect(softwareSourceCodeJsonLd()['codeRepository']).toBe(
+      'https://github.com/cacheplane/angular-agent-framework',
+    );
+  });
+
+  it('serializes to JSON', () => {
+    expectSerializable(softwareSourceCodeJsonLd());
+  });
+});
diff --git a/apps/website/src/lib/structured-data.ts b/apps/website/src/lib/structured-data.ts
new file mode 100644
index 000000000..1ba001389
--- /dev/null
+++ b/apps/website/src/lib/structured-data.ts
@@ -0,0 +1,149 @@
+// SPDX-License-Identifier: MIT
+import { DEFAULT_SOCIAL_IMAGE, getCanonicalUrl, SITE_NAME } from './site-metadata';
+import { SHORT_POSITIONING_DESCRIPTION } from './positioning';
+
+/** A single schema.org node, ready to be serialized into a `ld+json` script. */
+export type JsonLdNode = Record<string, unknown>;
+
+/**
+ * The canonical repository. Verified public; the npm *organization* page is
+ * member-gated, so `sameAs` links the public package page instead.
+ */
+const REPOSITORY_URL = 'https://github.com/cacheplane/angular-agent-framework';
+
+/**
+ * Stable identity for the publisher node. Every other node refers to the
+ * Organization by `@id` rather than repeating it, which is the schema.org way
+ * to express "same entity" across nodes.
+ *
+ * COUPLING: those references only resolve if the Organization node itself is
+ * present in the page's structured data. It is mounted once in the root layout
+ * (task 8), so it is on every route; if that mount is ever removed, these
+ * references become dangling.
+ *
+ * Computed at module load, which is safe because {@link getCanonicalUrl}
+ * resolves against a hardcoded `SITE_ORIGIN` constant — no env lookup, no
+ * request context, identical on server and client.
+ */
+const ORGANIZATION_ID = `${getCanonicalUrl('/')}#organization`;
+
+export function organizationJsonLd(): JsonLdNode {
+  return {
+    '@context': 'https://schema.org',
+    '@type': 'Organization',
+    '@id': ORGANIZATION_ID,
+    name: SITE_NAME,
+    url: getCanonicalUrl('/'),
+    // No standalone brand mark exists yet (the in-app LogoMark is inline JSX),
+    // so this points at the generated site social card: a real, crawlable PNG
+    // carrying the wordmark. Swap in a dedicated mark when one ships.
+    logo: getCanonicalUrl(DEFAULT_SOCIAL_IMAGE),
+    description:
+      'Threadplane builds the Angular UI layer for production agent applications on LangGraph and AG-UI-compatible runtimes.',
+    sameAs: [REPOSITORY_URL, 'https://www.npmjs.com/package/@threadplane/chat'],
+  };
+}
+
+export function websiteJsonLd(): JsonLdNode {
+  return {
+    '@context': 'https://schema.org',
+    '@type': 'WebSite',
+    '@id': `${getCanonicalUrl('/')}#website`,
+    name: SITE_NAME,
+    url: getCanonicalUrl('/'),
+    description: SHORT_POSITIONING_DESCRIPTION,
+    publisher: { '@id': ORGANIZATION_ID },
+  };
+}
+
+export function softwareSourceCodeJsonLd(): JsonLdNode {
+  return {
+    '@context': 'https://schema.org',
+    '@type': 'SoftwareSourceCode',
+    name: '@threadplane/chat',
+    description:
+      'Signal-native Angular chat UI primitives bound to a runtime-neutral Agent contract, with adapters for LangGraph and AG-UI.',
+    programmingLanguage: 'TypeScript',
+    runtimePlatform: 'Angular',
+    codeRepository: REPOSITORY_URL,
+    author: { '@id': ORGANIZATION_ID },
+    license: getCanonicalUrl('/docs/licensing'),
+  };
+}
+
+/** The subset of a blog post that schema.org cares about. */
+export interface BlogPostingInput {
+  title: string;
+  description: string;
+  slug: string;
+  /** ISO 8601 publish date or timestamp. */
+  datePublished: string;
+  /** ISO 8601 last-modified timestamp; falls back to `datePublished`. */
+  dateModified?: string;
+  authorName: string;
+  tags?: string[];
+}
+
+export function blogPostingJsonLd(post: BlogPostingInput): JsonLdNode {
+  const url = getCanonicalUrl(`/blog/${post.slug}`);
+  return {
+    '@context': 'https://schema.org',
+    '@type': 'BlogPosting',
+    headline: post.title,
+    description: post.description,
+    url,
+    mainEntityOfPage: url,
+    datePublished: post.datePublished,
+    // Same "unmodified" rule the OpenGraph metadata uses: a post with no known
+    // modification advertises its publish date.
+    dateModified: post.dateModified ?? post.datePublished,
+    // TODO(task 9): switch to `<pathname>/opengraph-image` once that route
+    // actually serves. It exists but currently 500s in production, and naming
+    // it here would advertise a broken image — same call task 6 made for
+    // og:image, kept consistent on purpose.
+    image: getCanonicalUrl(DEFAULT_SOCIAL_IMAGE),
+    keywords: post.tags,
+    // No `url` on the author until /about exists (task 11); a 404 author URL is
+    // worse than an unlinked name.
+    author: { '@type': 'Person', name: post.authorName },
+    publisher: { '@id': ORGANIZATION_ID },
+  };
+}
+
+/** The subset of a docs page that schema.org cares about. */
+export interface TechArticleInput {
+  title: string;
+  description: string;
+  pathname: string;
+  /** ISO 8601 last-modified timestamp; omitted from the node when unknown. */
+  dateModified?: string;
+}
+
+export function techArticleJsonLd(doc: TechArticleInput): JsonLdNode {
+  const url = getCanonicalUrl(doc.pathname);
+  return {
+    '@context': 'https://schema.org',
+    '@type': 'TechArticle',
+    headline: doc.title,
+    description: doc.description,
+    url,
+    mainEntityOfPage: url,
+    ...(doc.dateModified ? { dateModified: doc.dateModified } : {}),
+    author: { '@id': ORGANIZATION_ID },
+    publisher: { '@id': ORGANIZATION_ID },
+    proficiencyLevel: 'Expert',
+  };
+}
+
+export function breadcrumbJsonLd(crumbs: { name: string; pathname: string }[]): JsonLdNode {
+  return {
+    '@context': 'https://schema.org',
+    '@type': 'BreadcrumbList',
+    itemListElement: crumbs.map((crumb, index) => ({
+      '@type': 'ListItem',
+      position: index + 1,
+      name: crumb.name,
+      item: getCanonicalUrl(crumb.pathname),
+    })),
+  };
+}

From 4df555f0adaca8bc7b9352c294ee3a1631a28ee3 Mon Sep 17 00:00:00 2001
From: Brian Love <brian@liveloveapp.com>
Date: Thu, 20 Aug 2026 13:12:47 -0700
Subject: [PATCH 17/35] test(website): make json-ld round-trip assertions real

expectSerializable claimed a round-trip but never compared the parsed result
to the input, so JSON.parse(JSON.stringify(obj)) could not fail and the six
"serializes to JSON" tests were vacuous. Adding toStrictEqual immediately
caught blogPostingJsonLd leaving an undefined-valued `keywords` key when a
post has no tags, where techArticleJsonLd already used the omit pattern for
dateModified; both builders now agree.

Also adds table-driven coverage of @context and the Organization @id
reference across every builder that carries one, a rootJsonLd() @graph that
makes the three root-layout nodes physically inseparable so an @id reference
cannot be orphaned by mounting a subset, and an exported BreadcrumbCrumb type.

Drops Organization.logo: a 1200x630 marketing social card is not a brand
mark, and no square mark exists in the repo. Omitting is honest; the property
should be restored once a real mark ships.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
---
 apps/website/src/components/shared/JsonLd.tsx |  19 +-
 apps/website/src/lib/structured-data.spec.ts  | 188 ++++++++++++------
 apps/website/src/lib/structured-data.ts       |  77 +++++--
 3 files changed, 198 insertions(+), 86 deletions(-)

diff --git a/apps/website/src/components/shared/JsonLd.tsx b/apps/website/src/components/shared/JsonLd.tsx
index 8b46e224a..6c4f0de7e 100644
--- a/apps/website/src/components/shared/JsonLd.tsx
+++ b/apps/website/src/components/shared/JsonLd.tsx
@@ -2,10 +2,21 @@
 import type { JsonLdNode } from '../../lib/structured-data';
 
 /**
- * Renders schema.org JSON-LD. Content is generated from our own data, never
- * from user input, so `dangerouslySetInnerHTML` is safe here; `<` is still
- * escaped so a stray value cannot close the script tag. `<` is a valid
- * JSON string escape, so the escaped payload still parses back identically.
+ * Renders schema.org JSON-LD.
+ *
+ * React does not escape the body of a `<script>`, so the payload is written with
+ * `dangerouslySetInnerHTML` and every `<` character is replaced by the six-byte
+ * escape sequence `\u003c`. That replacement is what makes this safe,
+ * unconditionally: no value can emit a literal `<`, so no value can close the
+ * script tag and start injecting markup — whatever the value is and wherever it
+ * came from.
+ *
+ * This is not merely belt-and-braces over trusted input. Some of what flows
+ * through here (blog headlines, descriptions) is MDX frontmatter: our own
+ * content, but content rather than code.
+ *
+ * `\u003c` is a standard JSON string escape, so the escaped payload parses back to
+ * exactly the original value — see the round-trip assertion in the spec.
  */
 export function JsonLd({ data }: { data: JsonLdNode | JsonLdNode[] }) {
   const json = JSON.stringify(data).replace(/</g, '\\u003c');
diff --git a/apps/website/src/lib/structured-data.spec.ts b/apps/website/src/lib/structured-data.spec.ts
index 3f6541734..f31d68e22 100644
--- a/apps/website/src/lib/structured-data.spec.ts
+++ b/apps/website/src/lib/structured-data.spec.ts
@@ -3,6 +3,7 @@ import { describe, expect, it } from 'vitest';
 import {
   breadcrumbJsonLd,
   organizationJsonLd,
+  rootJsonLd,
   softwareSourceCodeJsonLd,
   techArticleJsonLd,
   websiteJsonLd,
@@ -10,24 +11,47 @@ import {
   type JsonLdNode,
 } from './structured-data';
 
+const ORGANIZATION_ID = 'https://threadplane.ai/#organization';
+
+const SAMPLE_POST = {
+  title: 'A Post',
+  description: 'About things.',
+  slug: 'a-post',
+  datePublished: '2026-08-13',
+  authorName: 'Brian Love',
+} as const;
+
+const SAMPLE_DOC = {
+  title: 'Installation',
+  description: 'Install it.',
+  pathname: '/docs/chat/getting-started/installation',
+} as const;
+
 /** Every builder's output must survive a JSON round-trip unchanged. */
-function expectSerializable(data: JsonLdNode): Record<string, unknown> {
+function expectSerializable<T extends JsonLdNode>(data: T): Record<string, unknown> {
   const json = JSON.stringify(data);
   expect(() => JSON.parse(json)).not.toThrow();
-  return JSON.parse(json) as Record<string, unknown>;
+  const parsed = JSON.parse(json) as Record<string, unknown>;
+  // The real assertion: nothing is lost or invented by serialization. This is
+  // what catches an `undefined`-valued key that `JSON.stringify` silently drops.
+  expect(parsed).toStrictEqual(data);
+  return parsed;
 }
 
 describe('organizationJsonLd', () => {
-  it('describes Threadplane with an absolute url and logo', () => {
+  it('describes Threadplane with an absolute url', () => {
     const data = organizationJsonLd();
     expect(data['@type']).toBe('Organization');
     expect(data['name']).toBe('Threadplane');
     expect(String(data['url'])).toBe('https://threadplane.ai/');
-    expect(String(data['logo'])).toMatch(/^https:\/\/threadplane\.ai\//);
   });
 
-  it('only links to profiles that exist', () => {
-    const sameAs = organizationJsonLd()['sameAs'] as string[];
+  it('omits logo entirely rather than passing off the social card as a mark', () => {
+    expect('logo' in organizationJsonLd()).toBe(false);
+  });
+
+  it('links only to absolute https profile urls', () => {
+    const sameAs = organizationJsonLd()['sameAs'];
     expect(sameAs).toContain('https://github.com/cacheplane/angular-agent-framework');
     for (const url of sameAs) expect(url).toMatch(/^https:\/\//);
   });
@@ -42,109 +66,110 @@ describe('websiteJsonLd', () => {
     expect(websiteJsonLd()['@type']).toBe('WebSite');
   });
 
-  it('attributes the site to the Organization node', () => {
-    const publisher = websiteJsonLd()['publisher'] as Record<string, unknown>;
-    expect(publisher['@id']).toBe(organizationJsonLd()['@id']);
+  it('serializes to JSON', () => {
+    expectSerializable(websiteJsonLd());
+  });
+});
+
+describe('rootJsonLd', () => {
+  it('bundles the three site-wide nodes into one @graph', () => {
+    const graph = rootJsonLd()['@graph'];
+    expect(graph.map((node) => node['@type'])).toEqual([
+      'Organization',
+      'WebSite',
+      'SoftwareSourceCode',
+    ]);
+  });
+
+  it('carries a single @context for the whole graph', () => {
+    const data = rootJsonLd();
+    expect(data['@context']).toBe('https://schema.org');
+    for (const node of data['@graph']) expect('@context' in node).toBe(false);
+  });
+
+  it('resolves every @id reference inside the graph it ships', () => {
+    const graph = rootJsonLd()['@graph'];
+    const ids = new Set(graph.map((node) => node['@id']).filter(Boolean));
+    expect(ids.has(ORGANIZATION_ID)).toBe(true);
+
+    // The referring nodes point at a node that is physically in this same graph.
+    const website = graph.find((node) => node['@type'] === 'WebSite');
+    const software = graph.find((node) => node['@type'] === 'SoftwareSourceCode');
+    expect((website?.['publisher'] as JsonLdNode)['@id']).toBe(ORGANIZATION_ID);
+    expect((software?.['author'] as JsonLdNode)['@id']).toBe(ORGANIZATION_ID);
   });
 
   it('serializes to JSON', () => {
-    expectSerializable(websiteJsonLd());
+    expectSerializable(rootJsonLd());
   });
 });
 
 describe('blogPostingJsonLd', () => {
   it('carries headline, dates, author, and absolute urls', () => {
-    const data = blogPostingJsonLd({
-      title: 'A Post',
-      description: 'About things.',
-      slug: 'a-post',
-      datePublished: '2026-08-13',
-      authorName: 'Brian Love',
-      tags: ['angular'],
-    });
+    const data = blogPostingJsonLd({ ...SAMPLE_POST, tags: ['angular'] });
     expect(data['@type']).toBe('BlogPosting');
     expect(data['headline']).toBe('A Post');
     expect(data['datePublished']).toBe('2026-08-13');
     expect(data['dateModified']).toBe('2026-08-13');
-    expect((data['author'] as Record<string, unknown>)['name']).toBe('Brian Love');
+    expect(data['author']['name']).toBe('Brian Love');
     expect(String(data['url'])).toBe('https://threadplane.ai/blog/a-post');
   });
 
   it('prefers an explicit dateModified when one is known', () => {
-    const data = blogPostingJsonLd({
-      title: 'A Post',
-      description: 'About things.',
-      slug: 'a-post',
-      datePublished: '2026-08-13',
-      dateModified: '2026-08-19',
-      authorName: 'Brian Love',
-    });
+    const data = blogPostingJsonLd({ ...SAMPLE_POST, dateModified: '2026-08-19' });
     expect(data['dateModified']).toBe('2026-08-19');
   });
 
   it('emits an absolute image url', () => {
-    const data = blogPostingJsonLd({
-      title: 'A Post',
-      description: 'About things.',
-      slug: 'a-post',
-      datePublished: '2026-08-13',
-      authorName: 'Brian Love',
-    });
-    expect(String(data['image'])).toMatch(/^https:\/\/threadplane\.ai\//);
+    expect(String(blogPostingJsonLd(SAMPLE_POST)['image'])).toMatch(/^https:\/\/threadplane\.ai\//);
+  });
+
+  it('omits keywords entirely for an untagged post', () => {
+    expect('keywords' in blogPostingJsonLd(SAMPLE_POST)).toBe(false);
+    expect('keywords' in blogPostingJsonLd({ ...SAMPLE_POST, tags: [] })).toBe(false);
   });
 
   it('serializes to JSON', () => {
-    expectSerializable(
-      blogPostingJsonLd({
-        title: 'A Post',
-        description: 'About things.',
-        slug: 'a-post',
-        datePublished: '2026-08-13',
-        authorName: 'Brian Love',
-      }),
-    );
+    expectSerializable(blogPostingJsonLd(SAMPLE_POST));
+    expectSerializable(blogPostingJsonLd({ ...SAMPLE_POST, tags: ['angular'] }));
   });
 });
 
 describe('techArticleJsonLd', () => {
   it('describes a docs page', () => {
-    const data = techArticleJsonLd({
-      title: 'Installation',
-      description: 'Install it.',
-      pathname: '/docs/chat/getting-started/installation',
-    });
+    const data = techArticleJsonLd(SAMPLE_DOC);
     expect(data['@type']).toBe('TechArticle');
     expect(String(data['url'])).toBe('https://threadplane.ai/docs/chat/getting-started/installation');
   });
 
   it('omits dateModified entirely when none is known', () => {
-    const data = techArticleJsonLd({
-      title: 'Installation',
-      description: 'Install it.',
-      pathname: '/docs/chat/getting-started/installation',
-    });
-    expect('dateModified' in data).toBe(false);
+    expect('dateModified' in techArticleJsonLd(SAMPLE_DOC)).toBe(false);
   });
 
   it('serializes to JSON', () => {
-    expectSerializable(
-      techArticleJsonLd({ title: 'Installation', description: 'Install it.', pathname: '/docs' }),
-    );
+    expectSerializable(techArticleJsonLd(SAMPLE_DOC));
+    expectSerializable(techArticleJsonLd({ ...SAMPLE_DOC, dateModified: '2026-08-19' }));
   });
 });
 
 describe('breadcrumbJsonLd', () => {
   it('numbers positions from 1 and resolves absolute urls', () => {
-    const data = breadcrumbJsonLd([
+    const items = breadcrumbJsonLd([
       { name: 'Docs', pathname: '/docs' },
       { name: 'Chat', pathname: '/docs/chat' },
-    ]);
-    const items = data['itemListElement'] as Record<string, unknown>[];
+    ])['itemListElement'];
     expect(items).toHaveLength(2);
     expect(items[0]['position']).toBe(1);
     expect(String(items[1]['item'])).toBe('https://threadplane.ai/docs/chat');
   });
 
+  it('emits an empty itemListElement for an empty trail', () => {
+    // Documenting, not endorsing: Google rejects a BreadcrumbList with no items.
+    // No runtime guard here on purpose — task 8 owns the call sites and must not
+    // hand this builder an empty array.
+    expect(breadcrumbJsonLd([])['itemListElement']).toEqual([]);
+  });
+
   it('serializes to JSON', () => {
     expectSerializable(breadcrumbJsonLd([{ name: 'Docs', pathname: '/docs' }]));
   });
@@ -167,3 +192,44 @@ describe('softwareSourceCodeJsonLd', () => {
     expectSerializable(softwareSourceCodeJsonLd());
   });
 });
+
+/**
+ * Cross-cutting invariants. Asserting these per-builder is what stops one
+ * builder from quietly drifting — a dropped `@context` or a `#Organization`
+ * typo in a single node would otherwise sail through.
+ */
+describe('shared node invariants', () => {
+  const standaloneBuilders: [string, () => JsonLdNode][] = [
+    ['organizationJsonLd', organizationJsonLd],
+    ['websiteJsonLd', websiteJsonLd],
+    ['softwareSourceCodeJsonLd', softwareSourceCodeJsonLd],
+    ['blogPostingJsonLd', () => blogPostingJsonLd(SAMPLE_POST)],
+    ['techArticleJsonLd', () => techArticleJsonLd(SAMPLE_DOC)],
+    ['breadcrumbJsonLd', () => breadcrumbJsonLd([{ name: 'Docs', pathname: '/docs' }])],
+  ];
+
+  it.each(standaloneBuilders)('%s declares the schema.org @context', (_name, build) => {
+    expect(build()['@context']).toBe('https://schema.org');
+  });
+
+  it.each(standaloneBuilders)('%s declares an @type', (_name, build) => {
+    expect(typeof build()['@type']).toBe('string');
+  });
+
+  // Every node that names the Organization must name the *same* Organization.
+  const organizationReferences: [string, string, () => JsonLdNode][] = [
+    ['websiteJsonLd', 'publisher', websiteJsonLd],
+    ['softwareSourceCodeJsonLd', 'author', softwareSourceCodeJsonLd],
+    ['blogPostingJsonLd', 'publisher', () => blogPostingJsonLd(SAMPLE_POST)],
+    ['techArticleJsonLd', 'author', () => techArticleJsonLd(SAMPLE_DOC)],
+    ['techArticleJsonLd', 'publisher', () => techArticleJsonLd(SAMPLE_DOC)],
+  ];
+
+  it.each(organizationReferences)('%s.%s references the Organization by @id', (_name, key, build) => {
+    expect((build()[key] as JsonLdNode)['@id']).toBe(ORGANIZATION_ID);
+  });
+
+  it('references the id the Organization node actually declares', () => {
+    expect(organizationJsonLd()['@id']).toBe(ORGANIZATION_ID);
+  });
+});
diff --git a/apps/website/src/lib/structured-data.ts b/apps/website/src/lib/structured-data.ts
index 1ba001389..601eb8489 100644
--- a/apps/website/src/lib/structured-data.ts
+++ b/apps/website/src/lib/structured-data.ts
@@ -5,6 +5,8 @@ import { SHORT_POSITIONING_DESCRIPTION } from './positioning';
 /** A single schema.org node, ready to be serialized into a `ld+json` script. */
 export type JsonLdNode = Record<string, unknown>;
 
+const SCHEMA_CONTEXT = 'https://schema.org';
+
 /**
  * The canonical repository. Verified public; the npm *organization* page is
  * member-gated, so `sameAs` links the public package page instead.
@@ -16,10 +18,10 @@ const REPOSITORY_URL = 'https://github.com/cacheplane/angular-agent-framework';
  * Organization by `@id` rather than repeating it, which is the schema.org way
  * to express "same entity" across nodes.
  *
- * COUPLING: those references only resolve if the Organization node itself is
- * present in the page's structured data. It is mounted once in the root layout
- * (task 8), so it is on every route; if that mount is ever removed, these
- * references become dangling.
+ * Those references only resolve if the Organization node is present in the same
+ * page's structured data. {@link rootJsonLd} is what guarantees that: it bundles
+ * Organization with the other root nodes into one `@graph`, so a caller cannot
+ * mount a referring node without its referent.
  *
  * Computed at module load, which is safe because {@link getCanonicalUrl}
  * resolves against a hardcoded `SITE_ORIGIN` constant — no env lookup, no
@@ -27,26 +29,27 @@ const REPOSITORY_URL = 'https://github.com/cacheplane/angular-agent-framework';
  */
 const ORGANIZATION_ID = `${getCanonicalUrl('/')}#organization`;
 
-export function organizationJsonLd(): JsonLdNode {
+export function organizationJsonLd() {
   return {
-    '@context': 'https://schema.org',
+    '@context': SCHEMA_CONTEXT,
     '@type': 'Organization',
     '@id': ORGANIZATION_ID,
     name: SITE_NAME,
     url: getCanonicalUrl('/'),
-    // No standalone brand mark exists yet (the in-app LogoMark is inline JSX),
-    // so this points at the generated site social card: a real, crawlable PNG
-    // carrying the wordmark. Swap in a dedicated mark when one ships.
-    logo: getCanonicalUrl(DEFAULT_SOCIAL_IMAGE),
+    // No `logo`: there is no square brand mark in the repo (the in-app LogoMark
+    // renders an emoji), and the generated social card is a 1200x630 marketing
+    // image, not a mark — it would satisfy Google's format floor while asserting
+    // something false about the brand. Restore this property once a real square
+    // mark ships in `public/logos/`.
     description:
       'Threadplane builds the Angular UI layer for production agent applications on LangGraph and AG-UI-compatible runtimes.',
     sameAs: [REPOSITORY_URL, 'https://www.npmjs.com/package/@threadplane/chat'],
   };
 }
 
-export function websiteJsonLd(): JsonLdNode {
+export function websiteJsonLd() {
   return {
-    '@context': 'https://schema.org',
+    '@context': SCHEMA_CONTEXT,
     '@type': 'WebSite',
     '@id': `${getCanonicalUrl('/')}#website`,
     name: SITE_NAME,
@@ -56,9 +59,9 @@ export function websiteJsonLd(): JsonLdNode {
   };
 }
 
-export function softwareSourceCodeJsonLd(): JsonLdNode {
+export function softwareSourceCodeJsonLd() {
   return {
-    '@context': 'https://schema.org',
+    '@context': SCHEMA_CONTEXT,
     '@type': 'SoftwareSourceCode',
     name: '@threadplane/chat',
     description:
@@ -71,6 +74,31 @@ export function softwareSourceCodeJsonLd(): JsonLdNode {
   };
 }
 
+/**
+ * The site-wide nodes, bundled into a single `@graph` so they are physically
+ * inseparable: mounting this cannot orphan the `@id` references that WebSite and
+ * SoftwareSourceCode make to the Organization, because the Organization travels
+ * with them. `@graph` is the conventional shape for a multi-entity page and
+ * consumers parse it identically to sibling nodes.
+ *
+ * Mounted once, in the root layout.
+ */
+export function rootJsonLd() {
+  // Annotated: the graph is deliberately heterogeneous, so `JsonLdNode[]` is the
+  // honest element type. The individual builders keep their inferred shapes.
+  const nodes: JsonLdNode[] = [organizationJsonLd(), websiteJsonLd(), softwareSourceCodeJsonLd()];
+  return {
+    '@context': SCHEMA_CONTEXT,
+    // One `@context` for the whole graph; repeating it per node is redundant.
+    // Per-route builders keep theirs, since they are mounted standalone.
+    '@graph': nodes.map((node) => {
+      const stripped = { ...node };
+      delete stripped['@context'];
+      return stripped;
+    }),
+  };
+}
+
 /** The subset of a blog post that schema.org cares about. */
 export interface BlogPostingInput {
   title: string;
@@ -84,10 +112,10 @@ export interface BlogPostingInput {
   tags?: string[];
 }
 
-export function blogPostingJsonLd(post: BlogPostingInput): JsonLdNode {
+export function blogPostingJsonLd(post: BlogPostingInput) {
   const url = getCanonicalUrl(`/blog/${post.slug}`);
   return {
-    '@context': 'https://schema.org',
+    '@context': SCHEMA_CONTEXT,
     '@type': 'BlogPosting',
     headline: post.title,
     description: post.description,
@@ -102,7 +130,8 @@ export function blogPostingJsonLd(post: BlogPostingInput): JsonLdNode {
     // it here would advertise a broken image — same call task 6 made for
     // og:image, kept consistent on purpose.
     image: getCanonicalUrl(DEFAULT_SOCIAL_IMAGE),
-    keywords: post.tags,
+    // Omitted rather than left undefined, matching `dateModified` below.
+    ...(post.tags?.length ? { keywords: post.tags } : {}),
     // No `url` on the author until /about exists (task 11); a 404 author URL is
     // worse than an unlinked name.
     author: { '@type': 'Person', name: post.authorName },
@@ -119,10 +148,10 @@ export interface TechArticleInput {
   dateModified?: string;
 }
 
-export function techArticleJsonLd(doc: TechArticleInput): JsonLdNode {
+export function techArticleJsonLd(doc: TechArticleInput) {
   const url = getCanonicalUrl(doc.pathname);
   return {
-    '@context': 'https://schema.org',
+    '@context': SCHEMA_CONTEXT,
     '@type': 'TechArticle',
     headline: doc.title,
     description: doc.description,
@@ -135,9 +164,15 @@ export function techArticleJsonLd(doc: TechArticleInput): JsonLdNode {
   };
 }
 
-export function breadcrumbJsonLd(crumbs: { name: string; pathname: string }[]): JsonLdNode {
+/** One rung of a breadcrumb trail, from the site root down to the current page. */
+export interface BreadcrumbCrumb {
+  name: string;
+  pathname: string;
+}
+
+export function breadcrumbJsonLd(crumbs: BreadcrumbCrumb[]) {
   return {
-    '@context': 'https://schema.org',
+    '@context': SCHEMA_CONTEXT,
     '@type': 'BreadcrumbList',
     itemListElement: crumbs.map((crumb, index) => ({
       '@type': 'ListItem',

From f47e15b75ae588a87710a396fb0e757776e11e79 Mon Sep 17 00:00:00 2001
From: Brian Love <brian@liveloveapp.com>
Date: Thu, 20 Aug 2026 13:17:52 -0700
Subject: [PATCH 18/35] feat(website): mount json-ld on layout, blog, and docs

Root layout mounts `rootJsonLd()` as a single `@graph`, so the Organization
node travels with every page and the `@id` references made by BlogPosting and
TechArticle always resolve.

Blog posts emit BlogPosting + BreadcrumbList; docs pages emit TechArticle +
BreadcrumbList. Both reuse the exact sources their `generateMetadata` already
uses, so `dateModified`, `og:modified_time`, and the sitemap `<lastmod>` agree:
`getPostLastModified()` factors the single-post date derivation the blog route
had inline, and `resolveDocDescription()` exposes the description accessor that
`getDocMetadata()` builds the meta description from.

The docs breadcrumb links its library rung at that library's introduction page,
mirroring the visible <DocsBreadcrumb>; `/docs/<library>` has no route and would
have been a crumb pointing at a 404.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
---
 apps/website/src/app/blog/[slug]/page.tsx     | 31 +++++++++++--
 .../docs/[library]/[section]/[slug]/page.tsx  | 39 ++++++++++++++++-
 apps/website/src/app/layout.tsx               | 10 +++++
 apps/website/src/lib/docs.spec.ts             | 43 ++++++++++++++++++-
 apps/website/src/lib/docs.ts                  | 16 ++++++-
 apps/website/src/lib/sitemap-dates.spec.ts    | 22 +++++++++-
 apps/website/src/lib/sitemap-dates.ts         | 15 +++++++
 7 files changed, 167 insertions(+), 9 deletions(-)

diff --git a/apps/website/src/app/blog/[slug]/page.tsx b/apps/website/src/app/blog/[slug]/page.tsx
index a3bed5312..2078ddbf0 100644
--- a/apps/website/src/app/blog/[slug]/page.tsx
+++ b/apps/website/src/app/blog/[slug]/page.tsx
@@ -10,7 +10,9 @@ import { getAllPosts, getPostBySlug, formatPostDate, readingTimeMin } from '../.
 import { getAuthor } from '../../../lib/blog-authors';
 import { extractHeadings } from '../../../lib/extract-headings';
 import { createPageMetadata } from '../../../lib/site-metadata';
-import { getRouteLastModified, publishedDate } from '../../../lib/sitemap-dates';
+import { getPostLastModified, publishedDate } from '../../../lib/sitemap-dates';
+import { JsonLd } from '../../../components/shared/JsonLd';
+import { blogPostingJsonLd, breadcrumbJsonLd } from '../../../lib/structured-data';
 
 interface Params {
   params: Promise<{ slug: string }>;
@@ -28,9 +30,7 @@ export async function generateMetadata({ params }: Params): Promise<Metadata> {
   }
   const author = getAuthor(post.frontmatter.author);
   const pathname = `/blog/${post.slug}`;
-  // The post is already resolved, so index just it: no drafts policy to inherit
-  // and no second read of the blog directory.
-  const lastModified = getRouteLastModified(pathname, new Map([[pathname, post]]));
+  const lastModified = getPostLastModified(post);
   // Undefined for an unparseable frontmatter date, which drops the article
   // block rather than shipping the bad string as `article:published_time`.
   const published = publishedDate(post);
@@ -64,9 +64,32 @@ export default async function BlogPostPage({ params }: Params) {
     ? post.frontmatter.tags[0].toUpperCase()
     : 'POST';
   const headings = extractHeadings(post.content);
+  // Same derivation `generateMetadata` uses for `article:modified_time`, and the
+  // same one the sitemap uses for `<lastmod>`, so all three agree.
+  const lastModified = getPostLastModified(post);
+  const published = publishedDate(post);
 
   return (
     <div style={{ paddingTop: 80, background: tokens.surfaces.canvas, minHeight: '100vh' }}>
+      {published ? (
+        <JsonLd
+          data={blogPostingJsonLd({
+            title: post.frontmatter.title,
+            description: post.frontmatter.description,
+            slug: post.slug,
+            datePublished: published.toISOString(),
+            dateModified: lastModified?.toISOString(),
+            authorName: author.name,
+            tags: post.frontmatter.tags,
+          })}
+        />
+      ) : null}
+      <JsonLd
+        data={breadcrumbJsonLd([
+          { name: 'Blog', pathname: '/blog' },
+          { name: post.frontmatter.title, pathname: `/blog/${post.slug}` },
+        ])}
+      />
       <div
         style={{
           display: 'flex',
diff --git a/apps/website/src/app/docs/[library]/[section]/[slug]/page.tsx b/apps/website/src/app/docs/[library]/[section]/[slug]/page.tsx
index bf4cad00b..4d1de379f 100644
--- a/apps/website/src/app/docs/[library]/[section]/[slug]/page.tsx
+++ b/apps/website/src/app/docs/[library]/[section]/[slug]/page.tsx
@@ -8,7 +8,10 @@ import { DocsBreadcrumb } from '../../../../../components/docs/DocsBreadcrumb';
 import { DocsPageHeader } from '../../../../../components/docs/DocsPageHeader';
 import { PageActions } from '../../../../../components/docs/PageActions';
 import { DocsPrevNext } from '../../../../../components/docs/DocsPrevNext';
-import { getDocBySlug, getAllDocSlugs, getDocMetadata } from '../../../../../lib/docs';
+import { getDocBySlug, getAllDocSlugs, getDocMetadata, resolveDocDescription } from '../../../../../lib/docs';
+import { JsonLd } from '../../../../../components/shared/JsonLd';
+import { breadcrumbJsonLd, techArticleJsonLd } from '../../../../../lib/structured-data';
+import { getRouteLastModified } from '../../../../../lib/sitemap-dates';
 import { ApiDocRenderer, type ApiDocEntry } from '../../../../../components/docs/ApiDocRenderer';
 import { DocsTOC } from '../../../../../components/docs/DocsTOC';
 import { extractHeadings } from '../../../../../lib/extract-headings';
@@ -52,11 +55,45 @@ export default async function DocsPage({ params }: DocsRouteProps) {
   const doc = getDocBySlug(library, section, slug);
   if (!doc) notFound();
 
+  const pathname = `/docs/${library}/${section}/${slug}`;
+  // The empty post index is the honest one here: `getRouteLastModified` consults
+  // it only to recognise a blog route, and no /docs route is ever a post, so
+  // passing an index costs a blog-directory read and changes nothing. The
+  // sitemap resolves this same route through the same file-source path, so the
+  // two `dateModified` claims agree.
+  const lastModified = getRouteLastModified(pathname, new Map());
+
   return (
     <div
       className="flex min-h-screen overflow-x-hidden"
       style={{ background: tokens.surfaces.canvas, paddingTop: 80 }}
     >
+      <JsonLd
+        data={techArticleJsonLd({
+          title: doc.title,
+          // Exactly the string `generateMetadata` puts in the meta description.
+          description: resolveDocDescription(doc, library),
+          pathname,
+          dateModified: lastModified?.toISOString(),
+        })}
+      />
+      <JsonLd
+        data={breadcrumbJsonLd([
+          { name: 'Docs', pathname: '/docs' },
+          // Mirrors the visible <DocsBreadcrumb>, which links the library at its
+          // introduction page: there is no /docs/<library> route (no page.tsx
+          // under src/app/docs/[library], and it is absent from the sitemap), so
+          // the plan's `/docs/${library}` would point a crumb at a 404.
+          //
+          // The section rung the visible trail shows between library and page is
+          // deliberately absent: it is plain text there because no section index
+          // route exists, and a non-final BreadcrumbList item with no `item` URL
+          // is invalid. Omitting it is closer to the visible trail than inventing
+          // a URL for it.
+          { name: libConfig.title, pathname: `/docs/${library}/getting-started/introduction` },
+          { name: doc.title, pathname },
+        ])}
+      />
       <DocsSearch library={library as LibraryId} />
       <DocsSidebar activeLibrary={library as LibraryId} activeSection={section} activeSlug={slug} />
       <div
diff --git a/apps/website/src/app/layout.tsx b/apps/website/src/app/layout.tsx
index e567dd5c3..dcf4d972c 100644
--- a/apps/website/src/app/layout.tsx
+++ b/apps/website/src/app/layout.tsx
@@ -4,6 +4,8 @@ import './global.css';
 import { Nav } from '../components/shared/Nav';
 import { Footer } from '../components/shared/Footer';
 import { AnnouncementToast } from '../components/shared/AnnouncementToast';
+import { JsonLd } from '../components/shared/JsonLd';
+import { rootJsonLd } from '../lib/structured-data';
 import {
   DEFAULT_META_DESCRIPTION,
   DEFAULT_SOCIAL_IMAGE,
@@ -57,6 +59,14 @@ export default function RootLayout({ children }: { children: React.ReactNode })
   return (
     <html lang="en" className={`${garamond.variable} ${inter.variable} ${mono.variable}`}>
       <body>
+        {/*
+          Site-wide structured data, mounted once here so it is present on every
+          route. Per-route nodes (BlogPosting, TechArticle) reference the
+          Organization by `@id`; those references only resolve because this
+          renders alongside them. `rootJsonLd()` is a single `@graph` for that
+          reason — do not mount its component builders individually.
+        */}
+        <JsonLd data={rootJsonLd()} />
         <Nav />
         <main>{children}</main>
         <Footer />
diff --git a/apps/website/src/lib/docs.spec.ts b/apps/website/src/lib/docs.spec.ts
index 2a986ecd2..4582699f7 100644
--- a/apps/website/src/lib/docs.spec.ts
+++ b/apps/website/src/lib/docs.spec.ts
@@ -2,8 +2,8 @@ import { describe, expect, it } from 'vitest';
 import fs from 'fs';
 import path from 'path';
 import { fileURLToPath } from 'url';
-import { getAllDocSlugs, getDocBySlug, getDocMetadata } from './docs';
-import { allDocsPages, findDocsPage, specialDocsPages } from './docs-config';
+import { getAllDocSlugs, getDocBySlug, getDocMetadata, resolveDocDescription } from './docs';
+import { allDocsPages, docsConfig, findDocsPage, specialDocsPages } from './docs-config';
 import { getCanonicalUrl, getSitemapRoutes } from './site-metadata';
 
 const internalDocsLinkPattern = /(?:href=["']|\]\()(?<href>\/docs\/[^"')#\s]+)/g;
@@ -259,3 +259,42 @@ describe('website docs bindings', () => {
     expect(getDocMetadata('langgraph', 'guides', 'nonexistent')).toBeNull();
   });
 });
+
+describe('docs structured-data inputs', () => {
+  // The docs page builds its TechArticle description from this accessor while
+  // `generateMetadata` builds the meta description from `getDocMetadata`. If
+  // they ever diverge the page tells crawlers two different things about itself.
+  it('resolves the same description the page metadata publishes', () => {
+    const mismatched: string[] = [];
+
+    for (const { library, section, slug } of getAllDocSlugs()) {
+      const doc = getDocBySlug(library, section, slug);
+      if (!doc) continue;
+      const description = resolveDocDescription(doc, library);
+      // Guards the comparison below from passing on two undefineds.
+      expect(typeof description === 'string' && description.length > 0).toBe(true);
+      if (description !== getDocMetadata(library, section, slug)?.description) {
+        mismatched.push(`${library}/${section}/${slug}`);
+      }
+    }
+
+    expect(mismatched).toEqual([]);
+  });
+
+  // The docs BreadcrumbList links its library rung at that library's
+  // introduction page, mirroring the visible <DocsBreadcrumb>. There is no
+  // `/docs/<library>` index route, so a crumb pointing there would 404 — this
+  // pins both halves of that: the intro page exists, and the bare library path
+  // does not.
+  it('links every library breadcrumb rung at a route that exists', () => {
+    const routes = new Set(getSitemapRoutes());
+
+    for (const library of docsConfig) {
+      expect([library.id, routes.has(`/docs/${library.id}/getting-started/introduction`)]).toEqual([
+        library.id,
+        true,
+      ]);
+      expect([library.id, routes.has(`/docs/${library.id}`)]).toEqual([library.id, false]);
+    }
+  });
+});
diff --git a/apps/website/src/lib/docs.ts b/apps/website/src/lib/docs.ts
index 02b57ec13..000ed415d 100644
--- a/apps/website/src/lib/docs.ts
+++ b/apps/website/src/lib/docs.ts
@@ -76,6 +76,20 @@ export function getDocBySlug(library: string, section: string, slug: string): Re
   };
 }
 
+/**
+ * The description a docs page advertises about itself: frontmatter when present,
+ * otherwise its first real paragraph, otherwise the library blurb.
+ *
+ * A `ResolvedDoc` carries no `description` field of its own — it is derived from
+ * the MDX body. Exported so the page's JSON-LD can state *exactly* the string
+ * that {@link getDocMetadata} puts in `<meta name="description">`; two surfaces
+ * describing the same page differently is a worse signal than either alone.
+ */
+export function resolveDocDescription(doc: ResolvedDoc, library: string): string {
+  const lib = getLibraryConfig(library);
+  return getDocDescription(doc.content, lib?.description ?? 'Threadplane documentation');
+}
+
 export function getDocMetadata(
   library: string,
   section: string,
@@ -87,7 +101,7 @@ export function getDocMetadata(
   const lib = getLibraryConfig(library);
   const libraryTitle = lib?.title ?? 'Docs';
   const title = `${doc.title} — ${libraryTitle} Docs — Threadplane`;
-  const description = getDocDescription(doc.content, lib?.description ?? 'Threadplane documentation');
+  const description = resolveDocDescription(doc, library);
   const pathname = `/docs/${library}/${section}/${slug}`;
 
   return createPageMetadata({ title, description, pathname });
diff --git a/apps/website/src/lib/sitemap-dates.spec.ts b/apps/website/src/lib/sitemap-dates.spec.ts
index bdc7f2eb2..d8d504828 100644
--- a/apps/website/src/lib/sitemap-dates.spec.ts
+++ b/apps/website/src/lib/sitemap-dates.spec.ts
@@ -1,6 +1,7 @@
 import { describe, expect, it } from 'vitest';
 import sitemap from '../app/sitemap';
-import { getSitemapEntries, hasGitHistory, parseGitLog } from './sitemap-dates';
+import { getAllPosts } from './blog';
+import { getPostLastModified, getSitemapEntries, hasGitHistory, parseGitLog } from './sitemap-dates';
 
 const SHA_A = 'a'.repeat(40);
 const SHA_B = 'b'.repeat(40);
@@ -137,3 +138,22 @@ describe('sitemap route', () => {
     }
   });
 });
+
+describe('getPostLastModified', () => {
+  // The point of the helper: the blog page's JSON-LD `dateModified`, its
+  // `article:modified_time`, and the sitemap's `<lastmod>` are three published
+  // claims about one fact. They agree only if all three ask the same question,
+  // so this pins the single-post shortcut against the full sitemap index.
+  it('agrees with the sitemap entry for the same route', () => {
+    const posts = getAllPosts();
+    expect(posts.length).toBeGreaterThan(0);
+
+    const entries = new Map(getSitemapEntries().map((entry) => [entry.route, entry.lastModified]));
+    for (const post of posts) {
+      expect([post.slug, getPostLastModified(post)?.toISOString()]).toEqual([
+        post.slug,
+        entries.get(`/blog/${post.slug}`)?.toISOString(),
+      ]);
+    }
+  });
+});
diff --git a/apps/website/src/lib/sitemap-dates.ts b/apps/website/src/lib/sitemap-dates.ts
index 9b4fd502b..84eb3e196 100644
--- a/apps/website/src/lib/sitemap-dates.ts
+++ b/apps/website/src/lib/sitemap-dates.ts
@@ -251,6 +251,21 @@ export function getRouteLastModified(route: string, postsByRoute: ReadonlyMap<st
   return committed && published ? (committed > published ? committed : published) : (committed ?? published);
 }
 
+/**
+ * Honest last-modified time for one already-resolved post.
+ *
+ * Both `generateMetadata` (for `article:modified_time`) and the page body (for
+ * the BlogPosting `dateModified`) need this, and they run as separate functions
+ * over the same request. Deriving it here — rather than each rebuilding the
+ * single-entry map — is what keeps the two surfaces from ever disagreeing about
+ * the same fact, and keeps both aligned with the sitemap's `<lastmod>`, which
+ * asks {@link getRouteLastModified} the same question via the full post index.
+ */
+export function getPostLastModified(post: Post): Date | undefined {
+  const route = `/blog/${post.slug}`;
+  return getRouteLastModified(route, new Map([[route, post]]));
+}
+
 export function getSitemapEntries(): SitemapEntry[] {
   // Drafts are not in `getSitemapRoutes()`, so they are not indexed either.
   const postsByRoute = getPostsByRoute();

From 651842f0307b90897bbcd4d7a90f06dfeb7c1426 Mon Sep 17 00:00:00 2001
From: Brian Love <brian@liveloveapp.com>
Date: Thu, 20 Aug 2026 13:29:50 -0700
Subject: [PATCH 19/35] test(website): pin breadcrumb and description
 invariants at their real surfaces
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

The docs-description test was a tautology: this branch made `getDocMetadata`
call `resolveDocDescription`, so both sides of the comparison had become the
same function and 116 double MDX reads asserted nothing. Replaced with a spec
that renders the docs route component and compares the JSON-LD it actually
emits against the route's own `generateMetadata` — the surface where divergence
can really occur.

`libraryIntroPath()` now lives in docs-config and is called by both the visible
<DocsBreadcrumb> and the page's BreadcrumbList, so the "markup mirrors the
visible trail" claim is structural instead of commented. The new spec asserts
the JSON-LD library rung equals the href the rendered component produces, and
that every non-final rung is a route the sitemap knows.

Also: the sitemap-agreement test no longer passes on two undefineds; the
"unmodified" fallback rule collapses into one `resolveModifiedTime()` shared by
og and JSON-LD; the docs fallback description and the docs last-modified
derivation each get one home; and both page mounts hoist their builder calls
above the return.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
---
 apps/website/src/app/blog/[slug]/page.tsx     |  40 +++---
 .../docs/[library]/[section]/[slug]/page.tsx  |  70 +++++-----
 .../app/docs/docs-structured-data.spec.tsx    | 124 ++++++++++++++++++
 .../src/components/docs/DocsBreadcrumb.tsx    |   4 +-
 apps/website/src/lib/docs-config.ts           |  13 ++
 apps/website/src/lib/docs.spec.ts             |  43 ++----
 apps/website/src/lib/docs.ts                  |   5 +-
 apps/website/src/lib/site-metadata.ts         |  16 ++-
 apps/website/src/lib/sitemap-dates.spec.ts    |   8 +-
 apps/website/src/lib/sitemap-dates.ts         |  13 ++
 apps/website/src/lib/structured-data.ts       |   6 +-
 11 files changed, 243 insertions(+), 99 deletions(-)
 create mode 100644 apps/website/src/app/docs/docs-structured-data.spec.tsx

diff --git a/apps/website/src/app/blog/[slug]/page.tsx b/apps/website/src/app/blog/[slug]/page.tsx
index 2078ddbf0..c365bd0c0 100644
--- a/apps/website/src/app/blog/[slug]/page.tsx
+++ b/apps/website/src/app/blog/[slug]/page.tsx
@@ -67,29 +67,31 @@ export default async function BlogPostPage({ params }: Params) {
   // Same derivation `generateMetadata` uses for `article:modified_time`, and the
   // same one the sitemap uses for `<lastmod>`, so all three agree.
   const lastModified = getPostLastModified(post);
+  // Undefined for an unparseable frontmatter date; the BlogPosting is dropped
+  // rather than published without a `datePublished`, matching the metadata.
   const published = publishedDate(post);
 
+  const postData = published
+    ? blogPostingJsonLd({
+        title: post.frontmatter.title,
+        description: post.frontmatter.description,
+        slug: post.slug,
+        datePublished: published.toISOString(),
+        dateModified: lastModified?.toISOString(),
+        authorName: author.name,
+        tags: post.frontmatter.tags,
+      })
+    : null;
+
+  const breadcrumbs = breadcrumbJsonLd([
+    { name: 'Blog', pathname: '/blog' },
+    { name: post.frontmatter.title, pathname: `/blog/${post.slug}` },
+  ]);
+
   return (
     <div style={{ paddingTop: 80, background: tokens.surfaces.canvas, minHeight: '100vh' }}>
-      {published ? (
-        <JsonLd
-          data={blogPostingJsonLd({
-            title: post.frontmatter.title,
-            description: post.frontmatter.description,
-            slug: post.slug,
-            datePublished: published.toISOString(),
-            dateModified: lastModified?.toISOString(),
-            authorName: author.name,
-            tags: post.frontmatter.tags,
-          })}
-        />
-      ) : null}
-      <JsonLd
-        data={breadcrumbJsonLd([
-          { name: 'Blog', pathname: '/blog' },
-          { name: post.frontmatter.title, pathname: `/blog/${post.slug}` },
-        ])}
-      />
+      {postData ? <JsonLd data={postData} /> : null}
+      <JsonLd data={breadcrumbs} />
       <div
         style={{
           display: 'flex',
diff --git a/apps/website/src/app/docs/[library]/[section]/[slug]/page.tsx b/apps/website/src/app/docs/[library]/[section]/[slug]/page.tsx
index 4d1de379f..fc591265f 100644
--- a/apps/website/src/app/docs/[library]/[section]/[slug]/page.tsx
+++ b/apps/website/src/app/docs/[library]/[section]/[slug]/page.tsx
@@ -8,14 +8,20 @@ import { DocsBreadcrumb } from '../../../../../components/docs/DocsBreadcrumb';
 import { DocsPageHeader } from '../../../../../components/docs/DocsPageHeader';
 import { PageActions } from '../../../../../components/docs/PageActions';
 import { DocsPrevNext } from '../../../../../components/docs/DocsPrevNext';
-import { getDocBySlug, getAllDocSlugs, getDocMetadata, resolveDocDescription } from '../../../../../lib/docs';
+import {
+  DEFAULT_DOCS_DESCRIPTION,
+  getAllDocSlugs,
+  getDocBySlug,
+  getDocMetadata,
+  resolveDocDescription,
+} from '../../../../../lib/docs';
 import { JsonLd } from '../../../../../components/shared/JsonLd';
 import { breadcrumbJsonLd, techArticleJsonLd } from '../../../../../lib/structured-data';
-import { getRouteLastModified } from '../../../../../lib/sitemap-dates';
+import { getDocLastModified } from '../../../../../lib/sitemap-dates';
 import { ApiDocRenderer, type ApiDocEntry } from '../../../../../components/docs/ApiDocRenderer';
 import { DocsTOC } from '../../../../../components/docs/DocsTOC';
 import { extractHeadings } from '../../../../../lib/extract-headings';
-import { findDocsPage, getLibraryConfig, type LibraryId } from '../../../../../lib/docs-config';
+import { findDocsPage, getLibraryConfig, libraryIntroPath, type LibraryId } from '../../../../../lib/docs-config';
 import fs from 'fs';
 import path from 'path';
 
@@ -42,7 +48,7 @@ export async function generateMetadata({ params }: DocsRouteProps): Promise<Meta
   const { library, section, slug } = await params;
   return getDocMetadata(library, section, slug) ?? {
     title: 'Docs — Threadplane',
-    description: 'Threadplane documentation',
+    description: DEFAULT_DOCS_DESCRIPTION,
   };
 }
 
@@ -56,44 +62,36 @@ export default async function DocsPage({ params }: DocsRouteProps) {
   if (!doc) notFound();
 
   const pathname = `/docs/${library}/${section}/${slug}`;
-  // The empty post index is the honest one here: `getRouteLastModified` consults
-  // it only to recognise a blog route, and no /docs route is ever a post, so
-  // passing an index costs a blog-directory read and changes nothing. The
-  // sitemap resolves this same route through the same file-source path, so the
-  // two `dateModified` claims agree.
-  const lastModified = getRouteLastModified(pathname, new Map());
+
+  const articleData = techArticleJsonLd({
+    title: doc.title,
+    // Exactly the string `generateMetadata` puts in the meta description.
+    description: resolveDocDescription(doc, library),
+    pathname,
+    dateModified: getDocLastModified(pathname)?.toISOString(),
+  });
+
+  // Mirrors the visible <DocsBreadcrumb>, which links the library rung through
+  // the same `libraryIntroPath()` — there is no /docs/<library> route, so a
+  // crumb pointing there would 404.
+  //
+  // The section rung the visible trail shows between library and page is
+  // deliberately absent: it is plain text there because no section index route
+  // exists, and a non-final BreadcrumbList item with no `item` URL is invalid.
+  // Omitting it is closer to the visible trail than inventing a URL for it.
+  const breadcrumbs = breadcrumbJsonLd([
+    { name: 'Docs', pathname: '/docs' },
+    { name: libConfig.title, pathname: libraryIntroPath(library) },
+    { name: doc.title, pathname },
+  ]);
 
   return (
     <div
       className="flex min-h-screen overflow-x-hidden"
       style={{ background: tokens.surfaces.canvas, paddingTop: 80 }}
     >
-      <JsonLd
-        data={techArticleJsonLd({
-          title: doc.title,
-          // Exactly the string `generateMetadata` puts in the meta description.
-          description: resolveDocDescription(doc, library),
-          pathname,
-          dateModified: lastModified?.toISOString(),
-        })}
-      />
-      <JsonLd
-        data={breadcrumbJsonLd([
-          { name: 'Docs', pathname: '/docs' },
-          // Mirrors the visible <DocsBreadcrumb>, which links the library at its
-          // introduction page: there is no /docs/<library> route (no page.tsx
-          // under src/app/docs/[library], and it is absent from the sitemap), so
-          // the plan's `/docs/${library}` would point a crumb at a 404.
-          //
-          // The section rung the visible trail shows between library and page is
-          // deliberately absent: it is plain text there because no section index
-          // route exists, and a non-final BreadcrumbList item with no `item` URL
-          // is invalid. Omitting it is closer to the visible trail than inventing
-          // a URL for it.
-          { name: libConfig.title, pathname: `/docs/${library}/getting-started/introduction` },
-          { name: doc.title, pathname },
-        ])}
-      />
+      <JsonLd data={articleData} />
+      <JsonLd data={breadcrumbs} />
       <DocsSearch library={library as LibraryId} />
       <DocsSidebar activeLibrary={library as LibraryId} activeSection={section} activeSlug={slug} />
       <div
diff --git a/apps/website/src/app/docs/docs-structured-data.spec.tsx b/apps/website/src/app/docs/docs-structured-data.spec.tsx
new file mode 100644
index 000000000..f84bfdbb3
--- /dev/null
+++ b/apps/website/src/app/docs/docs-structured-data.spec.tsx
@@ -0,0 +1,124 @@
+import { describe, expect, it } from 'vitest';
+import { isValidElement, type ReactNode } from 'react';
+import { render, screen } from '@testing-library/react';
+import DocsPage, { generateMetadata } from './[library]/[section]/[slug]/page';
+import { DocsBreadcrumb } from '../../components/docs/DocsBreadcrumb';
+import { docsConfig, type LibraryId } from '../../lib/docs-config';
+import { getDocBySlug } from '../../lib/docs';
+import { getSitemapRoutes } from '../../lib/site-metadata';
+
+interface Slug {
+  library: string;
+  section: string;
+  slug: string;
+}
+
+/**
+ * A spread of shapes rather than every page: one per description source
+ * (frontmatter, first-paragraph fallback), an API page, and a page that is
+ * itself the library's breadcrumb target.
+ */
+const SAMPLES: Slug[] = [
+  { library: 'langgraph', section: 'guides', slug: 'streaming' },
+  { library: 'langgraph', section: 'getting-started', slug: 'introduction' },
+  { library: 'langgraph', section: 'api', slug: 'inject-agent' },
+  { library: 'chat', section: 'getting-started', slug: 'introduction' },
+  { library: 'a2ui', section: 'getting-started', slug: 'introduction' },
+];
+
+/** Every `data` payload the page hands to a `<JsonLd>`, in render order. */
+async function renderedJsonLd({ library, section, slug }: Slug): Promise<Record<string, unknown>[]> {
+  const tree = await DocsPage({ params: Promise.resolve({ library, section, slug }) });
+  const found: Record<string, unknown>[] = [];
+
+  const walk = (node: ReactNode): void => {
+    if (Array.isArray(node)) return node.forEach(walk);
+    if (!isValidElement(node)) return;
+    const props = node.props as { data?: Record<string, unknown>; children?: ReactNode };
+    // Matched by name because `JsonLd` is a plain function component; importing
+    // it for identity would still work, but the name keeps the failure legible.
+    if (typeof node.type === 'function' && (node.type as { name?: string }).name === 'JsonLd' && props.data) {
+      found.push(props.data);
+    }
+    walk(props.children);
+  };
+
+  walk(tree);
+  return found;
+}
+
+function nodeOfType(nodes: Record<string, unknown>[], type: string): Record<string, unknown> | undefined {
+  return nodes.find((node) => node['@type'] === type);
+}
+
+describe('docs page structured data', () => {
+  // The tautology this replaces compared `resolveDocDescription` against
+  // `getDocMetadata`, which calls it — both sides were the same function. The
+  // real risk is the *page* describing itself differently from its own
+  // `generateMetadata`, so the assertion runs over both actual surfaces.
+  it('describes itself with the same string its metadata publishes', async () => {
+    for (const sample of SAMPLES) {
+      const [article, metadata] = await Promise.all([
+        renderedJsonLd(sample).then((nodes) => nodeOfType(nodes, 'TechArticle')),
+        generateMetadata({ params: Promise.resolve(sample) }),
+      ]);
+
+      const label = `${sample.library}/${sample.section}/${sample.slug}`;
+      expect([label, typeof metadata.description]).toEqual([label, 'string']);
+      expect([label, article?.description]).toEqual([label, metadata.description]);
+    }
+  });
+
+  it('emits exactly a TechArticle and a BreadcrumbList', async () => {
+    const nodes = await renderedJsonLd(SAMPLES[0]);
+    expect(nodes.map((node) => node['@type'])).toEqual(['TechArticle', 'BreadcrumbList']);
+  });
+
+  // Google expects the breadcrumb markup to correspond to the visible trail, so
+  // the JSON-LD is checked against what <DocsBreadcrumb> actually renders rather
+  // than against a second copy of the same string.
+  it('links the same library URL the visible breadcrumb links', async () => {
+    for (const sample of SAMPLES) {
+      const doc = getDocBySlug(sample.library, sample.section, sample.slug);
+      const nodes = await renderedJsonLd(sample);
+      const crumbs = nodeOfType(nodes, 'BreadcrumbList')?.itemListElement as
+        | { name: string; item: string }[]
+        | undefined;
+
+      const { unmount } = render(
+        <DocsBreadcrumb
+          library={sample.library as LibraryId}
+          section={sample.section}
+          slug={sample.slug}
+          title={doc?.title ?? ''}
+        />,
+      );
+      const libraryTitle = docsConfig.find((lib) => lib.id === sample.library)?.title ?? '';
+      const visibleHref = screen.getByRole('link', { name: libraryTitle }).getAttribute('href');
+      unmount();
+
+      const label = `${sample.library}/${sample.section}/${sample.slug}`;
+      expect([label, crumbs?.find((crumb) => crumb.name === libraryTitle)?.item]).toEqual([
+        label,
+        `https://threadplane.ai${visibleHref}`,
+      ]);
+    }
+  });
+
+  // A non-final BreadcrumbList item pointing at a 404 is a defect, and the
+  // plan's original `/docs/<library>` was exactly that. Rendering the page is
+  // what gives this teeth: reverting the URL in page.tsx fails here.
+  it('points every non-final breadcrumb rung at a route that exists', async () => {
+    const routes = new Set(getSitemapRoutes().map((route) => `https://threadplane.ai${route === '/' ? '/' : route}`));
+
+    for (const sample of SAMPLES) {
+      const nodes = await renderedJsonLd(sample);
+      const crumbs = nodeOfType(nodes, 'BreadcrumbList')?.itemListElement as { item: string }[];
+      const missing = crumbs.slice(0, -1).map((crumb) => crumb.item).filter((item) => !routes.has(item));
+      expect([`${sample.library}/${sample.section}/${sample.slug}`, missing]).toEqual([
+        `${sample.library}/${sample.section}/${sample.slug}`,
+        [],
+      ]);
+    }
+  });
+});
diff --git a/apps/website/src/components/docs/DocsBreadcrumb.tsx b/apps/website/src/components/docs/DocsBreadcrumb.tsx
index b27bd3c0f..1f7e08ee0 100644
--- a/apps/website/src/components/docs/DocsBreadcrumb.tsx
+++ b/apps/website/src/components/docs/DocsBreadcrumb.tsx
@@ -1,6 +1,6 @@
 import Link from 'next/link';
 import { tokens } from '@threadplane/design-tokens';
-import { getLibraryConfig, type LibraryId } from '../../lib/docs-config';
+import { getLibraryConfig, libraryIntroPath, type LibraryId } from '../../lib/docs-config';
 
 interface Props {
   library: LibraryId;
@@ -38,7 +38,7 @@ export function DocsBreadcrumb({ library, section, slug: _slug, title }: Props)
           <span style={sep} aria-hidden="true">/</span>
         </li>
         <li>
-          <Link href={`/docs/${library}/getting-started/introduction`} style={crumb}>{libraryTitle}</Link>
+          <Link href={libraryIntroPath(library)} style={crumb}>{libraryTitle}</Link>
           <span style={sep} aria-hidden="true">/</span>
         </li>
         <li style={crumb}>
diff --git a/apps/website/src/lib/docs-config.ts b/apps/website/src/lib/docs-config.ts
index 988784fe5..919bc560b 100644
--- a/apps/website/src/lib/docs-config.ts
+++ b/apps/website/src/lib/docs-config.ts
@@ -466,6 +466,19 @@ export function getLibraryConfig(libraryId: string): DocsLibrary | undefined {
   return docsConfig.find((l) => l.id === libraryId);
 }
 
+/**
+ * Where a library's breadcrumb rung points.
+ *
+ * There is no `/docs/<library>` index route, so the rung links the library's
+ * introduction page instead. Both the visible {@link DocsBreadcrumb} and the
+ * BreadcrumbList structured data on the same page call this, because Google
+ * expects the markup to match what the user sees — deriving both from one
+ * function is what makes that true by construction rather than by comment.
+ */
+export function libraryIntroPath(library: string): string {
+  return `/docs/${library}/getting-started/introduction`;
+}
+
 export function getLibraryPages(libraryId: string): DocsPage[] {
   const lib = getLibraryConfig(libraryId);
   if (!lib) return [];
diff --git a/apps/website/src/lib/docs.spec.ts b/apps/website/src/lib/docs.spec.ts
index 4582699f7..279294a14 100644
--- a/apps/website/src/lib/docs.spec.ts
+++ b/apps/website/src/lib/docs.spec.ts
@@ -2,8 +2,8 @@ import { describe, expect, it } from 'vitest';
 import fs from 'fs';
 import path from 'path';
 import { fileURLToPath } from 'url';
-import { getAllDocSlugs, getDocBySlug, getDocMetadata, resolveDocDescription } from './docs';
-import { allDocsPages, docsConfig, findDocsPage, specialDocsPages } from './docs-config';
+import { getAllDocSlugs, getDocBySlug, getDocMetadata } from './docs';
+import { allDocsPages, docsConfig, findDocsPage, libraryIntroPath, specialDocsPages } from './docs-config';
 import { getCanonicalUrl, getSitemapRoutes } from './site-metadata';
 
 const internalDocsLinkPattern = /(?:href=["']|\]\()(?<href>\/docs\/[^"')#\s]+)/g;
@@ -260,40 +260,17 @@ describe('website docs bindings', () => {
   });
 });
 
-describe('docs structured-data inputs', () => {
-  // The docs page builds its TechArticle description from this accessor while
-  // `generateMetadata` builds the meta description from `getDocMetadata`. If
-  // they ever diverge the page tells crawlers two different things about itself.
-  it('resolves the same description the page metadata publishes', () => {
-    const mismatched: string[] = [];
-
-    for (const { library, section, slug } of getAllDocSlugs()) {
-      const doc = getDocBySlug(library, section, slug);
-      if (!doc) continue;
-      const description = resolveDocDescription(doc, library);
-      // Guards the comparison below from passing on two undefineds.
-      expect(typeof description === 'string' && description.length > 0).toBe(true);
-      if (description !== getDocMetadata(library, section, slug)?.description) {
-        mismatched.push(`${library}/${section}/${slug}`);
-      }
-    }
-
-    expect(mismatched).toEqual([]);
-  });
-
-  // The docs BreadcrumbList links its library rung at that library's
-  // introduction page, mirroring the visible <DocsBreadcrumb>. There is no
-  // `/docs/<library>` index route, so a crumb pointing there would 404 — this
-  // pins both halves of that: the intro page exists, and the bare library path
-  // does not.
-  it('links every library breadcrumb rung at a route that exists', () => {
+describe('docs breadcrumb routes', () => {
+  // The docs BreadcrumbList and the visible <DocsBreadcrumb> both link the
+  // library rung through `libraryIntroPath()`. This pins the property that path
+  // has to satisfy: it must be a real route, and the bare `/docs/<library>` it
+  // stands in for must remain absent (there is no index route for it, so a crumb
+  // pointing there would 404).
+  it('resolves the library intro path to a real route for every library', () => {
     const routes = new Set(getSitemapRoutes());
 
     for (const library of docsConfig) {
-      expect([library.id, routes.has(`/docs/${library.id}/getting-started/introduction`)]).toEqual([
-        library.id,
-        true,
-      ]);
+      expect([library.id, routes.has(libraryIntroPath(library.id))]).toEqual([library.id, true]);
       expect([library.id, routes.has(`/docs/${library.id}`)]).toEqual([library.id, false]);
     }
   });
diff --git a/apps/website/src/lib/docs.ts b/apps/website/src/lib/docs.ts
index 000ed415d..f553b5cce 100644
--- a/apps/website/src/lib/docs.ts
+++ b/apps/website/src/lib/docs.ts
@@ -10,6 +10,9 @@ const resolveContentDir = (library: string): string => {
   return path.join(process.cwd(), 'content', 'docs', library);
 };
 
+/** Fallback description for a docs page whose library declares none. */
+export const DEFAULT_DOCS_DESCRIPTION = 'Threadplane documentation';
+
 export interface ResolvedDoc {
   page: DocsPage;
   content: string;
@@ -87,7 +90,7 @@ export function getDocBySlug(library: string, section: string, slug: string): Re
  */
 export function resolveDocDescription(doc: ResolvedDoc, library: string): string {
   const lib = getLibraryConfig(library);
-  return getDocDescription(doc.content, lib?.description ?? 'Threadplane documentation');
+  return getDocDescription(doc.content, lib?.description ?? DEFAULT_DOCS_DESCRIPTION);
 }
 
 export function getDocMetadata(
diff --git a/apps/website/src/lib/site-metadata.ts b/apps/website/src/lib/site-metadata.ts
index 28e7809cd..f2bf02c8c 100644
--- a/apps/website/src/lib/site-metadata.ts
+++ b/apps/website/src/lib/site-metadata.ts
@@ -38,6 +38,18 @@ export interface ArticleMetadata {
   tags?: string[];
 }
 
+/**
+ * The "unmodified" rule, in one place: a page with no known modification
+ * advertises its publish date as the modification date.
+ *
+ * Shared by `article:modified_time` here and by the BlogPosting `dateModified`
+ * in `structured-data.ts`. Those are two published claims about one fact, so
+ * they resolve it with one implementation rather than two that happen to agree.
+ */
+export function resolveModifiedTime(publishedTime: string, modifiedTime?: string): string {
+  return modifiedTime ?? publishedTime;
+}
+
 /** Options for {@link createPageMetadata}. */
 export interface PageMetadataOptions {
   title: string;
@@ -75,9 +87,7 @@ export function createPageMetadata({
       images: [image],
       ...(article && {
         publishedTime: article.publishedTime,
-        // The single place the "unmodified" rule lives: an article with no
-        // known modification advertises its publish date as the modification.
-        modifiedTime: article.modifiedTime ?? article.publishedTime,
+        modifiedTime: resolveModifiedTime(article.publishedTime, article.modifiedTime),
         authors: article.authors,
         tags: article.tags,
       }),
diff --git a/apps/website/src/lib/sitemap-dates.spec.ts b/apps/website/src/lib/sitemap-dates.spec.ts
index d8d504828..72e1b8e3c 100644
--- a/apps/website/src/lib/sitemap-dates.spec.ts
+++ b/apps/website/src/lib/sitemap-dates.spec.ts
@@ -150,9 +150,15 @@ describe('getPostLastModified', () => {
 
     const entries = new Map(getSitemapEntries().map((entry) => [entry.route, entry.lastModified]));
     for (const post of posts) {
+      const route = `/blog/${post.slug}`;
+      // Without these, an absent route and an undateable post both read as
+      // `undefined` and the comparison below passes on nothing.
+      expect([route, entries.has(route)]).toEqual([route, true]);
+      expect([route, entries.get(route) instanceof Date]).toEqual([route, true]);
+
       expect([post.slug, getPostLastModified(post)?.toISOString()]).toEqual([
         post.slug,
-        entries.get(`/blog/${post.slug}`)?.toISOString(),
+        entries.get(route)?.toISOString(),
       ]);
     }
   });
diff --git a/apps/website/src/lib/sitemap-dates.ts b/apps/website/src/lib/sitemap-dates.ts
index 84eb3e196..b11ab8799 100644
--- a/apps/website/src/lib/sitemap-dates.ts
+++ b/apps/website/src/lib/sitemap-dates.ts
@@ -266,6 +266,19 @@ export function getPostLastModified(post: Post): Date | undefined {
   return getRouteLastModified(route, new Map([[route, post]]));
 }
 
+/**
+ * Honest last-modified time for a docs route.
+ *
+ * The empty post index is the honest argument: {@link getRouteLastModified}
+ * consults it only to recognise a blog route, and no /docs route is ever a post,
+ * so supplying a real index would cost a blog-directory read and change nothing.
+ * The route then dates itself from its MDX source — the same path the sitemap
+ * takes for the same route, so the two `lastmod`/`dateModified` claims agree.
+ */
+export function getDocLastModified(pathname: string): Date | undefined {
+  return getRouteLastModified(pathname, new Map());
+}
+
 export function getSitemapEntries(): SitemapEntry[] {
   // Drafts are not in `getSitemapRoutes()`, so they are not indexed either.
   const postsByRoute = getPostsByRoute();
diff --git a/apps/website/src/lib/structured-data.ts b/apps/website/src/lib/structured-data.ts
index 601eb8489..6dbdd3254 100644
--- a/apps/website/src/lib/structured-data.ts
+++ b/apps/website/src/lib/structured-data.ts
@@ -1,5 +1,5 @@
 // SPDX-License-Identifier: MIT
-import { DEFAULT_SOCIAL_IMAGE, getCanonicalUrl, SITE_NAME } from './site-metadata';
+import { DEFAULT_SOCIAL_IMAGE, getCanonicalUrl, resolveModifiedTime, SITE_NAME } from './site-metadata';
 import { SHORT_POSITIONING_DESCRIPTION } from './positioning';
 
 /** A single schema.org node, ready to be serialized into a `ld+json` script. */
@@ -122,9 +122,7 @@ export function blogPostingJsonLd(post: BlogPostingInput) {
     url,
     mainEntityOfPage: url,
     datePublished: post.datePublished,
-    // Same "unmodified" rule the OpenGraph metadata uses: a post with no known
-    // modification advertises its publish date.
-    dateModified: post.dateModified ?? post.datePublished,
+    dateModified: resolveModifiedTime(post.datePublished, post.dateModified),
     // TODO(task 9): switch to `<pathname>/opengraph-image` once that route
     // actually serves. It exists but currently 500s in production, and naming
     // it here would advertise a broken image — same call task 6 made for

From b793d8d370acd205b982b1c8820354a6bef3fb4d Mon Sep 17 00:00:00 2001
From: Brian Love <brian@liveloveapp.com>
Date: Thu, 20 Aug 2026 14:24:12 -0700
Subject: [PATCH 20/35] fix(website): stop the per-post OpenGraph image route
 500ing
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Every blog post's social card returned HTTP 500 in production. Satori
rejects a div with more than one child node unless it carries an explicit
`display`, and the byline rendered three children (author, separator,
date) with none. The root `/opengraph-image` route was unaffected only
because it is prerendered at build time, while `/blog/[slug]/opengraph-image`
is server-rendered on demand.

Separately, the route read the bundled Garamond TTF through a parent
traversal (`join(here, '../../EBGaramond-Bold.ttf')`) that Next's file
tracer cannot statically resolve, so the font was absent from the
deployed function's trace — confirmed by diffing the two routes'
`route.js.nft.json`. Move font loading into `src/app/og-font.ts`,
colocated with the TTF, so the sibling-filename form traces for every
caller. Both routes now share it.

Make the failure mode safe: `satoriFonts` returns `undefined` rather than
`[]` when every font fails, since Satori throws on an empty list but
falls back to its bundled Noto Sans when the option is omitted. A plain
card beats a 500.

With the route verified locally, point `og:image`/`twitter:image` and the
BlogPosting `image` at the per-post card, flipping the two TODOs that
deliberately waited on this fix.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
---
 .../src/app/blog/[slug]/opengraph-image.tsx   | 50 +++--------
 apps/website/src/app/blog/[slug]/page.tsx     |  3 +-
 apps/website/src/app/og-font.spec.ts          | 27 ++++++
 apps/website/src/app/og-font.ts               | 86 +++++++++++++++++++
 apps/website/src/app/opengraph-image.tsx      | 57 ++----------
 apps/website/src/lib/structured-data.spec.ts  |  8 +-
 apps/website/src/lib/structured-data.ts       | 12 ++-
 7 files changed, 146 insertions(+), 97 deletions(-)
 create mode 100644 apps/website/src/app/og-font.spec.ts
 create mode 100644 apps/website/src/app/og-font.ts

diff --git a/apps/website/src/app/blog/[slug]/opengraph-image.tsx b/apps/website/src/app/blog/[slug]/opengraph-image.tsx
index cf9f4a28d..fa4dd3b1a 100644
--- a/apps/website/src/app/blog/[slug]/opengraph-image.tsx
+++ b/apps/website/src/app/blog/[slug]/opengraph-image.tsx
@@ -1,6 +1,7 @@
 import { ImageResponse } from 'next/og';
 import { getPostBySlug } from '../../../lib/blog';
 import { getAuthor } from '../../../lib/blog-authors';
+import { loadGoogleFont, loadLocalGaramond, satoriFonts } from '../../og-font';
 
 export const runtime = 'nodejs';
 export const alt = 'Threadplane blog post';
@@ -11,42 +12,12 @@ 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) {
+    // No `fonts` option at all: next/og falls back to its bundled Noto Sans.
     return new ImageResponse(
       (
         <div
@@ -70,14 +41,14 @@ export default async function og({ params }: Params) {
 
   const [garamondBold, interRegular, interBold] = await Promise.all([
     loadLocalGaramond(),
-    loadFont('Inter', 400),
-    loadFont('Inter', 600),
+    loadGoogleFont('Inter', 400),
+    loadGoogleFont('Inter', 600),
   ]);
-  const fonts = [
+  const fonts = satoriFonts([
     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(
@@ -97,6 +68,7 @@ export default async function og({ params }: Params) {
       >
         <div
           style={{
+            display: 'flex',
             fontSize: 24,
             textTransform: 'uppercase',
             letterSpacing: '0.12em',
@@ -107,6 +79,7 @@ export default async function og({ params }: Params) {
         </div>
         <div
           style={{
+            display: 'flex',
             fontFamily: 'EB Garamond, Georgia, serif',
             fontSize: 64,
             fontWeight: 700,
@@ -117,7 +90,12 @@ export default async function og({ params }: Params) {
         >
           {post.frontmatter.title}
         </div>
-        <div style={{ fontSize: 24, opacity: 0.7 }}>
+        {/*
+          Satori requires an explicit `display` on any div with more than one
+          child node, and throws (→ HTTP 500) otherwise. This byline has three
+          (name, separator, date), so the `display: flex` is load-bearing.
+        */}
+        <div style={{ display: 'flex', fontSize: 24, opacity: 0.7 }}>
           {author.name} · {post.frontmatter.date}
         </div>
       </div>
diff --git a/apps/website/src/app/blog/[slug]/page.tsx b/apps/website/src/app/blog/[slug]/page.tsx
index c365bd0c0..57ec7ef9b 100644
--- a/apps/website/src/app/blog/[slug]/page.tsx
+++ b/apps/website/src/app/blog/[slug]/page.tsx
@@ -40,8 +40,7 @@ export async function generateMetadata({ params }: Params): Promise<Metadata> {
     description: post.frontmatter.description,
     pathname,
     type: 'article',
-    // TODO(task 9): set image to "<pathname>/opengraph-image" once that route
-    // exists; naming it before then would emit an og:image URL that 404s.
+    image: `${pathname}/opengraph-image`,
     article: published
       ? {
           publishedTime: published.toISOString(),
diff --git a/apps/website/src/app/og-font.spec.ts b/apps/website/src/app/og-font.spec.ts
new file mode 100644
index 000000000..d9c0b4621
--- /dev/null
+++ b/apps/website/src/app/og-font.spec.ts
@@ -0,0 +1,27 @@
+// SPDX-License-Identifier: MIT
+import { describe, expect, it } from 'vitest';
+import { satoriFonts, type OgFont } from './og-font';
+
+const FONT: OgFont = {
+  name: 'EB Garamond',
+  data: new ArrayBuffer(8),
+  weight: 700,
+  style: 'normal',
+};
+
+describe('satoriFonts', () => {
+  it('drops the fonts that failed to load', () => {
+    expect(satoriFonts([FONT, null, { ...FONT, name: 'Inter', weight: 400 }])).toEqual([
+      FONT,
+      { ...FONT, name: 'Inter', weight: 400 },
+    ]);
+  });
+
+  it('returns undefined rather than an empty list when every font fails', () => {
+    // Satori throws on `fonts: []`, which would 500 the whole route. Omitting
+    // the option lets next/og fall back to its bundled Noto Sans, so a card
+    // still renders when the TTF is missing and Google Fonts is unreachable.
+    expect(satoriFonts([])).toBeUndefined();
+    expect(satoriFonts([null, null])).toBeUndefined();
+  });
+});
diff --git a/apps/website/src/app/og-font.ts b/apps/website/src/app/og-font.ts
new file mode 100644
index 000000000..401e91289
--- /dev/null
+++ b/apps/website/src/app/og-font.ts
@@ -0,0 +1,86 @@
+// SPDX-License-Identifier: MIT
+/**
+ * Shared font loading for the `opengraph-image` routes.
+ *
+ * This module lives next to `EBGaramond-Bold.ttf` on purpose. Next's file
+ * tracer (`@vercel/nft`) statically evaluates `join(dirname(fileURLToPath(
+ * import.meta.url)), 'EBGaramond-Bold.ttf')` and adds the TTF to the traced
+ * bundle of every route that reaches this code. It does *not* resolve a
+ * parent-traversal form like `join(here, '../../EBGaramond-Bold.ttf')`, which
+ * is how `blog/[slug]/opengraph-image.tsx` used to read the font: locally the
+ * source tree is on disk so it worked, but the deployed serverless function
+ * never received the file. Keeping the read in one colocated module means the
+ * traversal never has to be written again.
+ *
+ * EB Garamond is bundled as a static-weight TTF rather than fetched because:
+ * 1. Google Fonts only serves Garamond as woff2 — Satori can't decode woff2.
+ * 2. The variable-weight TTF in Google's fonts repo trips Satori's TTF parser
+ *    ("Cannot read properties of undefined (reading '256')") on variable-font
+ *    tables (fvar/STAT/MVAR/HVAR).
+ *
+ * The committed TTF was produced by instancing the upstream variable font to
+ * wght=700 and stripping the now-unused variable tables — see
+ * apps/website/scripts/instance-garamond.py. The file is ~500KB, served only
+ * from this server-side render path (never downloaded by browsers).
+ */
+
+export interface OgFont {
+  name: string;
+  data: ArrayBuffer;
+  weight: 400 | 600 | 700;
+  style: 'normal';
+}
+
+/**
+ * Reads the bundled Garamond TTF. Returns null (never throws) if the file is
+ * missing so a card without the serif headline still renders.
+ */
+export 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');
+    const here = dirname(fileURLToPath(import.meta.url));
+    // Keep this a bare sibling filename — see the module comment above.
+    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('og-font: failed to load bundled Garamond TTF', err);
+    return null;
+  }
+}
+
+/**
+ * Best-effort Google Fonts fetch. Purely decorative: every caller must stay
+ * renderable when this returns null, because nothing guarantees the render
+ * environment can reach fonts.googleapis.com.
+ */
+export async function loadGoogleFont(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());
+    // Grab any url(...) src — the first one is the woff2 the modern UA gets.
+    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;
+  }
+}
+
+/**
+ * Drops the fonts that failed to load.
+ *
+ * Returns `undefined` — not `[]` — when nothing loaded. Satori throws on an
+ * empty font list (a 500 for the whole route); omitting the option entirely
+ * makes `next/og` fall back to its own bundled Noto Sans, so the card is ugly
+ * but still a valid PNG.
+ */
+export function satoriFonts(candidates: (OgFont | null)[]): OgFont[] | undefined {
+  const fonts = candidates.filter((f): f is OgFont => f !== null);
+  return fonts.length > 0 ? fonts : undefined;
+}
diff --git a/apps/website/src/app/opengraph-image.tsx b/apps/website/src/app/opengraph-image.tsx
index 07a3a2f2e..8f176d244 100644
--- a/apps/website/src/app/opengraph-image.tsx
+++ b/apps/website/src/app/opengraph-image.tsx
@@ -7,71 +7,28 @@
  */
 import { ImageResponse } from 'next/og';
 import { POSITIONING_PROOF_POINTS, PRIMARY_TAGLINE, SHORT_POSITIONING_DESCRIPTION } from '../lib/positioning';
+import { loadGoogleFont, loadLocalGaramond, satoriFonts } from './og-font';
 
 // Node runtime (not edge) so we can read the bundled Garamond TTF off disk.
+// Font loading lives in ./og-font so the TTF stays statically traceable.
 export const runtime = 'nodejs';
 export const alt = PRIMARY_TAGLINE;
 export const size = { width: 1200, height: 630 };
 export const contentType = 'image/png';
 
-async function loadFont(family: string, weight: number): Promise<ArrayBuffer | null> {
-  try {
-    // Modern UA → woff2. Older UA → ttf. We ask for both and pick the first that resolves.
-    // ImageResponse wants the raw font binary; woff2 is fine (Satori decompresses internally).
-    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());
-    // Grab any url(...) src — the first one is the woff2 the modern UA gets.
-    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;
-  }
-}
-
-/**
- * EB Garamond is bundled as a static-weight TTF next to this file because:
- * 1. Google Fonts only serves Garamond as woff2 — Satori can't decode woff2.
- * 2. The variable-weight TTF in Google's fonts repo trips Satori's TTF parser
- *    ("Cannot read properties of undefined (reading '256')") on variable-font
- *    tables (fvar/STAT/MVAR/HVAR).
- *
- * The committed TTF was produced by instancing the upstream variable font to
- * wght=700 and stripping the now-unused variable tables — see
- * apps/website/scripts/instance-garamond.py. The file is ~500KB, served only
- * from this server-side render path (never downloaded by browsers).
- */
-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');
-    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('opengraph-image: failed to load local Garamond TTF', err);
-    return null;
-  }
-}
-
 export default async function OpenGraphImage() {
   const [garamondBold, interRegular, interBold, monoBold] = await Promise.all([
     loadLocalGaramond(),
-    loadFont('Inter', 400),
-    loadFont('Inter', 600),
-    loadFont('JetBrains+Mono', 700),
+    loadGoogleFont('Inter', 400),
+    loadGoogleFont('Inter', 600),
+    loadGoogleFont('JetBrains+Mono', 700),
   ]);
-  const fonts = [
+  const fonts = satoriFonts([
     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 },
     monoBold && { name: 'JetBrains Mono', data: monoBold, weight: 700 as const, style: 'normal' as const },
-  ].filter((f): f is NonNullable<typeof f> => f !== null);
+  ]);
 
   return new ImageResponse(
     (
diff --git a/apps/website/src/lib/structured-data.spec.ts b/apps/website/src/lib/structured-data.spec.ts
index f31d68e22..d965528b9 100644
--- a/apps/website/src/lib/structured-data.spec.ts
+++ b/apps/website/src/lib/structured-data.spec.ts
@@ -120,8 +120,12 @@ describe('blogPostingJsonLd', () => {
     expect(data['dateModified']).toBe('2026-08-19');
   });
 
-  it('emits an absolute image url', () => {
-    expect(String(blogPostingJsonLd(SAMPLE_POST)['image'])).toMatch(/^https:\/\/threadplane\.ai\//);
+  it('points image at the per-post opengraph-image route', () => {
+    // Must stay in lockstep with the `image` that `blog/[slug]/page.tsx` hands
+    // `createPageMetadata`, so og:image and the BlogPosting agree.
+    expect(blogPostingJsonLd(SAMPLE_POST)['image']).toBe(
+      'https://threadplane.ai/blog/a-post/opengraph-image',
+    );
   });
 
   it('omits keywords entirely for an untagged post', () => {
diff --git a/apps/website/src/lib/structured-data.ts b/apps/website/src/lib/structured-data.ts
index 6dbdd3254..f63e8064e 100644
--- a/apps/website/src/lib/structured-data.ts
+++ b/apps/website/src/lib/structured-data.ts
@@ -1,5 +1,5 @@
 // SPDX-License-Identifier: MIT
-import { DEFAULT_SOCIAL_IMAGE, getCanonicalUrl, resolveModifiedTime, SITE_NAME } from './site-metadata';
+import { getCanonicalUrl, resolveModifiedTime, SITE_NAME } from './site-metadata';
 import { SHORT_POSITIONING_DESCRIPTION } from './positioning';
 
 /** A single schema.org node, ready to be serialized into a `ld+json` script. */
@@ -113,7 +113,8 @@ export interface BlogPostingInput {
 }
 
 export function blogPostingJsonLd(post: BlogPostingInput) {
-  const url = getCanonicalUrl(`/blog/${post.slug}`);
+  const pathname = `/blog/${post.slug}`;
+  const url = getCanonicalUrl(pathname);
   return {
     '@context': SCHEMA_CONTEXT,
     '@type': 'BlogPosting',
@@ -123,11 +124,8 @@ export function blogPostingJsonLd(post: BlogPostingInput) {
     mainEntityOfPage: url,
     datePublished: post.datePublished,
     dateModified: resolveModifiedTime(post.datePublished, post.dateModified),
-    // TODO(task 9): switch to `<pathname>/opengraph-image` once that route
-    // actually serves. It exists but currently 500s in production, and naming
-    // it here would advertise a broken image — same call task 6 made for
-    // og:image, kept consistent on purpose.
-    image: getCanonicalUrl(DEFAULT_SOCIAL_IMAGE),
+    // Per-post card, matching the `og:image` that `generateMetadata` emits.
+    image: getCanonicalUrl(`${pathname}/opengraph-image`),
     // Omitted rather than left undefined, matching `dateModified` below.
     ...(post.tags?.length ? { keywords: post.tags } : {}),
     // No `url` on the author until /about exists (task 11); a 404 author URL is

From da7a09eafa2b44e37b603bb6544f616d02f042ce Mon Sep 17 00:00:00 2001
From: Brian Love <brian@liveloveapp.com>
Date: Thu, 20 Aug 2026 14:40:18 -0700
Subject: [PATCH 21/35] perf(website): prerender per-post og cards
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

The per-post card route was `ƒ` (server-rendered on demand), so Satori
markup errors could only surface as a production 500 — which is how the
missing `display: flex` on the byline shipped and broke all nine cards.
The root route escaped the same class of bug purely because it is
prerendered, where such an error fails the build instead.

Add `generateStaticParams`, mirroring this segment's `page.tsx`, so every
published post's card is generated at build time. The route now reports
as `●` and emits nine 1200x630 PNGs into the build output. This turns
render-time Satori failures into build failures, drops two uncached
Google Fonts round-trips and an MDX read per request on a path crawlers
hit, and moves `resolveWebsiteDir()` onto the build's cwd — which is
known to resolve — instead of an unverified serverless cwd.

Also:
- Extract `loadCardFonts` so both routes stop hand-assembling the same
  font descriptors, and widen `OgFont.weight` to the CSS weight domain
  so call sites no longer need `as const`.
- Add a shared `ogImagePath(slug)` used by both `blog/[slug]/page.tsx`
  and `blogPostingJsonLd`; the two built the same URL independently and
  could drift with both suites green.
- Drop the two defensive `display: flex` values on single-child divs and
  scope the comment to the byline, which is the one that was diagnosed.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
---
 .../src/app/blog/[slug]/opengraph-image.tsx   | 41 +++++++++++--------
 apps/website/src/app/blog/[slug]/page.tsx     |  4 +-
 apps/website/src/app/og-font.ts               | 28 ++++++++++++-
 apps/website/src/app/opengraph-image.tsx      | 15 +------
 apps/website/src/lib/site-metadata.ts         | 12 ++++++
 apps/website/src/lib/structured-data.spec.ts  |  4 +-
 apps/website/src/lib/structured-data.ts       |  7 ++--
 7 files changed, 72 insertions(+), 39 deletions(-)

diff --git a/apps/website/src/app/blog/[slug]/opengraph-image.tsx b/apps/website/src/app/blog/[slug]/opengraph-image.tsx
index fa4dd3b1a..c87daff93 100644
--- a/apps/website/src/app/blog/[slug]/opengraph-image.tsx
+++ b/apps/website/src/app/blog/[slug]/opengraph-image.tsx
@@ -1,7 +1,7 @@
 import { ImageResponse } from 'next/og';
-import { getPostBySlug } from '../../../lib/blog';
+import { getAllPosts, getPostBySlug } from '../../../lib/blog';
 import { getAuthor } from '../../../lib/blog-authors';
-import { loadGoogleFont, loadLocalGaramond, satoriFonts } from '../../og-font';
+import { loadCardFonts } from '../../og-font';
 
 export const runtime = 'nodejs';
 export const alt = 'Threadplane blog post';
@@ -12,6 +12,22 @@ interface Params {
   params: Promise<{ slug: string }>;
 }
 
+/**
+ * Prerenders one card per published post at build time. Mirrors the
+ * `generateStaticParams` in this segment's `page.tsx`, so drafts are excluded.
+ *
+ * This is load-bearing beyond the obvious caching win. Satori rejects some
+ * markup at render time (a div with multiple children and no explicit
+ * `display`, for one) and a request-time route turns that into a production
+ * 500 on every post — which is exactly how the byline below shipped broken.
+ * Prerendering promotes that whole class of mistake into a build failure.
+ * It also keeps the MDX read and the Google Fonts round-trips on the build,
+ * where `resolveWebsiteDir()` is known to resolve, rather than per request.
+ */
+export function generateStaticParams() {
+  return getAllPosts().map((p) => ({ slug: p.slug }));
+}
+
 export default async function og({ params }: Params) {
   const { slug } = await params;
   const post = getPostBySlug(slug);
@@ -39,18 +55,9 @@ export default async function og({ params }: Params) {
     );
   }
 
-  const [garamondBold, interRegular, interBold] = await Promise.all([
-    loadLocalGaramond(),
-    loadGoogleFont('Inter', 400),
-    loadGoogleFont('Inter', 600),
-  ]);
-  const fonts = satoriFonts([
-    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 },
-  ]);
-
+  const fonts = await loadCardFonts();
   const author = getAuthor(post.frontmatter.author);
+
   return new ImageResponse(
     (
       <div
@@ -68,7 +75,6 @@ export default async function og({ params }: Params) {
       >
         <div
           style={{
-            display: 'flex',
             fontSize: 24,
             textTransform: 'uppercase',
             letterSpacing: '0.12em',
@@ -79,7 +85,6 @@ export default async function og({ params }: Params) {
         </div>
         <div
           style={{
-            display: 'flex',
             fontFamily: 'EB Garamond, Georgia, serif',
             fontSize: 64,
             fontWeight: 700,
@@ -92,8 +97,10 @@ export default async function og({ params }: Params) {
         </div>
         {/*
           Satori requires an explicit `display` on any div with more than one
-          child node, and throws (→ HTTP 500) otherwise. This byline has three
-          (name, separator, date), so the `display: flex` is load-bearing.
+          child node, and throws otherwise. This byline has three (name,
+          separator, date), so the `display: flex` is load-bearing — its
+          absence is what 500ed every post's card. The two divs above have a
+          single child each and need no `display`.
         */}
         <div style={{ display: 'flex', fontSize: 24, opacity: 0.7 }}>
           {author.name} · {post.frontmatter.date}
diff --git a/apps/website/src/app/blog/[slug]/page.tsx b/apps/website/src/app/blog/[slug]/page.tsx
index 57ec7ef9b..ce64c7712 100644
--- a/apps/website/src/app/blog/[slug]/page.tsx
+++ b/apps/website/src/app/blog/[slug]/page.tsx
@@ -9,7 +9,7 @@ import { Eyebrow } from '../../../components/ui/Eyebrow';
 import { getAllPosts, getPostBySlug, formatPostDate, readingTimeMin } from '../../../lib/blog';
 import { getAuthor } from '../../../lib/blog-authors';
 import { extractHeadings } from '../../../lib/extract-headings';
-import { createPageMetadata } from '../../../lib/site-metadata';
+import { createPageMetadata, ogImagePath } from '../../../lib/site-metadata';
 import { getPostLastModified, publishedDate } from '../../../lib/sitemap-dates';
 import { JsonLd } from '../../../components/shared/JsonLd';
 import { blogPostingJsonLd, breadcrumbJsonLd } from '../../../lib/structured-data';
@@ -40,7 +40,7 @@ export async function generateMetadata({ params }: Params): Promise<Metadata> {
     description: post.frontmatter.description,
     pathname,
     type: 'article',
-    image: `${pathname}/opengraph-image`,
+    image: ogImagePath(post.slug),
     article: published
       ? {
           publishedTime: published.toISOString(),
diff --git a/apps/website/src/app/og-font.ts b/apps/website/src/app/og-font.ts
index 401e91289..7149e753b 100644
--- a/apps/website/src/app/og-font.ts
+++ b/apps/website/src/app/og-font.ts
@@ -24,10 +24,14 @@
  * from this server-side render path (never downloaded by browsers).
  */
 
+/** The CSS weight domain Satori accepts — wider than the weights we ship. */
+export type OgFontWeight = 100 | 200 | 300 | 400 | 500 | 600 | 700 | 800 | 900;
+
 export interface OgFont {
   name: string;
   data: ArrayBuffer;
-  weight: 400 | 600 | 700;
+  /** Satori matches the closest available weight. */
+  weight: OgFontWeight;
   style: 'normal';
 }
 
@@ -84,3 +88,25 @@ export function satoriFonts(candidates: (OgFont | null)[]): OgFont[] | undefined
   const fonts = candidates.filter((f): f is OgFont => f !== null);
   return fonts.length > 0 ? fonts : undefined;
 }
+
+/**
+ * Loads the shared card font set: bundled Garamond for headlines, Inter for
+ * body copy, and optionally JetBrains Mono for the eyebrow/pill lettering.
+ *
+ * Every load is best-effort, so this returns `undefined` (not `[]`) when the
+ * TTF is missing *and* Google Fonts is unreachable — see `satoriFonts`.
+ */
+export async function loadCardFonts(options: { mono?: boolean } = {}): Promise<OgFont[] | undefined> {
+  const [garamondBold, interRegular, interBold, monoBold] = await Promise.all([
+    loadLocalGaramond(),
+    loadGoogleFont('Inter', 400),
+    loadGoogleFont('Inter', 600),
+    options.mono ? loadGoogleFont('JetBrains+Mono', 700) : Promise.resolve(null),
+  ]);
+  return satoriFonts([
+    garamondBold && { name: 'EB Garamond', data: garamondBold, weight: 700, style: 'normal' },
+    interRegular && { name: 'Inter', data: interRegular, weight: 400, style: 'normal' },
+    interBold && { name: 'Inter', data: interBold, weight: 600, style: 'normal' },
+    monoBold && { name: 'JetBrains Mono', data: monoBold, weight: 700, style: 'normal' },
+  ]);
+}
diff --git a/apps/website/src/app/opengraph-image.tsx b/apps/website/src/app/opengraph-image.tsx
index 8f176d244..16870fa71 100644
--- a/apps/website/src/app/opengraph-image.tsx
+++ b/apps/website/src/app/opengraph-image.tsx
@@ -7,7 +7,7 @@
  */
 import { ImageResponse } from 'next/og';
 import { POSITIONING_PROOF_POINTS, PRIMARY_TAGLINE, SHORT_POSITIONING_DESCRIPTION } from '../lib/positioning';
-import { loadGoogleFont, loadLocalGaramond, satoriFonts } from './og-font';
+import { loadCardFonts } from './og-font';
 
 // Node runtime (not edge) so we can read the bundled Garamond TTF off disk.
 // Font loading lives in ./og-font so the TTF stays statically traceable.
@@ -17,18 +17,7 @@ export const size = { width: 1200, height: 630 };
 export const contentType = 'image/png';
 
 export default async function OpenGraphImage() {
-  const [garamondBold, interRegular, interBold, monoBold] = await Promise.all([
-    loadLocalGaramond(),
-    loadGoogleFont('Inter', 400),
-    loadGoogleFont('Inter', 600),
-    loadGoogleFont('JetBrains+Mono', 700),
-  ]);
-  const fonts = satoriFonts([
-    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 },
-    monoBold && { name: 'JetBrains Mono', data: monoBold, weight: 700 as const, style: 'normal' as const },
-  ]);
+  const fonts = await loadCardFonts({ mono: true });
 
   return new ImageResponse(
     (
diff --git a/apps/website/src/lib/site-metadata.ts b/apps/website/src/lib/site-metadata.ts
index f2bf02c8c..72c8366a3 100644
--- a/apps/website/src/lib/site-metadata.ts
+++ b/apps/website/src/lib/site-metadata.ts
@@ -16,6 +16,18 @@ export {
   SHORT_POSITIONING_DESCRIPTION,
 } from './positioning';
 
+/**
+ * Path of a blog post's per-post OpenGraph card.
+ *
+ * Single source of truth: `blog/[slug]/page.tsx` feeds it to
+ * `createPageMetadata` (og:image / twitter:image) and `blogPostingJsonLd`
+ * feeds it to the BlogPosting `image`. Building the string in both places
+ * independently let them drift with both test suites still green.
+ */
+export function ogImagePath(slug: string): string {
+  return `/blog/${slug}/opengraph-image`;
+}
+
 export function getCanonicalPath(pathname: string): string {
   if (pathname === '/') return '/';
   return `/${pathname.replace(/^\/+|\/+$/g, '')}`;
diff --git a/apps/website/src/lib/structured-data.spec.ts b/apps/website/src/lib/structured-data.spec.ts
index d965528b9..334ecd347 100644
--- a/apps/website/src/lib/structured-data.spec.ts
+++ b/apps/website/src/lib/structured-data.spec.ts
@@ -121,8 +121,8 @@ describe('blogPostingJsonLd', () => {
   });
 
   it('points image at the per-post opengraph-image route', () => {
-    // Must stay in lockstep with the `image` that `blog/[slug]/page.tsx` hands
-    // `createPageMetadata`, so og:image and the BlogPosting agree.
+    // Shares `ogImagePath` with the `image` that `blog/[slug]/page.tsx` hands
+    // `createPageMetadata`, so og:image and the BlogPosting cannot drift.
     expect(blogPostingJsonLd(SAMPLE_POST)['image']).toBe(
       'https://threadplane.ai/blog/a-post/opengraph-image',
     );
diff --git a/apps/website/src/lib/structured-data.ts b/apps/website/src/lib/structured-data.ts
index f63e8064e..9fc3721f6 100644
--- a/apps/website/src/lib/structured-data.ts
+++ b/apps/website/src/lib/structured-data.ts
@@ -1,5 +1,5 @@
 // SPDX-License-Identifier: MIT
-import { getCanonicalUrl, resolveModifiedTime, SITE_NAME } from './site-metadata';
+import { getCanonicalUrl, ogImagePath, resolveModifiedTime, SITE_NAME } from './site-metadata';
 import { SHORT_POSITIONING_DESCRIPTION } from './positioning';
 
 /** A single schema.org node, ready to be serialized into a `ld+json` script. */
@@ -113,8 +113,7 @@ export interface BlogPostingInput {
 }
 
 export function blogPostingJsonLd(post: BlogPostingInput) {
-  const pathname = `/blog/${post.slug}`;
-  const url = getCanonicalUrl(pathname);
+  const url = getCanonicalUrl(`/blog/${post.slug}`);
   return {
     '@context': SCHEMA_CONTEXT,
     '@type': 'BlogPosting',
@@ -125,7 +124,7 @@ export function blogPostingJsonLd(post: BlogPostingInput) {
     datePublished: post.datePublished,
     dateModified: resolveModifiedTime(post.datePublished, post.dateModified),
     // Per-post card, matching the `og:image` that `generateMetadata` emits.
-    image: getCanonicalUrl(`${pathname}/opengraph-image`),
+    image: getCanonicalUrl(ogImagePath(post.slug)),
     // Omitted rather than left undefined, matching `dateModified` below.
     ...(post.tags?.length ? { keywords: post.tags } : {}),
     // No `url` on the author until /about exists (task 11); a 404 author URL is

From c6aa8fefc6903f80eb71bc3c1ec122660cf2940b Mon Sep 17 00:00:00 2001
From: Brian Love <brian@liveloveapp.com>
Date: Thu, 20 Aug 2026 14:44:57 -0700
Subject: [PATCH 22/35] fix(website): keep anchor glyphs out of heading text
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Docs and blog headings rendered a literal `#` text node before the
heading children, so every extracted heading came out as
`#Prerequisites` / `#1. Install the packages` — polluting search
snippets, page outlines, and anything summarizing the page from the DOM.

The `#` is now CSS generated content on `.heading-anchor::before`, and
the anchor is rendered after `{children}`. Extracted text is exactly the
heading text, while the permalink stays a real link with its
`aria-label` and its place in the tab order.

Both MDX heading overrides (MdxRenderer and the choosing-an-adapter
page, which had its own copy of the same bug) now share one
`mdxHeadingComponents` module, covered by a regression spec asserting
heading `textContent` carries no `#`.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
---
 .../src/app/docs/choosing-an-adapter/page.tsx | 22 +------
 apps/website/src/app/global.css               |  9 +++
 .../src/components/docs/MdxRenderer.tsx       | 14 +----
 .../src/components/docs/mdx/headings.spec.tsx | 63 +++++++++++++++++++
 .../src/components/docs/mdx/headings.tsx      | 33 ++++++++++
 5 files changed, 109 insertions(+), 32 deletions(-)
 create mode 100644 apps/website/src/components/docs/mdx/headings.spec.tsx
 create mode 100644 apps/website/src/components/docs/mdx/headings.tsx

diff --git a/apps/website/src/app/docs/choosing-an-adapter/page.tsx b/apps/website/src/app/docs/choosing-an-adapter/page.tsx
index 52828a617..fc9daef25 100644
--- a/apps/website/src/app/docs/choosing-an-adapter/page.tsx
+++ b/apps/website/src/app/docs/choosing-an-adapter/page.tsx
@@ -15,6 +15,7 @@ import { Tabs, Tab } from '../../../components/docs/mdx/Tabs';
 import { Card, CardGroup } from '../../../components/docs/mdx/Card';
 import { CodeGroup } from '../../../components/docs/mdx/CodeGroup';
 import { Pre } from '../../../components/docs/mdx/CodeBlock';
+import { mdxHeadingComponents } from '../../../components/docs/mdx/headings';
 import { createPageMetadata } from '../../../lib/site-metadata';
 
 export const metadata = createPageMetadata({
@@ -39,26 +40,7 @@ const mdxComponents = {
       <table {...rest}>{children}</table>
     </div>
   ),
-  h2: ({ id, children, ...rest }: React.HTMLAttributes<HTMLHeadingElement>) => (
-    <h2 id={id} {...rest}>
-      {id ? (
-        <a href={`#${id}`} aria-label={`Link to ${id}`} className="heading-anchor">
-          #
-        </a>
-      ) : null}
-      {children}
-    </h2>
-  ),
-  h3: ({ id, children, ...rest }: React.HTMLAttributes<HTMLHeadingElement>) => (
-    <h3 id={id} {...rest}>
-      {id ? (
-        <a href={`#${id}`} aria-label={`Link to ${id}`} className="heading-anchor">
-          #
-        </a>
-      ) : null}
-      {children}
-    </h3>
-  ),
+  ...mdxHeadingComponents,
 };
 
 const rehypeOptions = {
diff --git a/apps/website/src/app/global.css b/apps/website/src/app/global.css
index 7e8041115..1878ca18c 100644
--- a/apps/website/src/app/global.css
+++ b/apps/website/src/app/global.css
@@ -290,6 +290,15 @@ html {
   text-decoration: none;
   transition: opacity 120ms ease;
 }
+/*
+ * The `#` glyph is generated content, never a text node: that keeps it out of
+ * the heading's textContent so extracted headings ("Prerequisites") stay clean
+ * for search snippets, page outlines, and agents reading the DOM.
+ */
+.docs-prose h2 .heading-anchor::before,
+.docs-prose h3 .heading-anchor::before {
+  content: '#';
+}
 .docs-prose h2:hover .heading-anchor,
 .docs-prose h3:hover .heading-anchor,
 .docs-prose h2 .heading-anchor:focus-visible,
diff --git a/apps/website/src/components/docs/MdxRenderer.tsx b/apps/website/src/components/docs/MdxRenderer.tsx
index 7b8bd6b11..e7cc51d92 100644
--- a/apps/website/src/components/docs/MdxRenderer.tsx
+++ b/apps/website/src/components/docs/MdxRenderer.tsx
@@ -7,6 +7,7 @@ import { Card, CardGroup } from './mdx/Card';
 import { CodeGroup } from './mdx/CodeGroup';
 import { Pre } from './mdx/CodeBlock';
 import { FeatureChips } from './mdx/FeatureChips';
+import { mdxHeadingComponents } from './mdx/headings';
 import { ArchFlowDiagram } from './ArchFlowDiagram';
 import { AgUiArchDiagram } from './AgUiArchDiagram';
 import { type LibraryId } from '../../lib/docs-config';
@@ -32,18 +33,7 @@ const mdxComponents = {
       <table {...rest}>{children}</table>
     </div>
   ),
-  h2: ({ id, children, ...rest }: React.HTMLAttributes<HTMLHeadingElement>) => (
-    <h2 id={id} {...rest}>
-      {id ? <a href={`#${id}`} aria-label={`Link to ${id}`} className="heading-anchor">#</a> : null}
-      {children}
-    </h2>
-  ),
-  h3: ({ id, children, ...rest }: React.HTMLAttributes<HTMLHeadingElement>) => (
-    <h3 id={id} {...rest}>
-      {id ? <a href={`#${id}`} aria-label={`Link to ${id}`} className="heading-anchor">#</a> : null}
-      {children}
-    </h3>
-  ),
+  ...mdxHeadingComponents,
 };
 
 const rehypeOptions = {
diff --git a/apps/website/src/components/docs/mdx/headings.spec.tsx b/apps/website/src/components/docs/mdx/headings.spec.tsx
new file mode 100644
index 000000000..12fae7c2c
--- /dev/null
+++ b/apps/website/src/components/docs/mdx/headings.spec.tsx
@@ -0,0 +1,63 @@
+// SPDX-License-Identifier: MIT
+// @vitest-environment jsdom
+import React from 'react';
+import { describe, expect, it } from 'vitest';
+import { render } from '@testing-library/react';
+import { mdxHeadingComponents } from './headings';
+
+const { h2: H2, h3: H3 } = mdxHeadingComponents;
+
+describe('mdx heading components', () => {
+  it('extracts H2 text with no anchor glyph anywhere in it', () => {
+    const { container } = render(<H2 id="prerequisites">Prerequisites</H2>);
+    const heading = container.querySelector('h2');
+
+    expect(heading?.textContent).toBe('Prerequisites');
+    expect(heading?.textContent).not.toContain('#');
+  });
+
+  it('extracts H3 text with no anchor glyph anywhere in it', () => {
+    const { container } = render(<H3 id="troubleshooting">Troubleshooting</H3>);
+    const heading = container.querySelector('h3');
+
+    expect(heading?.textContent).toBe('Troubleshooting');
+    expect(heading?.textContent).not.toContain('#');
+  });
+
+  it('keeps a numbered heading clean (the live-site regression case)', () => {
+    const { container } = render(<H2 id="1-install-the-packages">1. Install the packages</H2>);
+
+    expect(container.querySelector('h2')?.textContent).toBe('1. Install the packages');
+  });
+
+  it('still renders a labelled, keyboard-reachable permalink after the text', () => {
+    const { container } = render(<H2 id="prerequisites">Prerequisites</H2>);
+    const anchor = container.querySelector('a.heading-anchor') as HTMLAnchorElement | null;
+
+    expect(anchor).not.toBeNull();
+    expect(anchor?.getAttribute('href')).toBe('#prerequisites');
+    expect(anchor?.getAttribute('aria-label')).toBe('Link to prerequisites');
+    // Reachable by keyboard: not hidden from assistive tech, not removed from tab order.
+    expect(anchor?.getAttribute('aria-hidden')).toBeNull();
+    expect(anchor?.getAttribute('tabindex')).toBeNull();
+    // The anchor is the last child, so reading order is text-then-permalink.
+    expect(container.querySelector('h2')?.lastElementChild).toBe(anchor);
+  });
+
+  it('omits the anchor when the heading has no id', () => {
+    const { container } = render(<H2>No slug</H2>);
+
+    expect(container.querySelector('a.heading-anchor')).toBeNull();
+    expect(container.querySelector('h2')?.textContent).toBe('No slug');
+  });
+
+  it('forwards extra props onto the heading element', () => {
+    const { container } = render(
+      <H3 id="api" className="custom">
+        API
+      </H3>,
+    );
+
+    expect(container.querySelector('h3')?.className).toBe('custom');
+  });
+});
diff --git a/apps/website/src/components/docs/mdx/headings.tsx b/apps/website/src/components/docs/mdx/headings.tsx
new file mode 100644
index 000000000..32ec9f1c7
--- /dev/null
+++ b/apps/website/src/components/docs/mdx/headings.tsx
@@ -0,0 +1,33 @@
+import type { HTMLAttributes } from 'react';
+
+/**
+ * Permalink affordance rendered alongside MDX headings.
+ *
+ * The visible `#` glyph is supplied by CSS (`.docs-prose .heading-anchor::before`
+ * in global.css) rather than by a text node, so it never lands in the heading's
+ * `textContent`. That keeps extracted heading text clean for search snippets,
+ * page outlines, and any agent reading the DOM, while the anchor itself stays a
+ * real, keyboard-reachable, accessibly-named link.
+ *
+ * It is rendered *after* `{children}` so the reading order is
+ * "heading text, then permalink" even if the stylesheet never loads.
+ */
+function HeadingAnchor({ id }: { id: string }) {
+  return <a href={`#${id}`} aria-label={`Link to ${id}`} className="heading-anchor" />;
+}
+
+/** MDX component overrides that add permalink anchors to H2/H3. */
+export const mdxHeadingComponents = {
+  h2: ({ id, children, ...rest }: HTMLAttributes<HTMLHeadingElement>) => (
+    <h2 id={id} {...rest}>
+      {children}
+      {id ? <HeadingAnchor id={id} /> : null}
+    </h2>
+  ),
+  h3: ({ id, children, ...rest }: HTMLAttributes<HTMLHeadingElement>) => (
+    <h3 id={id} {...rest}>
+      {children}
+      {id ? <HeadingAnchor id={id} /> : null}
+    </h3>
+  ),
+};

From 35f573d793f8ab6baf67270b03a255ae58976c8a Mon Sep 17 00:00:00 2001
From: Brian Love <brian@liveloveapp.com>
Date: Thu, 20 Aug 2026 14:54:06 -0700
Subject: [PATCH 23/35] test(website): guard the css-generated heading anchor
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

The heading `#` glyph is now CSS generated content, so the visible
permalink affordance hangs entirely on one declaration that jsdom
cannot see — it does not resolve pseudo-element content. Add a
Playwright assertion in the docs spec that reads
`getComputedStyle(el, '::before').content` off the rendered anchor and
pins it to `"#"`, alongside a check that the heading text carries no
glyph. Verified red by commenting out the rule (received "none").

Also label the permalink with the heading text rather than the slug, so
it announces "Link to At a glance" instead of "Link to at-a-glance".
Children are frequently nested nodes, so the text is flattened
recursively and falls back to the id when nothing can be derived.

Correct the module comment to name the real selectors: the CSS is scoped
to H2/H3 inside `.docs-prose`, not to `.heading-anchor` generally.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
---
 apps/website/e2e/docs.spec.ts                 | 18 ++++++++
 .../src/components/docs/mdx/headings.spec.tsx | 34 ++++++++++++++-
 .../src/components/docs/mdx/headings.tsx      | 42 ++++++++++++++-----
 3 files changed, 82 insertions(+), 12 deletions(-)

diff --git a/apps/website/e2e/docs.spec.ts b/apps/website/e2e/docs.spec.ts
index d0805c4b6..fe2181fde 100644
--- a/apps/website/e2e/docs.spec.ts
+++ b/apps/website/e2e/docs.spec.ts
@@ -89,6 +89,24 @@ test.describe('Docs slug page', () => {
     expect(id?.length).toBeGreaterThan(0);
   });
 
+  test('heading permalinks carry no glyph in the text, only a CSS ::before', async ({ page }) => {
+    await page.goto(route);
+    const h2 = page.locator('article h2').first();
+    await expect(h2).toBeVisible();
+
+    // The `#` must never be a text node: extracted heading text feeds search
+    // snippets, the page outline, and anything summarizing the DOM.
+    expect((await h2.textContent())?.trim()).not.toContain('#');
+
+    // ...which means the visible affordance hangs entirely on one CSS rule
+    // (`.docs-prose h2 .heading-anchor::before` in global.css). jsdom cannot
+    // resolve pseudo-element content, so this is the only place it is guarded.
+    const anchor = h2.locator('a.heading-anchor');
+    await expect(anchor).toHaveCount(1);
+    const glyph = await anchor.evaluate((el) => getComputedStyle(el, '::before').content);
+    expect(glyph).toBe('"#"');
+  });
+
   test('breadcrumb renders exactly once', async ({ page }) => {
     await page.goto('/docs/langgraph/getting-started/introduction');
     await expect(page.locator('nav[aria-label="Breadcrumb"]')).toHaveCount(1);
diff --git a/apps/website/src/components/docs/mdx/headings.spec.tsx b/apps/website/src/components/docs/mdx/headings.spec.tsx
index 12fae7c2c..b50280b9e 100644
--- a/apps/website/src/components/docs/mdx/headings.spec.tsx
+++ b/apps/website/src/components/docs/mdx/headings.spec.tsx
@@ -36,7 +36,7 @@ describe('mdx heading components', () => {
 
     expect(anchor).not.toBeNull();
     expect(anchor?.getAttribute('href')).toBe('#prerequisites');
-    expect(anchor?.getAttribute('aria-label')).toBe('Link to prerequisites');
+    expect(anchor?.getAttribute('aria-label')).toBe('Link to Prerequisites');
     // Reachable by keyboard: not hidden from assistive tech, not removed from tab order.
     expect(anchor?.getAttribute('aria-hidden')).toBeNull();
     expect(anchor?.getAttribute('tabindex')).toBeNull();
@@ -44,6 +44,38 @@ describe('mdx heading components', () => {
     expect(container.querySelector('h2')?.lastElementChild).toBe(anchor);
   });
 
+  it('labels the permalink with the heading text, not the slug', () => {
+    const { container } = render(<H2 id="at-a-glance">At a glance</H2>);
+
+    expect(container.querySelector('a.heading-anchor')?.getAttribute('aria-label')).toBe(
+      'Link to At a glance',
+    );
+  });
+
+  it('derives the label from nested nodes, not [object Object]', () => {
+    const { container } = render(
+      <H3 id="wire-providechat">
+        Wire <code>provideChat()</code> first
+      </H3>,
+    );
+
+    expect(container.querySelector('a.heading-anchor')?.getAttribute('aria-label')).toBe(
+      'Link to Wire provideChat() first',
+    );
+  });
+
+  it('falls back to the id when no text can be derived from children', () => {
+    const { container } = render(
+      <H2 id="diagram">
+        <svg />
+      </H2>,
+    );
+
+    expect(container.querySelector('a.heading-anchor')?.getAttribute('aria-label')).toBe(
+      'Link to diagram',
+    );
+  });
+
   it('omits the anchor when the heading has no id', () => {
     const { container } = render(<H2>No slug</H2>);
 
diff --git a/apps/website/src/components/docs/mdx/headings.tsx b/apps/website/src/components/docs/mdx/headings.tsx
index 32ec9f1c7..dc0c032d2 100644
--- a/apps/website/src/components/docs/mdx/headings.tsx
+++ b/apps/website/src/components/docs/mdx/headings.tsx
@@ -1,19 +1,39 @@
-import type { HTMLAttributes } from 'react';
+import { isValidElement, type HTMLAttributes, type ReactNode } from 'react';
+
+/**
+ * Flatten a heading's children to plain text so the permalink can announce the
+ * heading itself ("Link to At a glance") rather than its slug
+ * ("Link to at-a-glance"). Children are frequently an array of nodes — MDX
+ * wraps inline code, emphasis, and links in elements — so this walks them.
+ */
+function headingText(node: ReactNode): string {
+  if (node === null || node === undefined || typeof node === 'boolean') return '';
+  if (typeof node === 'string' || typeof node === 'number') return String(node);
+  if (Array.isArray(node)) return node.map(headingText).join('');
+  if (isValidElement(node)) return headingText((node.props as { children?: ReactNode }).children);
+  return '';
+}
 
 /**
  * Permalink affordance rendered alongside MDX headings.
  *
- * The visible `#` glyph is supplied by CSS (`.docs-prose .heading-anchor::before`
- * in global.css) rather than by a text node, so it never lands in the heading's
- * `textContent`. That keeps extracted heading text clean for search snippets,
- * page outlines, and any agent reading the DOM, while the anchor itself stays a
- * real, keyboard-reachable, accessibly-named link.
+ * The visible `#` glyph is supplied by CSS — the
+ * `.docs-prose h2 .heading-anchor::before, .docs-prose h3 .heading-anchor::before`
+ * rules in global.css — rather than by a text node, so it never lands in the
+ * heading's `textContent`. That keeps extracted heading text clean for search
+ * snippets, page outlines, and any agent reading the DOM, while the anchor
+ * itself stays a real, keyboard-reachable, accessibly-named link.
+ *
+ * Note the CSS is scoped to H2/H3 *inside `.docs-prose`*: rendered under any
+ * other wrapper, or at another heading level, this is an empty unstyled link
+ * with no visible affordance. Keep the selectors and this component in step.
  *
- * It is rendered *after* `{children}` so the reading order is
+ * The anchor is rendered *after* `{children}` so the reading order is
  * "heading text, then permalink" even if the stylesheet never loads.
  */
-function HeadingAnchor({ id }: { id: string }) {
-  return <a href={`#${id}`} aria-label={`Link to ${id}`} className="heading-anchor" />;
+function HeadingAnchor({ id, children }: { id: string; children: ReactNode }) {
+  const label = headingText(children).replace(/\s+/g, ' ').trim() || id;
+  return <a href={`#${id}`} aria-label={`Link to ${label}`} className="heading-anchor" />;
 }
 
 /** MDX component overrides that add permalink anchors to H2/H3. */
@@ -21,13 +41,13 @@ export const mdxHeadingComponents = {
   h2: ({ id, children, ...rest }: HTMLAttributes<HTMLHeadingElement>) => (
     <h2 id={id} {...rest}>
       {children}
-      {id ? <HeadingAnchor id={id} /> : null}
+      {id ? <HeadingAnchor id={id}>{children}</HeadingAnchor> : null}
     </h2>
   ),
   h3: ({ id, children, ...rest }: HTMLAttributes<HTMLHeadingElement>) => (
     <h3 id={id} {...rest}>
       {children}
-      {id ? <HeadingAnchor id={id} /> : null}
+      {id ? <HeadingAnchor id={id}>{children}</HeadingAnchor> : null}
     </h3>
   ),
 };

From baa5ddb6a408c72b590cf2970510abb8f9c35d32 Mon Sep 17 00:00:00 2001
From: Brian Love <brian@liveloveapp.com>
Date: Thu, 20 Aug 2026 14:57:41 -0700
Subject: [PATCH 24/35] feat(website): add /about page carrying a Person entity
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Establishes an attributable author for the site: an AboutPage JSON-LD
graph whose mainEntity is a Person built from the existing
`blogAuthors['brian']` record, referencing the Organization the root
layout already mounts.

Now that the route exists, blog bylines carry `author.url` pointing at
it — deliberately omitted before, when a 404 author URL was the worse
signal.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
---
 apps/website/src/app/about/page.tsx           | 146 ++++++++++++++++++
 apps/website/src/components/shared/Footer.tsx |   6 +
 apps/website/src/lib/site-metadata.ts         |   2 +-
 apps/website/src/lib/sitemap-dates.spec.ts    |   8 +
 apps/website/src/lib/structured-data.spec.ts  |  65 ++++++++
 apps/website/src/lib/structured-data.ts       |  67 +++++++-
 6 files changed, 290 insertions(+), 4 deletions(-)
 create mode 100644 apps/website/src/app/about/page.tsx

diff --git a/apps/website/src/app/about/page.tsx b/apps/website/src/app/about/page.tsx
new file mode 100644
index 000000000..b43821207
--- /dev/null
+++ b/apps/website/src/app/about/page.tsx
@@ -0,0 +1,146 @@
+// SPDX-License-Identifier: MIT
+import Link from 'next/link';
+import { tokens } from '@threadplane/design-tokens';
+import { Container } from '../../components/ui/Container';
+import { Section } from '../../components/ui/Section';
+import { Eyebrow } from '../../components/ui/Eyebrow';
+import { JsonLd } from '../../components/shared/JsonLd';
+import { aboutPageJsonLd } from '../../lib/structured-data';
+import { blogAuthors } from '../../lib/blog-authors';
+import { createPageMetadata } from '../../lib/site-metadata';
+import { LONG_SUBHEAD } from '../../lib/positioning';
+
+const REPOSITORY_URL = 'https://github.com/cacheplane/angular-agent-framework';
+
+/**
+ * The single author record the site already publishes (blog bylines read the
+ * same object), so the Person node and every BlogPosting byline state one name
+ * and one role rather than two that happen to agree.
+ */
+const author = blogAuthors['brian'];
+
+/**
+ * Topics this site actually publishes about — the libraries it ships and the
+ * runtimes they adapt. `knowsAbout` is an expertise claim, so it lists only
+ * subjects with docs and code behind them in this repository.
+ */
+const KNOWS_ABOUT = [
+  'Angular',
+  'TypeScript',
+  'LangGraph',
+  'AG-UI',
+  'Generative UI',
+  'Agent user interfaces',
+] as const;
+
+export const metadata = createPageMetadata({
+  title: 'About — Threadplane',
+  description: `Who writes Threadplane: ${author.name}, ${author.role}. ${author.bio}`,
+  pathname: '/about',
+  type: 'website',
+});
+
+const bodyStyle = {
+  fontFamily: tokens.typography.bodyLg.family,
+  fontSize: tokens.typography.bodyLg.size,
+  lineHeight: tokens.typography.bodyLg.line,
+  color: tokens.colors.textSecondary,
+  margin: 0,
+  marginBottom: 16,
+  maxWidth: '60ch',
+} as const;
+
+const headingStyle = {
+  fontFamily: tokens.typography.h2.family,
+  fontSize: tokens.typography.h2.size,
+  color: tokens.colors.textPrimary,
+  margin: 0,
+  marginBottom: 12,
+} as const;
+
+const linkStyle = { color: tokens.colors.accent } as const;
+
+export default function AboutPage() {
+  return (
+    <>
+      <JsonLd data={aboutPageJsonLd(author, KNOWS_ABOUT)} />
+
+      <Section surface="canvas" ariaLabelledBy="about-heading">
+        <Container>
+          <div style={{ maxWidth: 720 }}>
+            <Eyebrow tone="accent" style={{ marginBottom: 16 }}>About</Eyebrow>
+            <h1
+              id="about-heading"
+              style={{
+                fontFamily: tokens.typography.h1.family,
+                fontSize: tokens.typography.h1.size,
+                lineHeight: tokens.typography.h1.line,
+                fontWeight: 700,
+                color: tokens.colors.textPrimary,
+                margin: 0,
+                marginBottom: 16,
+                letterSpacing: '-0.02em',
+              }}
+            >
+              Who writes Threadplane
+            </h1>
+            <p style={bodyStyle}>
+              Threadplane is written and maintained by {author.name}, {author.role}.
+            </p>
+            <p style={bodyStyle}>{author.bio}</p>
+            <p style={{ ...bodyStyle, marginBottom: 0 }}>
+              <a
+                href={`https://github.com/${author.github}`}
+                target="_blank"
+                rel="noopener noreferrer"
+                style={linkStyle}
+              >
+                github.com/{author.github}
+              </a>
+            </p>
+          </div>
+        </Container>
+      </Section>
+
+      <Section surface="tinted">
+        <Container>
+          <div style={{ maxWidth: 720 }}>
+            <h2 style={headingStyle}>What Threadplane is</h2>
+            <p style={bodyStyle}>{LONG_SUBHEAD}</p>
+            <p style={{ ...bodyStyle, marginBottom: 0 }}>
+              The source is public at{' '}
+              <a href={REPOSITORY_URL} target="_blank" rel="noopener noreferrer" style={linkStyle}>
+                github.com/cacheplane/angular-agent-framework
+              </a>
+              .
+            </p>
+          </div>
+        </Container>
+      </Section>
+
+      <Section surface="canvas">
+        <Container>
+          <div style={{ maxWidth: 720 }}>
+            <h2 style={headingStyle}>How it is licensed</h2>
+            <p style={bodyStyle}>
+              <code>@threadplane/chat</code> is free for noncommercial use under PolyForm
+              Noncommercial 1.0.0; commercial production use requires a Threadplane Commercial
+              license. The other libraries are MIT. The{' '}
+              <Link href="/docs/licensing" style={linkStyle}>
+                licensing docs
+              </Link>{' '}
+              and the <Link href="/pricing" style={linkStyle}>pricing page</Link> have the details.
+            </p>
+            <p style={{ ...bodyStyle, marginBottom: 0 }}>
+              Questions about a specific build go to{' '}
+              <Link href="/contact" style={linkStyle}>
+                contact
+              </Link>
+              ; ongoing writing is on the <Link href="/blog" style={linkStyle}>blog</Link>.
+            </p>
+          </div>
+        </Container>
+      </Section>
+    </>
+  );
+}
diff --git a/apps/website/src/components/shared/Footer.tsx b/apps/website/src/components/shared/Footer.tsx
index f6d564357..2ba7567e1 100644
--- a/apps/website/src/components/shared/Footer.tsx
+++ b/apps/website/src/components/shared/Footer.tsx
@@ -305,6 +305,12 @@ export function Footer() {
               onMouseLeave={(e) => (e.currentTarget.style.color = tokens.colors.textSecondary)}>
               npm Package
             </a>
+            <Link href="/about" className="transition-colors" style={{ color: tokens.colors.textSecondary }}
+              onClick={() => trackFooterCta('About', '/about')}
+              onMouseEnter={(e) => (e.currentTarget.style.color = tokens.colors.accent)}
+              onMouseLeave={(e) => (e.currentTarget.style.color = tokens.colors.textSecondary)}>
+              About
+            </Link>
             <Link href="/docs/licensing" className="transition-colors" style={{ color: tokens.colors.textSecondary }}
               onClick={() => trackFooterCta('Licensing', '/docs/licensing')}
               onMouseEnter={(e) => (e.currentTarget.style.color = tokens.colors.accent)}
diff --git a/apps/website/src/lib/site-metadata.ts b/apps/website/src/lib/site-metadata.ts
index 72c8366a3..ebae4f853 100644
--- a/apps/website/src/lib/site-metadata.ts
+++ b/apps/website/src/lib/site-metadata.ts
@@ -114,7 +114,7 @@ export function createPageMetadata({
 }
 
 export function getSitemapRoutes(): string[] {
-  const staticRoutes = ['/', '/langgraph', '/render', '/chat', '/ag-ui', '/pricing', '/solutions', '/pilot-to-prod', '/docs', '/blog', '/contact'];
+  const staticRoutes = ['/', '/langgraph', '/render', '/chat', '/ag-ui', '/pricing', '/solutions', '/pilot-to-prod', '/docs', '/blog', '/about', '/contact'];
   const solutionRoutes = getAllSolutionSlugs().map((slug) => `/solutions/${slug}`);
   const docsRoutes = docsConfig.flatMap((library) =>
     library.sections.flatMap((section) =>
diff --git a/apps/website/src/lib/sitemap-dates.spec.ts b/apps/website/src/lib/sitemap-dates.spec.ts
index 72e1b8e3c..249d8a47f 100644
--- a/apps/website/src/lib/sitemap-dates.spec.ts
+++ b/apps/website/src/lib/sitemap-dates.spec.ts
@@ -116,6 +116,14 @@ describe('getSitemapEntries', () => {
     expect(future.map((e) => e.route)).toEqual([]);
   });
 
+  it('indexes /about, dated from its committed page source', () => {
+    // The Person entity is only discoverable if the route is in the sitemap,
+    // and it dates from git like any other hand-written page.
+    const entry = getSitemapEntries().find((e) => e.route === '/about');
+    expect(entry).toBeDefined();
+    if (hasGitHistory()) expect(entry?.lastModified).toBeInstanceOf(Date);
+  });
+
   it('resolves the special docs pages whose route shape differs from library docs', () => {
     const entry = getSitemapEntries().find((e) => e.route === '/docs/choosing-an-adapter');
     if (hasGitHistory()) expect(entry?.lastModified).toBeInstanceOf(Date);
diff --git a/apps/website/src/lib/structured-data.spec.ts b/apps/website/src/lib/structured-data.spec.ts
index 334ecd347..45ee531e8 100644
--- a/apps/website/src/lib/structured-data.spec.ts
+++ b/apps/website/src/lib/structured-data.spec.ts
@@ -6,10 +6,13 @@ import {
   rootJsonLd,
   softwareSourceCodeJsonLd,
   techArticleJsonLd,
+  aboutPageJsonLd,
+  PERSON_ID,
   websiteJsonLd,
   blogPostingJsonLd,
   type JsonLdNode,
 } from './structured-data';
+import { blogAuthors } from './blog-authors';
 
 const ORGANIZATION_ID = 'https://threadplane.ai/#organization';
 
@@ -112,6 +115,9 @@ describe('blogPostingJsonLd', () => {
     expect(data['datePublished']).toBe('2026-08-13');
     expect(data['dateModified']).toBe('2026-08-13');
     expect(data['author']['name']).toBe('Brian Love');
+    // Attribution is only a real signal when the author resolves to a page. The
+    // /about route exists, so the byline links to it.
+    expect(data['author']['url']).toBe('https://threadplane.ai/about');
     expect(String(data['url'])).toBe('https://threadplane.ai/blog/a-post');
   });
 
@@ -197,6 +203,65 @@ describe('softwareSourceCodeJsonLd', () => {
   });
 });
 
+describe('aboutPageJsonLd', () => {
+  const AUTHOR = {
+    name: 'Brian Love',
+    role: 'Founder, Threadplane',
+    bio: 'Angular consultant and open-source maintainer.',
+    github: 'blove',
+  };
+
+  function nodes() {
+    return aboutPageJsonLd(AUTHOR, ['Angular'])['@graph'] as JsonLdNode[];
+  }
+
+  it('bundles an AboutPage whose mainEntity is the Person it ships with', () => {
+    const graph = nodes();
+    const about = graph.find((node) => node['@type'] === 'AboutPage');
+    const person = graph.find((node) => node['@type'] === 'Person');
+    expect(about).toBeDefined();
+    expect(person).toBeDefined();
+    // The reference resolves inside this same graph — that is the point of
+    // emitting them together.
+    expect((about?.['mainEntity'] as JsonLdNode)['@id']).toBe(person?.['@id']);
+    expect(person?.['@id']).toBe(PERSON_ID);
+  });
+
+  it('states nothing about the person that the author record does not', () => {
+    const person = nodes().find((node) => node['@type'] === 'Person') as JsonLdNode;
+    expect(person['name']).toBe(AUTHOR.name);
+    expect(person['jobTitle']).toBe(AUTHOR.role);
+    expect(person['description']).toBe(AUTHOR.bio);
+    expect(person['sameAs']).toEqual(['https://github.com/blove']);
+    expect(person['url']).toBe('https://threadplane.ai/about');
+  });
+
+  it('omits profile, title, and bio fields for an author record that lacks them', () => {
+    const graph = aboutPageJsonLd({ name: 'Anon' }, ['Angular'])['@graph'] as JsonLdNode[];
+    const person = graph.find((node) => node['@type'] === 'Person') as JsonLdNode;
+    expect('sameAs' in person).toBe(false);
+    expect('jobTitle' in person).toBe(false);
+    expect('description' in person).toBe(false);
+  });
+
+  it('references the Organization the root layout mounts', () => {
+    const person = nodes().find((node) => node['@type'] === 'Person') as JsonLdNode;
+    expect((person['worksFor'] as JsonLdNode)['@id']).toBe(ORGANIZATION_ID);
+  });
+
+  it('resolves the real site author to a real GitHub profile', () => {
+    // The page passes `blogAuthors['brian']`; `sameAs` is an identity claim, so
+    // this pins the profile the repo actually knows rather than the fixture's.
+    const graph = aboutPageJsonLd(blogAuthors['brian'], ['Angular'])['@graph'] as JsonLdNode[];
+    const person = graph.find((node) => node['@type'] === 'Person') as JsonLdNode;
+    expect(person['sameAs']).toEqual(['https://github.com/blove']);
+  });
+
+  it('serializes to JSON', () => {
+    expectSerializable(aboutPageJsonLd(AUTHOR, ['Angular']));
+  });
+});
+
 /**
  * Cross-cutting invariants. Asserting these per-builder is what stops one
  * builder from quietly drifting — a dropped `@context` or a `#Organization`
diff --git a/apps/website/src/lib/structured-data.ts b/apps/website/src/lib/structured-data.ts
index 9fc3721f6..bca426520 100644
--- a/apps/website/src/lib/structured-data.ts
+++ b/apps/website/src/lib/structured-data.ts
@@ -1,6 +1,7 @@
 // SPDX-License-Identifier: MIT
 import { getCanonicalUrl, ogImagePath, resolveModifiedTime, SITE_NAME } from './site-metadata';
 import { SHORT_POSITIONING_DESCRIPTION } from './positioning';
+import type { Author } from './blog-authors';
 
 /** A single schema.org node, ready to be serialized into a `ld+json` script. */
 export type JsonLdNode = Record<string, unknown>;
@@ -99,6 +100,65 @@ export function rootJsonLd() {
   };
 }
 
+/**
+ * The /about route, named once. `aboutPageJsonLd` mints the Person `@id` from
+ * it and `blogPostingJsonLd` points every author at it, so the attribution link
+ * and its target cannot drift apart.
+ */
+const ABOUT_PATH = '/about';
+
+/**
+ * Stable identity for the site's author node, so a BlogPosting author and the
+ * /about Person can be recognised as one entity.
+ */
+export const PERSON_ID = `${getCanonicalUrl(ABOUT_PATH)}#person`;
+
+/**
+ * The /about page and the Person it is about, as one `@graph`.
+ *
+ * Bundled for the same reason as {@link rootJsonLd}: the AboutPage's
+ * `mainEntity` reference cannot be orphaned if the Person travels with it.
+ *
+ * `worksFor` refers to the Organization by `@id` rather than repeating it,
+ * which resolves because the root layout mounts {@link rootJsonLd} — including
+ * the Organization node — on every page of the site.
+ *
+ * Every field is derived from the caller's {@link Author} record; nothing about
+ * the person is stated here.
+ */
+export function aboutPageJsonLd(author: Author, knowsAbout: readonly string[]) {
+  const url = getCanonicalUrl(ABOUT_PATH);
+  const person: JsonLdNode = {
+    '@type': 'Person',
+    '@id': PERSON_ID,
+    name: author.name,
+    url,
+    ...(author.role ? { jobTitle: author.role } : {}),
+    ...(author.bio ? { description: author.bio } : {}),
+    // Only profiles the repo actually knows about; `sameAs` is an identity
+    // claim, so a guessed profile is a false one.
+    ...(author.github ? { sameAs: [`https://github.com/${author.github}`] } : {}),
+    knowsAbout: [...knowsAbout],
+    worksFor: { '@id': ORGANIZATION_ID },
+  };
+
+  return {
+    '@context': SCHEMA_CONTEXT,
+    '@graph': [
+      {
+        '@type': 'AboutPage',
+        '@id': `${url}#webpage`,
+        url,
+        name: `About ${author.name}`,
+        mainEntity: { '@id': PERSON_ID },
+        isPartOf: { '@id': `${getCanonicalUrl('/')}#website` },
+        publisher: { '@id': ORGANIZATION_ID },
+      },
+      person,
+    ],
+  };
+}
+
 /** The subset of a blog post that schema.org cares about. */
 export interface BlogPostingInput {
   title: string;
@@ -127,9 +187,10 @@ export function blogPostingJsonLd(post: BlogPostingInput) {
     image: getCanonicalUrl(ogImagePath(post.slug)),
     // Omitted rather than left undefined, matching `dateModified` below.
     ...(post.tags?.length ? { keywords: post.tags } : {}),
-    // No `url` on the author until /about exists (task 11); a 404 author URL is
-    // worse than an unlinked name.
-    author: { '@type': 'Person', name: post.authorName },
+    // `url` points at /about, which renders the matching Person node. Keep the
+    // two together: an author URL is only a real attribution signal while the
+    // page it points at exists and identifies the same person.
+    author: { '@type': 'Person', name: post.authorName, url: getCanonicalUrl(ABOUT_PATH) },
     publisher: { '@id': ORGANIZATION_ID },
   };
 }

From f733f121cc45d7e29ce3c221be9675858f28ab35 Mon Sep 17 00:00:00 2001
From: Brian Love <brian@liveloveapp.com>
Date: Thu, 20 Aug 2026 15:06:13 -0700
Subject: [PATCH 25/35] feat(website): unify the author entity across blog and
 about
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Every BlogPosting byline now carries the same `@id` the /about Person
declares, so the two are one entity to a consumer rather than two nodes
that merely share a name — which is the point of the attribution work.

`knowsAbout` moves onto the Author record beside `bio`: it is a claim
about the person, so it belongs with the person rather than with one
page that renders them.

Also: /about reads the author through `getAuthor()` for its missing-key
fallback, and shares the repository URL constant instead of adding a
third copy.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
---
 apps/website/src/app/about/page.spec.tsx     | 52 ++++++++++++++++++++
 apps/website/src/app/about/page.tsx          | 24 ++-------
 apps/website/src/lib/blog-authors.ts         |  7 +++
 apps/website/src/lib/structured-data.spec.ts | 20 ++++++--
 apps/website/src/lib/structured-data.ts      | 25 ++++++----
 5 files changed, 95 insertions(+), 33 deletions(-)
 create mode 100644 apps/website/src/app/about/page.spec.tsx

diff --git a/apps/website/src/app/about/page.spec.tsx b/apps/website/src/app/about/page.spec.tsx
new file mode 100644
index 000000000..ffa3d47ed
--- /dev/null
+++ b/apps/website/src/app/about/page.spec.tsx
@@ -0,0 +1,52 @@
+// SPDX-License-Identifier: MIT
+// @vitest-environment jsdom
+import React from 'react';
+import { describe, expect, it, vi } from 'vitest';
+import { render, screen } from '@testing-library/react';
+import AboutPage from './page';
+import { getAuthor } from '../../lib/blog-authors';
+
+vi.mock('../../components/ui/Container', () => ({
+  Container: ({ children }: { children: React.ReactNode }) => <div>{children}</div>,
+}));
+vi.mock('../../components/ui/Section', () => ({
+  Section: ({ children }: { children: React.ReactNode }) => <section>{children}</section>,
+}));
+vi.mock('../../components/ui/Eyebrow', () => ({
+  Eyebrow: ({ children }: { children: React.ReactNode }) => <span>{children}</span>,
+}));
+
+const author = getAuthor('brian');
+
+/**
+ * This page is an E-E-A-T signal, so its visible prose is exactly the surface a
+ * fabricated credential would appear on. These assertions tie the rendered
+ * claims back to the author record rather than restating the layout.
+ */
+describe('AboutPage', () => {
+  it('renders the bio verbatim from the author record', () => {
+    render(<AboutPage />);
+    // Not a substring match: any editorial embellishment around the sourced
+    // sentence would still be a claim nothing in the repo supports.
+    expect(screen.getByText(author.bio as string).textContent).toBe(author.bio);
+  });
+
+  it('states the name and role the author record gives, and no other', () => {
+    render(<AboutPage />);
+    expect(screen.getByText(`Threadplane is written and maintained by ${author.name}, ${author.role}.`))
+      .toBeTruthy();
+  });
+
+  it('links the GitHub profile the record names', () => {
+    render(<AboutPage />);
+    expect(screen.getByRole('link', { name: `github.com/${author.github}` }).getAttribute('href'))
+      .toBe(`https://github.com/${author.github}`);
+  });
+
+  it('references no image asset', () => {
+    // There is no headshot in the repo. A later `<img>` here would either point
+    // at a missing file or assert a likeness the project does not have.
+    const { container } = render(<AboutPage />);
+    expect(container.querySelectorAll('img').length).toBe(0);
+  });
+});
diff --git a/apps/website/src/app/about/page.tsx b/apps/website/src/app/about/page.tsx
index b43821207..696662841 100644
--- a/apps/website/src/app/about/page.tsx
+++ b/apps/website/src/app/about/page.tsx
@@ -5,33 +5,17 @@ import { Container } from '../../components/ui/Container';
 import { Section } from '../../components/ui/Section';
 import { Eyebrow } from '../../components/ui/Eyebrow';
 import { JsonLd } from '../../components/shared/JsonLd';
-import { aboutPageJsonLd } from '../../lib/structured-data';
-import { blogAuthors } from '../../lib/blog-authors';
+import { aboutPageJsonLd, REPOSITORY_URL } from '../../lib/structured-data';
+import { getAuthor } from '../../lib/blog-authors';
 import { createPageMetadata } from '../../lib/site-metadata';
 import { LONG_SUBHEAD } from '../../lib/positioning';
 
-const REPOSITORY_URL = 'https://github.com/cacheplane/angular-agent-framework';
-
 /**
  * The single author record the site already publishes (blog bylines read the
  * same object), so the Person node and every BlogPosting byline state one name
  * and one role rather than two that happen to agree.
  */
-const author = blogAuthors['brian'];
-
-/**
- * Topics this site actually publishes about — the libraries it ships and the
- * runtimes they adapt. `knowsAbout` is an expertise claim, so it lists only
- * subjects with docs and code behind them in this repository.
- */
-const KNOWS_ABOUT = [
-  'Angular',
-  'TypeScript',
-  'LangGraph',
-  'AG-UI',
-  'Generative UI',
-  'Agent user interfaces',
-] as const;
+const author = getAuthor('brian');
 
 export const metadata = createPageMetadata({
   title: 'About — Threadplane',
@@ -63,7 +47,7 @@ const linkStyle = { color: tokens.colors.accent } as const;
 export default function AboutPage() {
   return (
     <>
-      <JsonLd data={aboutPageJsonLd(author, KNOWS_ABOUT)} />
+      <JsonLd data={aboutPageJsonLd(author)} />
 
       <Section surface="canvas" ariaLabelledBy="about-heading">
         <Container>
diff --git a/apps/website/src/lib/blog-authors.ts b/apps/website/src/lib/blog-authors.ts
index e3b68ff7d..270e504e9 100644
--- a/apps/website/src/lib/blog-authors.ts
+++ b/apps/website/src/lib/blog-authors.ts
@@ -3,6 +3,12 @@ export interface Author {
   name: string;
   role?: string;
   bio?: string;
+  /**
+   * Topics this author has published work behind. Rendered as schema.org
+   * `knowsAbout` on /about, so it is an expertise claim: list only subjects
+   * with docs and code in this repository.
+   */
+  knowsAbout?: readonly string[];
   twitter?: string;
   github?: string;
   avatar?: string;
@@ -13,6 +19,7 @@ export const blogAuthors: Record<string, Author> = {
     name: 'Brian Love',
     role: 'Founder, Threadplane',
     bio: 'Angular consultant and open-source maintainer. Building agent UI for Angular teams.',
+    knowsAbout: ['Angular', 'TypeScript', 'LangGraph', 'AG-UI', 'Generative UI', 'Agent user interfaces'],
     github: 'blove',
   },
 };
diff --git a/apps/website/src/lib/structured-data.spec.ts b/apps/website/src/lib/structured-data.spec.ts
index 45ee531e8..b6e0603be 100644
--- a/apps/website/src/lib/structured-data.spec.ts
+++ b/apps/website/src/lib/structured-data.spec.ts
@@ -209,10 +209,11 @@ describe('aboutPageJsonLd', () => {
     role: 'Founder, Threadplane',
     bio: 'Angular consultant and open-source maintainer.',
     github: 'blove',
+    knowsAbout: ['Angular'],
   };
 
   function nodes() {
-    return aboutPageJsonLd(AUTHOR, ['Angular'])['@graph'] as JsonLdNode[];
+    return aboutPageJsonLd(AUTHOR)['@graph'] as JsonLdNode[];
   }
 
   it('bundles an AboutPage whose mainEntity is the Person it ships with', () => {
@@ -237,11 +238,12 @@ describe('aboutPageJsonLd', () => {
   });
 
   it('omits profile, title, and bio fields for an author record that lacks them', () => {
-    const graph = aboutPageJsonLd({ name: 'Anon' }, ['Angular'])['@graph'] as JsonLdNode[];
+    const graph = aboutPageJsonLd({ name: 'Anon' })['@graph'] as JsonLdNode[];
     const person = graph.find((node) => node['@type'] === 'Person') as JsonLdNode;
     expect('sameAs' in person).toBe(false);
     expect('jobTitle' in person).toBe(false);
     expect('description' in person).toBe(false);
+    expect('knowsAbout' in person).toBe(false);
   });
 
   it('references the Organization the root layout mounts', () => {
@@ -252,13 +254,13 @@ describe('aboutPageJsonLd', () => {
   it('resolves the real site author to a real GitHub profile', () => {
     // The page passes `blogAuthors['brian']`; `sameAs` is an identity claim, so
     // this pins the profile the repo actually knows rather than the fixture's.
-    const graph = aboutPageJsonLd(blogAuthors['brian'], ['Angular'])['@graph'] as JsonLdNode[];
+    const graph = aboutPageJsonLd(blogAuthors['brian'])['@graph'] as JsonLdNode[];
     const person = graph.find((node) => node['@type'] === 'Person') as JsonLdNode;
     expect(person['sameAs']).toEqual(['https://github.com/blove']);
   });
 
   it('serializes to JSON', () => {
-    expectSerializable(aboutPageJsonLd(AUTHOR, ['Angular']));
+    expectSerializable(aboutPageJsonLd(AUTHOR));
   });
 });
 
@@ -298,6 +300,16 @@ describe('shared node invariants', () => {
     expect((build()[key] as JsonLdNode)['@id']).toBe(ORGANIZATION_ID);
   });
 
+  // The byline and the /about page are the same person, and say so with the
+  // same `@id`. A shared name alone would leave a consumer two nodes to guess at.
+  it('gives a BlogPosting author the id the /about Person declares', () => {
+    const byline = blogPostingJsonLd(SAMPLE_POST)['author'] as JsonLdNode;
+    const graph = aboutPageJsonLd(blogAuthors['brian'])['@graph'] as JsonLdNode[];
+    const person = graph.find((node) => node['@type'] === 'Person') as JsonLdNode;
+    expect(byline['@id']).toBe(person['@id']);
+    expect(byline['@id']).toBe(PERSON_ID);
+  });
+
   it('references the id the Organization node actually declares', () => {
     expect(organizationJsonLd()['@id']).toBe(ORGANIZATION_ID);
   });
diff --git a/apps/website/src/lib/structured-data.ts b/apps/website/src/lib/structured-data.ts
index bca426520..e1d1357fe 100644
--- a/apps/website/src/lib/structured-data.ts
+++ b/apps/website/src/lib/structured-data.ts
@@ -12,7 +12,7 @@ const SCHEMA_CONTEXT = 'https://schema.org';
  * The canonical repository. Verified public; the npm *organization* page is
  * member-gated, so `sameAs` links the public package page instead.
  */
-const REPOSITORY_URL = 'https://github.com/cacheplane/angular-agent-framework';
+export const REPOSITORY_URL = 'https://github.com/cacheplane/angular-agent-framework';
 
 /**
  * Stable identity for the publisher node. Every other node refers to the
@@ -108,8 +108,9 @@ export function rootJsonLd() {
 const ABOUT_PATH = '/about';
 
 /**
- * Stable identity for the site's author node, so a BlogPosting author and the
- * /about Person can be recognised as one entity.
+ * Stable identity for the site's author node. Both {@link aboutPageJsonLd} and
+ * every BlogPosting byline stamp it, which is what makes them one entity to a
+ * consumer rather than two nodes that merely share a name.
  */
 export const PERSON_ID = `${getCanonicalUrl(ABOUT_PATH)}#person`;
 
@@ -126,7 +127,7 @@ export const PERSON_ID = `${getCanonicalUrl(ABOUT_PATH)}#person`;
  * Every field is derived from the caller's {@link Author} record; nothing about
  * the person is stated here.
  */
-export function aboutPageJsonLd(author: Author, knowsAbout: readonly string[]) {
+export function aboutPageJsonLd(author: Author) {
   const url = getCanonicalUrl(ABOUT_PATH);
   const person: JsonLdNode = {
     '@type': 'Person',
@@ -138,7 +139,7 @@ export function aboutPageJsonLd(author: Author, knowsAbout: readonly string[]) {
     // Only profiles the repo actually knows about; `sameAs` is an identity
     // claim, so a guessed profile is a false one.
     ...(author.github ? { sameAs: [`https://github.com/${author.github}`] } : {}),
-    knowsAbout: [...knowsAbout],
+    ...(author.knowsAbout?.length ? { knowsAbout: [...author.knowsAbout] } : {}),
     worksFor: { '@id': ORGANIZATION_ID },
   };
 
@@ -187,10 +188,16 @@ export function blogPostingJsonLd(post: BlogPostingInput) {
     image: getCanonicalUrl(ogImagePath(post.slug)),
     // Omitted rather than left undefined, matching `dateModified` below.
     ...(post.tags?.length ? { keywords: post.tags } : {}),
-    // `url` points at /about, which renders the matching Person node. Keep the
-    // two together: an author URL is only a real attribution signal while the
-    // page it points at exists and identifies the same person.
-    author: { '@type': 'Person', name: post.authorName, url: getCanonicalUrl(ABOUT_PATH) },
+    // The same `@id` the /about Person declares, so a byline and that page are
+    // one entity rather than two similarly-named nodes. The node stays inline
+    // (rather than a bare `@id` reference) because nothing on a post page
+    // defines the Person, and `url` is what makes the identity followable.
+    author: {
+      '@type': 'Person',
+      '@id': PERSON_ID,
+      name: post.authorName,
+      url: getCanonicalUrl(ABOUT_PATH),
+    },
     publisher: { '@id': ORGANIZATION_ID },
   };
 }

From 2a46113b1987d03b87fa5c91671189831ebecc18 Mon Sep 17 00:00:00 2001
From: Brian Love <brian@liveloveapp.com>
Date: Thu, 20 Aug 2026 15:09:10 -0700
Subject: [PATCH 26/35] docs(blog): question-form section headings in the
 2026-05/06 posts

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
---
 ...17-build-a-streaming-chat-ui-in-angular-with-langgraph.mdx | 4 ++--
 ...05-21-build-fullstack-agentic-angular-apps-using-ag-ui.mdx | 4 ++--
 ...26-05-28-human-in-the-loop-langgraph-agents-in-angular.mdx | 2 +-
 .../2026-06-04-human-in-the-loop-ag-ui-agents-in-angular.mdx  | 2 +-
 4 files changed, 6 insertions(+), 6 deletions(-)

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
index 839d10ebc..9d5114723 100644
--- 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
@@ -17,7 +17,7 @@ Most AI chat features still ship without streaming — they buffer the full resp
 - Wire a real LangGraph backend to the UI without writing any transport code.
 - Cover the three production patterns that matter once the scaffold works: errors, threads, and generative UI.
 
-## Why streaming matters
+## Why does streaming matter?
 
 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. If you buffer, every response feels like a page load with no progress indicator.
 
@@ -160,7 +160,7 @@ The slot pattern is intentional: the chat doesn't set your welcome copy, pick yo
 
 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 already use a design system, map your tokens onto theirs in a single stylesheet and the chat picks them up.
 
-## What's happening under the hood
+## What's happening under the hood?
 
 Let's peek at the contract. The adapter exposes a small surface, the chat consumes it, and everything else is implementation detail.
 
diff --git a/apps/website/content/blog/2026-05-21-build-fullstack-agentic-angular-apps-using-ag-ui.mdx b/apps/website/content/blog/2026-05-21-build-fullstack-agentic-angular-apps-using-ag-ui.mdx
index a790bf58f..3c920c87e 100644
--- a/apps/website/content/blog/2026-05-21-build-fullstack-agentic-angular-apps-using-ag-ui.mdx
+++ b/apps/website/content/blog/2026-05-21-build-fullstack-agentic-angular-apps-using-ag-ui.mdx
@@ -152,7 +152,7 @@ No `EventSource`. No reducer. No manual subscribe-and-render plumbing. No store.
 
 Spin up your agent backend, point `url` at it, and the chat just works.
 
-## How AG-UI events become signals
+## How do AG-UI events become signals?
 
 The AG-UI protocol has seventeen event types, grouped into five families:
 
@@ -267,7 +267,7 @@ How you scope threads — per project, per task, per user session — is a produ
 
 If you want a starting point, `@threadplane/chat` exposes a `<chat-sidebar>` primitive that handles the layout without locking you into a persistence model.
 
-## Swap the backend without changing the UI
+## Can you swap the backend without changing the UI?
 
 This is the part that pays off the protocol bet.
 
diff --git a/apps/website/content/blog/2026-05-28-human-in-the-loop-langgraph-agents-in-angular.mdx b/apps/website/content/blog/2026-05-28-human-in-the-loop-langgraph-agents-in-angular.mdx
index ac467cf75..b7049191f 100644
--- a/apps/website/content/blog/2026-05-28-human-in-the-loop-langgraph-agents-in-angular.mdx
+++ b/apps/website/content/blog/2026-05-28-human-in-the-loop-langgraph-agents-in-angular.mdx
@@ -30,7 +30,7 @@ Everything below is running code from the cockpit example at `cockpit/langgraph/
 - Render the approval dialog in Angular with the `<chat-approval-card>` composition.
 - Resume, reject, or edit-then-resume — with a distinct path for each.
 
-## When to use an interrupt
+## When should you use an interrupt?
 
 Most tool calls don't need approval. Reads, searches, and lookups can run unattended. Reach for an interrupt when a tool does something the operator wouldn't want to undo by hand: moves money, sends a customer-facing message, deletes a record, or triggers a deploy.
 
diff --git a/apps/website/content/blog/2026-06-04-human-in-the-loop-ag-ui-agents-in-angular.mdx b/apps/website/content/blog/2026-06-04-human-in-the-loop-ag-ui-agents-in-angular.mdx
index d883230e2..6a1d55895 100644
--- a/apps/website/content/blog/2026-06-04-human-in-the-loop-ag-ui-agents-in-angular.mdx
+++ b/apps/website/content/blog/2026-06-04-human-in-the-loop-ag-ui-agents-in-angular.mdx
@@ -48,7 +48,7 @@ That's the whole client-side delta. The rest of the file — the template bindin
 
 `<chat-approval-card>` reads `agent.interrupt()` (a `Signal<AgentInterrupt | undefined>`), and `submit({ resume })` is part of the runtime-neutral `Agent` contract declared in `@threadplane/chat`. Both adapters populate the signal and forward the resume; the chat surface above doesn't see the wire format.
 
-## When to use an interrupt
+## When should you use an interrupt?
 
 Most tool calls don't need approval. Reads, searches, and lookups can run unattended. Reach for an interrupt when a tool does something the operator wouldn't want to undo by hand: moves money, sends a customer-facing message, deletes a record, or triggers a deploy.
 

From 3339d6bd4e2524f89eb1330360266d197d298f01 Mon Sep 17 00:00:00 2001
From: Brian Love <brian@liveloveapp.com>
Date: Thu, 20 Aug 2026 15:09:50 -0700
Subject: [PATCH 27/35] docs(website): record the no-scaled-content rule for
 solutions pages

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
---
 apps/website/src/lib/solutions-data.ts | 19 +++++++++++++++++++
 1 file changed, 19 insertions(+)

diff --git a/apps/website/src/lib/solutions-data.ts b/apps/website/src/lib/solutions-data.ts
index 20b42d9ec..8d14ea300 100644
--- a/apps/website/src/lib/solutions-data.ts
+++ b/apps/website/src/lib/solutions-data.ts
@@ -1,3 +1,22 @@
+/**
+ * Solutions pages are hand-written, not templated at scale.
+ *
+ * This file drives `/solutions/[slug]`, which makes it look like a page
+ * generator. It is not one, and it must not become one. Google's
+ * scaled-content-abuse policy targets exactly this shape: families of
+ * programmatically generated pages that differ only by keyword.
+ *
+ * The rule: every entry must carry genuinely distinct first-hand content —
+ * a real problem we have seen, a real architecture, real code. If a new
+ * entry would amount to a find-and-replace of an existing one (swap the
+ * vertical noun, keep the structure and the claims), do not add it. Write a
+ * blog post or a docs guide instead, where the thing you actually have to
+ * say can stand on its own.
+ *
+ * Adding an entry is an editorial decision, not a data-file edit.
+ *
+ * See https://developers.google.com/search/docs/fundamentals/ai-optimization-guide
+ */
 export interface SolutionPainPoint {
   title: string;
   description: string;

From b95a201325aa73edd6feed82fec8252b6d3983aa Mon Sep 17 00:00:00 2001
From: Brian Love <brian@liveloveapp.com>
Date: Thu, 20 Aug 2026 15:19:23 -0700
Subject: [PATCH 28/35] feat(website): track ai crawler and ai referral traffic

Google Search Console's Generative AI report is UI-only, and AI crawlers
never execute JavaScript, so the client PostHog snippet cannot observe
either signal. Add edge middleware that classifies the request and emits
marketing:ai_crawler_visit / marketing:ai_referral_visit.

- ai-traffic.ts: pure classifiers. Crawler UAs are matched on published
  tokens (plain Googlebot/Applebot deliberately excluded); referrers are
  matched on the parsed hostname exactly or as a subdomain, so lookalikes
  such as evil-chatgpt.com.attacker.net do not classify.
- Capture goes direct to the PostHog ingest host over fetch, not through
  posthog-node (a Node library; middleware runs on the Edge runtime) and
  not through the /ingest/* rewrites, which exist for the browser.
- Registered with FetchEvent#waitUntil so the response is never delayed,
  with a 2s abort: a dropped event is acceptable, a hung request is not.
- Anonymous by construction: $process_person_profile false, $ip null,
  pathname only (never the query string), and no UA on referral events.
- Crawler events are deduped per crawler/path/hour, best-effort and
  per-instance, so a crawler looping one URL cannot become a firehose.
- Matcher excludes api, _next, ingest, og/twitter image routes and any
  path whose last segment has an extension.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
---
 .../src/lib/analytics/ai-traffic.spec.ts      | 127 ++++++++++++++
 apps/website/src/lib/analytics/ai-traffic.ts  | 142 +++++++++++++++
 apps/website/src/lib/analytics/events.ts      |   5 +
 apps/website/src/middleware.spec.ts           | 104 +++++++++++
 apps/website/src/middleware.ts                | 161 ++++++++++++++++++
 docs/gtm/taxonomy.md                          |   2 +
 6 files changed, 541 insertions(+)
 create mode 100644 apps/website/src/lib/analytics/ai-traffic.spec.ts
 create mode 100644 apps/website/src/lib/analytics/ai-traffic.ts
 create mode 100644 apps/website/src/middleware.spec.ts
 create mode 100644 apps/website/src/middleware.ts

diff --git a/apps/website/src/lib/analytics/ai-traffic.spec.ts b/apps/website/src/lib/analytics/ai-traffic.spec.ts
new file mode 100644
index 000000000..82465087f
--- /dev/null
+++ b/apps/website/src/lib/analytics/ai-traffic.spec.ts
@@ -0,0 +1,127 @@
+// SPDX-License-Identifier: MIT
+import { describe, expect, it } from 'vitest';
+import { classifyAiCrawler, classifyAiReferrer, shouldEmitCrawlerEvent } from './ai-traffic';
+
+describe('classifyAiCrawler', () => {
+  it.each([
+    ['GPTBot/1.2', 'gptbot'],
+    ['ClaudeBot/1.0', 'claudebot'],
+    ['PerplexityBot/1.0', 'perplexitybot'],
+    ['Google-Extended', 'google-extended'],
+  ])('classifies %s as %s', (ua, expected) => {
+    expect(classifyAiCrawler(ua)).toBe(expected);
+  });
+
+  it.each([
+    ['Mozilla/5.0 AppleWebKit/537.36 (KHTML, like Gecko); compatible; GPTBot/1.2; +https://openai.com/gptbot', 'gptbot'],
+    ['Mozilla/5.0 (compatible; OAI-SearchBot/1.0; +https://openai.com/searchbot)', 'oai-searchbot'],
+    ['Mozilla/5.0 (compatible; ChatGPT-User/1.0; +https://openai.com/bot)', 'chatgpt-user'],
+    ['Mozilla/5.0 (compatible; Claude-Web/1.0)', 'claude-web'],
+    ['anthropic-ai', 'anthropic-ai'],
+    ['Mozilla/5.0 (compatible; Perplexity-User/1.0)', 'perplexity-user'],
+    ['Mozilla/5.0 (compatible; Google-CloudVertexBot/1.0)', 'google-cloudvertexbot'],
+    ['Mozilla/5.0 (compatible; Applebot-Extended/0.1)', 'applebot-extended'],
+    ['Mozilla/5.0 (compatible; Bytespider; spider-feedback@bytedance.com)', 'bytespider'],
+    ['meta-externalagent/1.1', 'meta-externalagent'],
+    ['CCBot/2.0 (https://commoncrawl.org/faq/)', 'ccbot'],
+  ])('classifies the full user-agent string %s as %s', (ua, expected) => {
+    expect(classifyAiCrawler(ua)).toBe(expected);
+  });
+
+  it.each([
+    ['Googlebot/2.1'],
+    ['Mozilla/5.0 (compatible; Googlebot/2.1; +http://www.google.com/bot.html)'],
+    ['Mozilla/5.0 (compatible; Applebot/0.1; +http://www.apple.com/go/applebot)'],
+    ['Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) AppleWebKit/537.36 Chrome/131.0.0.0 Safari/537.36'],
+    [''],
+    ['   '],
+  ])('returns null for %s', (ua) => {
+    expect(classifyAiCrawler(ua)).toBeNull();
+  });
+
+  it('returns null for non-string input', () => {
+    expect(classifyAiCrawler(null)).toBeNull();
+    expect(classifyAiCrawler(undefined)).toBeNull();
+  });
+});
+
+describe('classifyAiReferrer', () => {
+  it.each([
+    ['https://chatgpt.com/c/abc', 'chatgpt'],
+    ['https://www.perplexity.ai/search?q=x', 'perplexity'],
+    ['https://claude.ai/chat/1', 'claude'],
+    ['https://gemini.google.com/app', 'gemini'],
+    ['https://chat.openai.com/c/1', 'chatgpt'],
+    ['https://copilot.microsoft.com/chats/1', 'copilot'],
+    ['https://you.com/search?q=x', 'you'],
+    ['https://CHATGPT.COM/c/abc', 'chatgpt'],
+  ])('classifies %s as %s', (referrer, expected) => {
+    expect(classifyAiReferrer(referrer)).toBe(expected);
+  });
+
+  it.each([
+    ['https://www.google.com/search?q=x'],
+    [''],
+    ['   '],
+    ['not a url'],
+    ['https://news.ycombinator.com/'],
+  ])('returns null for %s', (referrer) => {
+    expect(classifyAiReferrer(referrer)).toBeNull();
+  });
+
+  it('does not match a lookalike host by substring', () => {
+    expect(classifyAiReferrer('https://evil-chatgpt.com.attacker.net/x')).toBeNull();
+    expect(classifyAiReferrer('https://claude.ai.attacker.net/x')).toBeNull();
+    expect(classifyAiReferrer('https://notclaude.ai/x')).toBeNull();
+    expect(classifyAiReferrer('https://attacker.net/?u=https://chatgpt.com/c/1')).toBeNull();
+  });
+
+  it('matches subdomains of a known AI host', () => {
+    expect(classifyAiReferrer('https://www.chatgpt.com/c/1')).toBe('chatgpt');
+    expect(classifyAiReferrer('https://labs.perplexity.ai/')).toBe('perplexity');
+  });
+
+  it('ignores non-http schemes', () => {
+    expect(classifyAiReferrer('javascript:alert(1)')).toBeNull();
+    expect(classifyAiReferrer('android-app://com.openai.chatgpt')).toBeNull();
+  });
+
+  it('returns null for non-string input', () => {
+    expect(classifyAiReferrer(null)).toBeNull();
+    expect(classifyAiReferrer(undefined)).toBeNull();
+  });
+});
+
+describe('shouldEmitCrawlerEvent', () => {
+  it('emits the first sighting of a crawler/path pair in a bucket', () => {
+    const seen = new Set<string>();
+    expect(shouldEmitCrawlerEvent({ crawler: 'gptbot', path: '/blog/a', now: 0, seen })).toBe(true);
+  });
+
+  it('suppresses a repeat sighting of the same crawler/path within the same bucket', () => {
+    const seen = new Set<string>();
+    shouldEmitCrawlerEvent({ crawler: 'gptbot', path: '/blog/a', now: 0, seen });
+    expect(shouldEmitCrawlerEvent({ crawler: 'gptbot', path: '/blog/a', now: 60_000, seen })).toBe(false);
+  });
+
+  it('re-emits once the bucket rolls over', () => {
+    const seen = new Set<string>();
+    shouldEmitCrawlerEvent({ crawler: 'gptbot', path: '/blog/a', now: 0, seen });
+    expect(shouldEmitCrawlerEvent({ crawler: 'gptbot', path: '/blog/a', now: 3_600_000, seen })).toBe(true);
+  });
+
+  it('tracks distinct paths and distinct crawlers separately', () => {
+    const seen = new Set<string>();
+    expect(shouldEmitCrawlerEvent({ crawler: 'gptbot', path: '/a', now: 0, seen })).toBe(true);
+    expect(shouldEmitCrawlerEvent({ crawler: 'gptbot', path: '/b', now: 0, seen })).toBe(true);
+    expect(shouldEmitCrawlerEvent({ crawler: 'claudebot', path: '/a', now: 0, seen })).toBe(true);
+  });
+
+  it('bounds memory by clearing the set when it grows past the cap', () => {
+    const seen = new Set<string>();
+    for (let i = 0; i < 2100; i++) {
+      shouldEmitCrawlerEvent({ crawler: 'gptbot', path: `/p/${i}`, now: 0, seen });
+    }
+    expect(seen.size).toBeLessThanOrEqual(2000);
+  });
+});
diff --git a/apps/website/src/lib/analytics/ai-traffic.ts b/apps/website/src/lib/analytics/ai-traffic.ts
new file mode 100644
index 000000000..5f2745b58
--- /dev/null
+++ b/apps/website/src/lib/analytics/ai-traffic.ts
@@ -0,0 +1,142 @@
+// SPDX-License-Identifier: MIT
+/**
+ * Pure classification helpers for AI crawler traffic and AI-engine referrals.
+ *
+ * Deliberately dependency-free and free of any Next.js / Node imports so it can
+ * run unchanged in middleware (Edge or Node runtime) and be unit-tested directly.
+ *
+ * Google Search Console's Generative AI report is UI-only — there is no API for
+ * AI Overviews / AI Mode impressions — and AI crawlers never execute JavaScript,
+ * so the client-side PostHog snippet cannot see them. Edge middleware is the only
+ * place we can observe either signal.
+ */
+
+/**
+ * User-agent tokens published by AI crawlers, mapped to the stable slug we report.
+ *
+ * Matched case-insensitively as substrings of the full UA string. Tokens are
+ * chosen to be specific enough that non-AI crawlers do not collide: plain
+ * `Googlebot` and plain `Applebot` are classic search crawlers and must NOT be
+ * classified here — only their AI-training variants (`Google-Extended`,
+ * `Applebot-Extended`) count.
+ */
+const AI_CRAWLER_TOKENS = [
+  // OpenAI
+  'GPTBot',
+  'OAI-SearchBot',
+  'ChatGPT-User',
+  // Anthropic
+  'ClaudeBot',
+  'Claude-Web',
+  'anthropic-ai',
+  // Perplexity
+  'PerplexityBot',
+  'Perplexity-User',
+  // Google (AI-specific variants only)
+  'Google-Extended',
+  'Google-CloudVertexBot',
+  // Apple (AI-training variant only)
+  'Applebot-Extended',
+  // ByteDance / Meta / Common Crawl
+  'Bytespider',
+  'Meta-ExternalAgent',
+  'CCBot',
+] as const;
+
+/**
+ * Longest token first so a shorter token can never shadow a more specific one
+ * (e.g. a hypothetical `Claude` before `Claude-Web`).
+ */
+const CRAWLER_MATCHERS: ReadonlyArray<{ needle: string; slug: string }> = [...AI_CRAWLER_TOKENS]
+  .sort((a, b) => b.length - a.length)
+  .map((token) => ({ needle: token.toLowerCase(), slug: token.toLowerCase() }));
+
+/**
+ * Registered hostnames of AI answer engines, mapped to the stable source slug.
+ *
+ * Matched on the *parsed hostname*, exactly or as a subdomain — never as a naive
+ * substring, so `evil-chatgpt.com.attacker.net` and `claude.ai.attacker.net` do
+ * not classify.
+ */
+const AI_REFERRER_HOSTS: ReadonlyArray<{ host: string; slug: string }> = [
+  { host: 'chatgpt.com', slug: 'chatgpt' },
+  { host: 'chat.openai.com', slug: 'chatgpt' },
+  { host: 'perplexity.ai', slug: 'perplexity' },
+  { host: 'claude.ai', slug: 'claude' },
+  { host: 'gemini.google.com', slug: 'gemini' },
+  { host: 'copilot.microsoft.com', slug: 'copilot' },
+  { host: 'you.com', slug: 'you' },
+];
+
+/** Identify an AI crawler from a raw User-Agent header. Returns a stable slug or null. */
+export function classifyAiCrawler(userAgent: string | null | undefined): string | null {
+  if (typeof userAgent !== 'string') return null;
+  const ua = userAgent.trim().toLowerCase();
+  if (!ua) return null;
+
+  for (const { needle, slug } of CRAWLER_MATCHERS) {
+    if (ua.includes(needle)) return slug;
+  }
+  return null;
+}
+
+/** Identify an AI answer engine from a raw Referer header. Returns a stable slug or null. */
+export function classifyAiReferrer(referrer: string | null | undefined): string | null {
+  if (typeof referrer !== 'string') return null;
+  const value = referrer.trim();
+  if (!value) return null;
+
+  let hostname: string;
+  try {
+    const url = new URL(value);
+    if (url.protocol !== 'http:' && url.protocol !== 'https:') return null;
+    hostname = url.hostname.toLowerCase().replace(/\.$/, '');
+  } catch {
+    return null;
+  }
+  if (!hostname) return null;
+
+  for (const { host, slug } of AI_REFERRER_HOSTS) {
+    if (hostname === host || hostname.endsWith(`.${host}`)) return slug;
+  }
+  return null;
+}
+
+/** One event per crawler/path per hour. */
+const CRAWLER_BUCKET_MS = 60 * 60 * 1000;
+
+/**
+ * Cap on remembered keys. Reached only by a crawler sweeping thousands of
+ * distinct URLs in one hour on one instance; clearing then just re-opens the
+ * window, which is the safe direction (over-report, never leak memory).
+ */
+const CRAWLER_SEEN_MAX = 2000;
+
+/**
+ * Best-effort, per-instance dedup so a crawler looping a single URL cannot turn
+ * into an unbounded PostHog firehose. The sitemap is 141 URLs against ~14 known
+ * crawlers, so the ceiling this imposes is ~2k events/hour worst case and, in
+ * practice, a few hundred a day.
+ *
+ * Serverless instances are short-lived and horizontally scaled, so this
+ * deliberately does NOT guarantee exactly-once — it trims the tail. Under-count
+ * is acceptable for a "who is reading us" signal; a hung request is not.
+ */
+export function shouldEmitCrawlerEvent({
+  crawler,
+  path,
+  now,
+  seen,
+}: {
+  crawler: string;
+  path: string;
+  now: number;
+  seen: Set<string>;
+}): boolean {
+  const bucket = Math.floor(now / CRAWLER_BUCKET_MS);
+  const key = `${bucket}|${crawler}|${path}`;
+  if (seen.has(key)) return false;
+  if (seen.size >= CRAWLER_SEEN_MAX) seen.clear();
+  seen.add(key);
+  return true;
+}
diff --git a/apps/website/src/lib/analytics/events.ts b/apps/website/src/lib/analytics/events.ts
index d678b2b25..26621fde9 100644
--- a/apps/website/src/lib/analytics/events.ts
+++ b/apps/website/src/lib/analytics/events.ts
@@ -20,6 +20,8 @@ export const analyticsEvents = {
   docsSidebarSectionToggle: 'docs:sidebar_section_toggle',
   blogCtaClick: 'blog:cta_click',
   blogCopyCodeClick: 'blog:copy_code_click',
+  marketingAiCrawlerVisit: 'marketing:ai_crawler_visit',
+  marketingAiReferralVisit: 'marketing:ai_referral_visit',
   marketingCheckoutStarted: 'marketing:checkout_started',
   marketingCheckoutSucceeded: 'marketing:checkout_succeeded',
 } as const;
@@ -106,5 +108,8 @@ export type AnalyticsProperties = {
   result_count?: number;
   query_length?: number;
   error_reason?: string;
+  ai_crawler?: string;
+  ai_source?: string;
+  user_agent?: string;
   [key: string]: string | number | boolean | undefined;
 };
diff --git a/apps/website/src/middleware.spec.ts b/apps/website/src/middleware.spec.ts
new file mode 100644
index 000000000..da58ee843
--- /dev/null
+++ b/apps/website/src/middleware.spec.ts
@@ -0,0 +1,104 @@
+// SPDX-License-Identifier: MIT
+import { describe, expect, it } from 'vitest';
+import { classifyRequest, config } from './middleware';
+
+const MATCHER = new RegExp(`^${config.matcher[0]}$`);
+const matches = (path: string) => MATCHER.test(path);
+
+describe('middleware matcher', () => {
+  it.each(['/', '/blog/x', '/docs/chat/overview', '/about', '/llms', '/opengraph'])('matches HTML route %s', (p) => {
+    expect(matches(p)).toBe(true);
+  });
+
+  it.each([
+    '/api/leads',
+    '/api/checkout/session',
+    '/_next/static/chunk.js',
+    '/_next/image',
+    '/ingest/e',
+    '/ingest/static/array.js',
+    '/favicon.ico',
+    '/sitemap.xml',
+    '/robots.txt',
+    '/llms.txt',
+    '/opengraph-image',
+    '/blog/my-post/opengraph-image',
+    '/twitter-image',
+    '/whitepapers/overview.pdf',
+  ])('excludes %s', (p) => {
+    expect(matches(p)).toBe(false);
+  });
+});
+
+describe('classifyRequest', () => {
+  const base = { path: '/blog/a', now: 0 };
+
+  it('captures an AI crawler visit with the path but no query string', () => {
+    const capture = classifyRequest({
+      ...base,
+      userAgent: 'Mozilla/5.0 (compatible; GPTBot/1.2; +https://openai.com/gptbot)',
+      referrer: null,
+      seen: new Set(),
+    });
+    expect(capture).toEqual({
+      event: 'marketing:ai_crawler_visit',
+      distinctId: 'ai_crawler:gptbot',
+      properties: {
+        ai_crawler: 'gptbot',
+        source_page: '/blog/a',
+        user_agent: 'Mozilla/5.0 (compatible; GPTBot/1.2; +https://openai.com/gptbot)',
+      },
+    });
+  });
+
+  it('captures an AI referral visit without the user agent or referrer url', () => {
+    const capture = classifyRequest({
+      ...base,
+      userAgent: 'Mozilla/5.0 (Macintosh) Chrome/131.0.0.0 Safari/537.36',
+      referrer: 'https://www.perplexity.ai/search?q=angular+agent',
+      seen: new Set(),
+    });
+    expect(capture).toEqual({
+      event: 'marketing:ai_referral_visit',
+      distinctId: 'ai_referral:perplexity',
+      properties: { ai_source: 'perplexity', source_page: '/blog/a' },
+    });
+  });
+
+  it('prefers the crawler classification when both match', () => {
+    const capture = classifyRequest({
+      ...base,
+      userAgent: 'ClaudeBot/1.0',
+      referrer: 'https://claude.ai/chat/1',
+      seen: new Set(),
+    });
+    expect(capture?.event).toBe('marketing:ai_crawler_visit');
+  });
+
+  it('returns null for ordinary human traffic', () => {
+    expect(
+      classifyRequest({
+        ...base,
+        userAgent: 'Mozilla/5.0 (Macintosh) Chrome/131.0.0.0 Safari/537.36',
+        referrer: 'https://www.google.com/search?q=x',
+        seen: new Set(),
+      }),
+    ).toBeNull();
+  });
+
+  it('returns null for a repeat crawler hit on the same path in the same hour', () => {
+    const seen = new Set<string>();
+    expect(classifyRequest({ ...base, userAgent: 'GPTBot/1.2', referrer: null, seen })).not.toBeNull();
+    expect(classifyRequest({ ...base, userAgent: 'GPTBot/1.2', referrer: null, seen })).toBeNull();
+  });
+
+  it('truncates an abusive user-agent string', () => {
+    const capture = classifyRequest({
+      ...base,
+      userAgent: `GPTBot/1.2 ${'x'.repeat(5000)}`,
+      referrer: null,
+      seen: new Set(),
+    });
+    expect((capture?.properties.user_agent as string).length).toBe(200);
+  });
+});
diff --git a/apps/website/src/middleware.ts b/apps/website/src/middleware.ts
new file mode 100644
index 000000000..69486d70a
--- /dev/null
+++ b/apps/website/src/middleware.ts
@@ -0,0 +1,161 @@
+// SPDX-License-Identifier: MIT
+import { NextResponse, type NextFetchEvent, type NextRequest } from 'next/server';
+import { normalizePostHogHost, toSafeAnalyticsString } from '@threadplane/telemetry/shared';
+import { analyticsEvents, type AnalyticsEventName, type AnalyticsProperties } from './lib/analytics/events';
+import { classifyAiCrawler, classifyAiReferrer, shouldEmitCrawlerEvent } from './lib/analytics/ai-traffic';
+
+/**
+ * Observe AI crawlers and AI-answer-engine referrals.
+ *
+ * Google Search Console's Generative AI report has no API, and AI crawlers never
+ * run JavaScript — so `instrumentation-client.ts` cannot see either signal. This
+ * middleware is the only place we can.
+ *
+ * Deliberately written against Web-standard APIs only (`fetch`, `NextRequest`,
+ * `FetchEvent#waitUntil`) so it behaves identically whether Next runs middleware
+ * on the Edge or Node.js runtime. `posthog-node` is intentionally NOT used here:
+ * it is a Node library, and the Edge bundle is size-constrained.
+ *
+ * Capture goes DIRECT to the PostHog ingest host, not through the `/ingest/*`
+ * rewrites in `next.config.ts`. Those exist so ad-blockers cannot intercept the
+ * browser snippet; routing a server-side capture through them would just make the
+ * deployment issue an HTTP request to itself.
+ */
+
+/** Best-effort, per-instance dedup state. See `shouldEmitCrawlerEvent`. */
+const seenCrawlerKeys = new Set<string>();
+
+function isLocalAnalyticsHost(hostname: string): boolean {
+  return hostname === 'localhost' || hostname === '127.0.0.1' || hostname === '::1' || hostname === '[::1]';
+}
+
+type PendingCapture = {
+  event: AnalyticsEventName;
+  distinctId: string;
+  properties: AnalyticsProperties;
+};
+
+/**
+ * Classify the request. Returns the event to capture, or null when this is
+ * ordinary human traffic (the overwhelmingly common case — keep it cheap).
+ */
+export function classifyRequest({
+  userAgent,
+  referrer,
+  path,
+  now,
+  seen,
+}: {
+  userAgent: string | null;
+  referrer: string | null;
+  path: string;
+  now: number;
+  seen: Set<string>;
+}): PendingCapture | null {
+  const crawler = classifyAiCrawler(userAgent);
+  if (crawler) {
+    // A crawler that also carries a referrer is still a crawler — never both.
+    if (!shouldEmitCrawlerEvent({ crawler, path, now, seen })) return null;
+    return {
+      event: analyticsEvents.marketingAiCrawlerVisit,
+      distinctId: `ai_crawler:${crawler}`,
+      properties: {
+        ai_crawler: crawler,
+        source_page: path,
+        // Crawler UAs are machine identities, not personal data, and the version
+        // suffix is the useful part. Truncated for cardinality safety.
+        user_agent: toSafeAnalyticsString(userAgent, 200),
+      },
+    };
+  }
+
+  const source = classifyAiReferrer(referrer);
+  if (source) {
+    return {
+      event: analyticsEvents.marketingAiReferralVisit,
+      distinctId: `ai_referral:${source}`,
+      // No user_agent, no referrer URL, no query string: this is a human.
+      properties: { ai_source: source, source_page: path },
+    };
+  }
+
+  return null;
+}
+
+async function sendToPostHog(capture: PendingCapture): Promise<void> {
+  const token = toSafeAnalyticsString(process.env.NEXT_PUBLIC_POSTHOG_TOKEN, 500);
+  if (!token) return;
+
+  const host = normalizePostHogHost(process.env.NEXT_PUBLIC_POSTHOG_HOST);
+  try {
+    await fetch(`${host}/i/v0/e/`, {
+      method: 'POST',
+      headers: { 'content-type': 'application/json' },
+      body: JSON.stringify({
+        api_key: token,
+        event: capture.event,
+        distinct_id: capture.distinctId,
+        timestamp: new Date().toISOString(),
+        properties: {
+          ...capture.properties,
+          // Anonymous by construction: no person profile is created or updated,
+          // and `$ip: null` tells PostHog to skip GeoIP enrichment rather than
+          // geolocating our own edge node.
+          $process_person_profile: false,
+          $ip: null,
+          $lib: 'threadplane-website-middleware',
+        },
+      }),
+      // A dropped analytics event is acceptable; a hung request is not.
+      signal: AbortSignal.timeout(2000),
+      keepalive: true,
+    });
+  } catch {
+    // Swallow. Analytics must never surface to a visitor.
+  }
+}
+
+export function middleware(request: NextRequest, event: NextFetchEvent) {
+  const response = NextResponse.next();
+
+  try {
+    if (
+      process.env.NEXT_PUBLIC_POSTHOG_TOKEN &&
+      (process.env.NEXT_PUBLIC_POSTHOG_CAPTURE_LOCAL === 'true' || !isLocalAnalyticsHost(request.nextUrl.hostname))
+    ) {
+      const capture = classifyRequest({
+        userAgent: request.headers.get('user-agent'),
+        referrer: request.headers.get('referer'),
+        // `pathname` only — never the query string, which can carry search terms.
+        path: request.nextUrl.pathname,
+        now: Date.now(),
+        seen: seenCrawlerKeys,
+      });
+
+      // Fire-and-forget, but registered with the platform so the runtime keeps the
+      // invocation alive past the response instead of killing the promise.
+      if (capture) event.waitUntil(sendToPostHog(capture));
+    }
+  } catch {
+    // Never let instrumentation break a page render.
+  }
+
+  return response;
+}
+
+/**
+ * HTML routes only.
+ *
+ * Excluded, and why:
+ * - `api`            — no HTML, and lead/checkout routes already capture server-side.
+ * - `_next/static`, `_next/image` — build assets.
+ * - `ingest`         — the PostHog proxy rewrites in `next.config.ts`; matching them
+ *                      would put middleware in front of our own analytics traffic.
+ * - `favicon.ico`, and any final segment containing a `.` — static files, plus
+ *   `sitemap.xml`, `robots.txt`, `llms.txt`. (Trade-off: we therefore do not see
+ *   crawler hits on `llms.txt`; server logs remain the source for those.)
+ * - `opengraph-image` / `twitter-image` — prerendered PNG routes with no extension.
+ */
+export const config = {
+  matcher: ['/((?!api|_next/static|_next/image|ingest|favicon.ico|.*opengraph-image|.*twitter-image|.*\\.[^/]*$).*)'],
+};
diff --git a/docs/gtm/taxonomy.md b/docs/gtm/taxonomy.md
index add0134bc..8560f5830 100644
--- a/docs/gtm/taxonomy.md
+++ b/docs/gtm/taxonomy.md
@@ -40,6 +40,8 @@ The standard PostHog `$pageview` event is used as-is across all three surfaces.
 | `marketing:newsletter_signup_submit`  | Submit attempt                                                                                |
 | `marketing:newsletter_signup_success` | Server 2xx                                                                                    |
 | `marketing:newsletter_signup_fail`    | Failure                                                                                       |
+| `marketing:ai_crawler_visit`          | Edge middleware saw a known AI crawler UA on an HTML route. Props: `ai_crawler`, `source_page`, `user_agent`. Deduped per crawler/path/hour. |
+| `marketing:ai_referral_visit`         | Edge middleware saw a referrer from an AI answer engine. Props: `ai_source`, `source_page`. Anonymous (no person profile). |
 | `docs:search_submit`                  | Docs search invocation                                                                        |
 | `docs:search_result_click`            | Result click                                                                                  |
 | `docs:copy_prompt_click`              | Prompt-copy button                                                                            |

From 3413824f5188b302609e53da3a06d7b703043902 Mon Sep 17 00:00:00 2001
From: Brian Love <brian@liveloveapp.com>
Date: Thu, 20 Aug 2026 15:34:57 -0700
Subject: [PATCH 29/35] fix(website): bound ai-traffic event volume and cover
 the capture payload
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Both inputs to this feature are attacker-controlled, and the per-key dedup
was not an abuse ceiling: varying the path defeats it entirely, and the
referral path had no limiter at all. Demonstrated live — 700 requests with
a spoofed chatgpt.com Referer produced 700 events. Anyone reading the
bundle could bill the PostHog account arbitrarily or poison the dataset
this feature exists to produce.

- Add a per-instance token bucket on TOTAL emissions (500/hour, burst 500),
  so the blast radius is bounded regardless of key variety. Chosen well
  above honest volume: 141 sitemap URLs, and a simultaneous full-site sweep
  by three crawlers landing on one instance is ~423. Per-instance and
  best-effort like the dedup: it bounds blast radius, it is not a global
  quota.
- Cover sendToPostHog, where every privacy invariant lives. Asserts the
  exact wire payload for both event types: $process_person_profile false,
  $ip null, no query string, no referrer URL, no UA on referral events,
  and that a caller cannot override the anonymous properties.
- Observe /llms.txt, /llms-full.txt, /sitemap.xml and /robots.txt. These
  are the file written for AI consumers and the strongest crawler-intent
  signals that exist; losing them to the blunt extension rule undercut the
  feature's own premise.
- Anchor the og/twitter-image exclusion to a segment boundary, so a page
  named /my-opengraph-image-guide is no longer silently dropped.
- Rename middleware.ts to proxy.ts (Next 16 deprecates the middleware file
  convention). NextProxy is NextMiddleware, so waitUntil is unchanged. This
  moves the runtime from edge to nodejs, re-verified below.
- Dedup key is now JSON.stringify([bucket, crawler, path]): a path may
  legitimately contain any delimiter, and a collision silently drops an
  event. Drop keepalive (a browser-unload primitive; waitUntil is what
  holds the invocation). Drop the unreachable '[::1]' branch.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
---
 .../src/lib/analytics/ai-traffic.spec.ts      |  58 ++-
 apps/website/src/lib/analytics/ai-traffic.ts  |  66 +++-
 apps/website/src/middleware.spec.ts           | 104 ------
 apps/website/src/proxy.spec.ts                | 341 ++++++++++++++++++
 apps/website/src/{middleware.ts => proxy.ts}  | 105 ++++--
 docs/gtm/taxonomy.md                          |   4 +-
 6 files changed, 530 insertions(+), 148 deletions(-)
 delete mode 100644 apps/website/src/middleware.spec.ts
 create mode 100644 apps/website/src/proxy.spec.ts
 rename apps/website/src/{middleware.ts => proxy.ts} (58%)

diff --git a/apps/website/src/lib/analytics/ai-traffic.spec.ts b/apps/website/src/lib/analytics/ai-traffic.spec.ts
index 82465087f..a02ac9897 100644
--- a/apps/website/src/lib/analytics/ai-traffic.spec.ts
+++ b/apps/website/src/lib/analytics/ai-traffic.spec.ts
@@ -1,6 +1,13 @@
 // SPDX-License-Identifier: MIT
 import { describe, expect, it } from 'vitest';
-import { classifyAiCrawler, classifyAiReferrer, shouldEmitCrawlerEvent } from './ai-traffic';
+import {
+  classifyAiCrawler,
+  classifyAiReferrer,
+  createEmissionBudget,
+  EMISSION_BUCKET_CAPACITY,
+  shouldEmitCrawlerEvent,
+  takeEmissionToken,
+} from './ai-traffic';
 
 describe('classifyAiCrawler', () => {
   it.each([
@@ -124,4 +131,53 @@ describe('shouldEmitCrawlerEvent', () => {
     }
     expect(seen.size).toBeLessThanOrEqual(2000);
   });
+
+  it('does not confuse two keys that would collide under a delimiter-joined key', () => {
+    const seen = new Set<string>();
+    // Under `${bucket}|${crawler}|${path}` these two produce the same string.
+    expect(shouldEmitCrawlerEvent({ crawler: 'a|b', path: '/c', now: 0, seen })).toBe(true);
+    expect(shouldEmitCrawlerEvent({ crawler: 'a', path: 'b|/c', now: 0, seen })).toBe(true);
+  });
+});
+
+describe('takeEmissionToken', () => {
+  it('allows exactly the bucket capacity before throttling', () => {
+    const budget = createEmissionBudget(0);
+    let allowed = 0;
+    for (let i = 0; i < EMISSION_BUCKET_CAPACITY * 3; i++) {
+      if (takeEmissionToken(budget, 0)) allowed++;
+    }
+    expect(allowed).toBe(EMISSION_BUCKET_CAPACITY);
+  });
+
+  it('refills linearly with elapsed time', () => {
+    const budget = createEmissionBudget(0);
+    while (takeEmissionToken(budget, 0)) {
+      /* drain */
+    }
+    // Half an hour buys back half the capacity.
+    const halfHour = 30 * 60 * 1000;
+    let allowed = 0;
+    for (let i = 0; i < EMISSION_BUCKET_CAPACITY; i++) {
+      if (takeEmissionToken(budget, halfHour)) allowed++;
+    }
+    expect(allowed).toBe(EMISSION_BUCKET_CAPACITY / 2);
+  });
+
+  it('never accumulates more than the capacity while idle', () => {
+    const budget = createEmissionBudget(0);
+    takeEmissionToken(budget, 0);
+    let allowed = 0;
+    const aWeek = 7 * 24 * 60 * 60 * 1000;
+    for (let i = 0; i < EMISSION_BUCKET_CAPACITY * 2; i++) {
+      if (takeEmissionToken(budget, aWeek)) allowed++;
+    }
+    expect(allowed).toBe(EMISSION_BUCKET_CAPACITY);
+  });
+
+  it('is monotonic-safe if the clock goes backwards', () => {
+    const budget = createEmissionBudget(1_000_000);
+    expect(takeEmissionToken(budget, 0)).toBe(true);
+    expect(budget.tokens).toBeLessThanOrEqual(EMISSION_BUCKET_CAPACITY);
+  });
 });
diff --git a/apps/website/src/lib/analytics/ai-traffic.ts b/apps/website/src/lib/analytics/ai-traffic.ts
index 5f2745b58..b74a3858f 100644
--- a/apps/website/src/lib/analytics/ai-traffic.ts
+++ b/apps/website/src/lib/analytics/ai-traffic.ts
@@ -102,7 +102,12 @@ export function classifyAiReferrer(referrer: string | null | undefined): string
   return null;
 }
 
-/** One event per crawler/path per hour. */
+/**
+ * Dedup window length. Buckets are fixed wall-clock slices, not a sliding
+ * window, so a hit at 10:59 and another at 11:01 both emit. That is fine for a
+ * "who is reading us" signal — the guarantee is "at most a handful per
+ * crawler/path per hour", not "exactly one".
+ */
 const CRAWLER_BUCKET_MS = 60 * 60 * 1000;
 
 /**
@@ -114,13 +119,15 @@ const CRAWLER_SEEN_MAX = 2000;
 
 /**
  * Best-effort, per-instance dedup so a crawler looping a single URL cannot turn
- * into an unbounded PostHog firehose. The sitemap is 141 URLs against ~14 known
- * crawlers, so the ceiling this imposes is ~2k events/hour worst case and, in
- * practice, a few hundred a day.
+ * into a PostHog firehose.
+ *
+ * This alone is NOT an abuse ceiling: it is keyed on crawler+path, so varying
+ * the path defeats it entirely. `takeEmissionToken` is the actual bound; this
+ * just removes the most common source of pointless duplicates.
  *
  * Serverless instances are short-lived and horizontally scaled, so this
- * deliberately does NOT guarantee exactly-once — it trims the tail. Under-count
- * is acceptable for a "who is reading us" signal; a hung request is not.
+ * deliberately does NOT guarantee exactly-once across the fleet — it trims the
+ * tail. Under-count is acceptable for this signal; a hung request is not.
  */
 export function shouldEmitCrawlerEvent({
   crawler,
@@ -134,9 +141,54 @@ export function shouldEmitCrawlerEvent({
   seen: Set<string>;
 }): boolean {
   const bucket = Math.floor(now / CRAWLER_BUCKET_MS);
-  const key = `${bucket}|${crawler}|${path}`;
+  // JSON encoding, not string concatenation: a path may legitimately contain
+  // any delimiter we might pick, and a collision would silently drop an event.
+  const key = JSON.stringify([bucket, crawler, path]);
   if (seen.has(key)) return false;
   if (seen.size >= CRAWLER_SEEN_MAX) seen.clear();
   seen.add(key);
   return true;
 }
+
+/**
+ * Hard ceiling on TOTAL events emitted by one instance, across every event type
+ * and regardless of key variety.
+ *
+ * Why a total-emission bucket and not just the per-key dedup: both inputs to
+ * this feature are attacker-controlled. Anyone can send `Referer:
+ * https://chatgpt.com/...` or a `GPTBot` UA against an unlimited number of
+ * distinct paths, and without this they could bill the PostHog account
+ * arbitrarily or poison the very dataset the feature exists to produce.
+ *
+ * 500/hour is far above any honest volume: the sitemap is 141 URLs, the dedup
+ * already collapses repeats, and a simultaneous full-site sweep by three
+ * different crawlers landing entirely on one instance is ~423 events. Real
+ * traffic spreads across instances, so the honest path never reaches this.
+ * The burst capacity equals the hourly rate, so a legitimate fast sweep is not
+ * throttled partway through.
+ *
+ * Per-instance and therefore best-effort, exactly like the dedup: N instances
+ * means the fleet-wide ceiling is N x 500. It bounds the blast radius; it is not
+ * a global quota.
+ */
+export const EMISSION_BUCKET_CAPACITY = 500;
+const EMISSION_REFILL_PER_MS = EMISSION_BUCKET_CAPACITY / (60 * 60 * 1000);
+
+export type EmissionBudget = { tokens: number; updatedAt: number };
+
+export function createEmissionBudget(now = 0): EmissionBudget {
+  return { tokens: EMISSION_BUCKET_CAPACITY, updatedAt: now };
+}
+
+/**
+ * Classic token bucket with lazy refill. Returns false once the instance has
+ * spent its budget; callers must then drop the event rather than queue it.
+ */
+export function takeEmissionToken(budget: EmissionBudget, now: number): boolean {
+  const elapsed = Math.max(0, now - budget.updatedAt);
+  budget.tokens = Math.min(EMISSION_BUCKET_CAPACITY, budget.tokens + elapsed * EMISSION_REFILL_PER_MS);
+  budget.updatedAt = now;
+  if (budget.tokens < 1) return false;
+  budget.tokens -= 1;
+  return true;
+}
diff --git a/apps/website/src/middleware.spec.ts b/apps/website/src/middleware.spec.ts
deleted file mode 100644
index da58ee843..000000000
--- a/apps/website/src/middleware.spec.ts
+++ /dev/null
@@ -1,104 +0,0 @@
-// SPDX-License-Identifier: MIT
-import { describe, expect, it } from 'vitest';
-import { classifyRequest, config } from './middleware';
-
-const MATCHER = new RegExp(`^${config.matcher[0]}$`);
-const matches = (path: string) => MATCHER.test(path);
-
-describe('middleware matcher', () => {
-  it.each(['/', '/blog/x', '/docs/chat/overview', '/about', '/llms', '/opengraph'])('matches HTML route %s', (p) => {
-    expect(matches(p)).toBe(true);
-  });
-
-  it.each([
-    '/api/leads',
-    '/api/checkout/session',
-    '/_next/static/chunk.js',
-    '/_next/image',
-    '/ingest/e',
-    '/ingest/static/array.js',
-    '/favicon.ico',
-    '/sitemap.xml',
-    '/robots.txt',
-    '/llms.txt',
-    '/opengraph-image',
-    '/blog/my-post/opengraph-image',
-    '/twitter-image',
-    '/whitepapers/overview.pdf',
-  ])('excludes %s', (p) => {
-    expect(matches(p)).toBe(false);
-  });
-});
-
-describe('classifyRequest', () => {
-  const base = { path: '/blog/a', now: 0 };
-
-  it('captures an AI crawler visit with the path but no query string', () => {
-    const capture = classifyRequest({
-      ...base,
-      userAgent: 'Mozilla/5.0 (compatible; GPTBot/1.2; +https://openai.com/gptbot)',
-      referrer: null,
-      seen: new Set(),
-    });
-    expect(capture).toEqual({
-      event: 'marketing:ai_crawler_visit',
-      distinctId: 'ai_crawler:gptbot',
-      properties: {
-        ai_crawler: 'gptbot',
-        source_page: '/blog/a',
-        user_agent: 'Mozilla/5.0 (compatible; GPTBot/1.2; +https://openai.com/gptbot)',
-      },
-    });
-  });
-
-  it('captures an AI referral visit without the user agent or referrer url', () => {
-    const capture = classifyRequest({
-      ...base,
-      userAgent: 'Mozilla/5.0 (Macintosh) Chrome/131.0.0.0 Safari/537.36',
-      referrer: 'https://www.perplexity.ai/search?q=angular+agent',
-      seen: new Set(),
-    });
-    expect(capture).toEqual({
-      event: 'marketing:ai_referral_visit',
-      distinctId: 'ai_referral:perplexity',
-      properties: { ai_source: 'perplexity', source_page: '/blog/a' },
-    });
-  });
-
-  it('prefers the crawler classification when both match', () => {
-    const capture = classifyRequest({
-      ...base,
-      userAgent: 'ClaudeBot/1.0',
-      referrer: 'https://claude.ai/chat/1',
-      seen: new Set(),
-    });
-    expect(capture?.event).toBe('marketing:ai_crawler_visit');
-  });
-
-  it('returns null for ordinary human traffic', () => {
-    expect(
-      classifyRequest({
-        ...base,
-        userAgent: 'Mozilla/5.0 (Macintosh) Chrome/131.0.0.0 Safari/537.36',
-        referrer: 'https://www.google.com/search?q=x',
-        seen: new Set(),
-      }),
-    ).toBeNull();
-  });
-
-  it('returns null for a repeat crawler hit on the same path in the same hour', () => {
-    const seen = new Set<string>();
-    expect(classifyRequest({ ...base, userAgent: 'GPTBot/1.2', referrer: null, seen })).not.toBeNull();
-    expect(classifyRequest({ ...base, userAgent: 'GPTBot/1.2', referrer: null, seen })).toBeNull();
-  });
-
-  it('truncates an abusive user-agent string', () => {
-    const capture = classifyRequest({
-      ...base,
-      userAgent: `GPTBot/1.2 ${'x'.repeat(5000)}`,
-      referrer: null,
-      seen: new Set(),
-    });
-    expect((capture?.properties.user_agent as string).length).toBe(200);
-  });
-});
diff --git a/apps/website/src/proxy.spec.ts b/apps/website/src/proxy.spec.ts
new file mode 100644
index 000000000..2725b00aa
--- /dev/null
+++ b/apps/website/src/proxy.spec.ts
@@ -0,0 +1,341 @@
+// SPDX-License-Identifier: MIT
+import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest';
+import { buildCapturePayload, classifyRequest, config, sendToPostHog } from './proxy';
+import { createEmissionBudget, EMISSION_BUCKET_CAPACITY } from './lib/analytics/ai-traffic';
+
+const MATCHERS = config.matcher.map((m) => new RegExp(`^${m}$`));
+const matches = (path: string) => MATCHERS.some((re) => re.test(path));
+
+const budget = () => createEmissionBudget(0);
+
+describe('proxy matcher', () => {
+  it.each([
+    '/',
+    '/blog/x',
+    '/docs/chat/overview',
+    '/about',
+    // Files written for AI consumers / strongest crawler-intent signals.
+    '/llms.txt',
+    '/llms-full.txt',
+    '/sitemap.xml',
+    '/robots.txt',
+    // Anchored exclusion: a page merely *named* after OG images is still observed.
+    '/my-opengraph-image-guide',
+    '/opengraph-image-not-really',
+    '/blog/twitter-image-tips',
+  ])('matches %s', (p) => {
+    expect(matches(p)).toBe(true);
+  });
+
+  it.each([
+    '/api/leads',
+    '/api/checkout/session',
+    '/_next/static/chunk.js',
+    '/_next/image',
+    '/ingest/e',
+    '/ingest/static/array.js',
+    '/favicon.ico',
+    '/opengraph-image',
+    '/blog/my-post/opengraph-image',
+    '/twitter-image',
+    '/whitepapers/overview.pdf',
+    '/some/script.js',
+  ])('excludes %s', (p) => {
+    expect(matches(p)).toBe(false);
+  });
+});
+
+describe('classifyRequest', () => {
+  const base = { path: '/blog/a', now: 0 };
+
+  it('captures an AI crawler visit with the path but no query string', () => {
+    expect(
+      classifyRequest({
+        ...base,
+        userAgent: 'Mozilla/5.0 (compatible; GPTBot/1.2; +https://openai.com/gptbot)',
+        referrer: null,
+        seen: new Set(),
+        budget: budget(),
+      }),
+    ).toEqual({
+      event: 'marketing:ai_crawler_visit',
+      distinctId: 'ai_crawler:gptbot',
+      properties: {
+        ai_crawler: 'gptbot',
+        source_page: '/blog/a',
+        user_agent: 'Mozilla/5.0 (compatible; GPTBot/1.2; +https://openai.com/gptbot)',
+      },
+    });
+  });
+
+  it('captures an AI referral visit without the user agent or referrer url', () => {
+    expect(
+      classifyRequest({
+        ...base,
+        userAgent: 'Mozilla/5.0 (Macintosh) Chrome/131.0.0.0 Safari/537.36',
+        referrer: 'https://www.perplexity.ai/search?q=angular+agent',
+        seen: new Set(),
+        budget: budget(),
+      }),
+    ).toEqual({
+      event: 'marketing:ai_referral_visit',
+      distinctId: 'ai_referral:perplexity',
+      properties: { ai_source: 'perplexity', source_page: '/blog/a' },
+    });
+  });
+
+  it('prefers the crawler classification when both match', () => {
+    const capture = classifyRequest({
+      ...base,
+      userAgent: 'ClaudeBot/1.0',
+      referrer: 'https://claude.ai/chat/1',
+      seen: new Set(),
+      budget: budget(),
+    });
+    expect(capture?.event).toBe('marketing:ai_crawler_visit');
+  });
+
+  it('returns null for ordinary human traffic', () => {
+    expect(
+      classifyRequest({
+        ...base,
+        userAgent: 'Mozilla/5.0 (Macintosh) Chrome/131.0.0.0 Safari/537.36',
+        referrer: 'https://www.google.com/search?q=x',
+        seen: new Set(),
+        budget: budget(),
+      }),
+    ).toBeNull();
+  });
+
+  it('returns null for a repeat crawler hit on the same path in the same hour', () => {
+    const seen = new Set<string>();
+    const b = budget();
+    expect(classifyRequest({ ...base, userAgent: 'GPTBot/1.2', referrer: null, seen, budget: b })).not.toBeNull();
+    expect(classifyRequest({ ...base, userAgent: 'GPTBot/1.2', referrer: null, seen, budget: b })).toBeNull();
+  });
+
+  it('does not spend a token on a deduplicated crawler hit', () => {
+    const seen = new Set<string>();
+    const b = budget();
+    classifyRequest({ ...base, userAgent: 'GPTBot/1.2', referrer: null, seen, budget: b });
+    const afterFirst = b.tokens;
+    classifyRequest({ ...base, userAgent: 'GPTBot/1.2', referrer: null, seen, budget: b });
+    expect(b.tokens).toBe(afterFirst);
+  });
+
+  it('does not spend a token on ordinary human traffic', () => {
+    const b = budget();
+    classifyRequest({
+      ...base,
+      userAgent: 'Mozilla/5.0 (Macintosh) Chrome/131',
+      referrer: null,
+      seen: new Set(),
+      budget: b,
+    });
+    expect(b.tokens).toBe(EMISSION_BUCKET_CAPACITY);
+  });
+
+  it('truncates an abusive user-agent string', () => {
+    const capture = classifyRequest({
+      ...base,
+      userAgent: `GPTBot/1.2 ${'x'.repeat(5000)}`,
+      referrer: null,
+      seen: new Set(),
+      budget: budget(),
+    });
+    expect((capture?.properties.user_agent as string).length).toBe(200);
+  });
+});
+
+describe('emission ceiling (abuse bound)', () => {
+  it('caps a spoofed-referrer flood at the bucket capacity', () => {
+    const b = budget();
+    let emitted = 0;
+    for (let i = 0; i < 5000; i++) {
+      const capture = classifyRequest({
+        path: `/p/${i}`,
+        now: 0,
+        userAgent: 'Mozilla/5.0 (Macintosh) Chrome/131',
+        referrer: `https://chatgpt.com/c/${i}`,
+        seen: new Set(),
+        budget: b,
+      });
+      if (capture) emitted++;
+    }
+    expect(emitted).toBe(EMISSION_BUCKET_CAPACITY);
+  });
+
+  it('caps a crawler-UA flood across varying paths, which dedup alone cannot', () => {
+    const seen = new Set<string>();
+    const b = budget();
+    let emitted = 0;
+    for (let i = 0; i < 5000; i++) {
+      const capture = classifyRequest({
+        path: `/blog/nonexistent-${i}`,
+        now: 0,
+        userAgent: 'GPTBot/1.2',
+        referrer: null,
+        seen,
+        budget: b,
+      });
+      if (capture) emitted++;
+    }
+    expect(emitted).toBe(EMISSION_BUCKET_CAPACITY);
+  });
+
+  it('refills over time so a throttled instance recovers', () => {
+    const b = budget();
+    for (let i = 0; i < 5000; i++) {
+      classifyRequest({
+        path: `/p/${i}`,
+        now: 0,
+        userAgent: 'Mozilla/5.0 Chrome/131',
+        referrer: 'https://claude.ai/chat/1',
+        seen: new Set(),
+        budget: b,
+      });
+    }
+    // Exhausted at t=0; one hour later the bucket is full again.
+    const after = classifyRequest({
+      path: '/p/x',
+      now: 60 * 60 * 1000,
+      userAgent: 'Mozilla/5.0 Chrome/131',
+      referrer: 'https://claude.ai/chat/1',
+      seen: new Set(),
+      budget: b,
+    });
+    expect(after).not.toBeNull();
+  });
+});
+
+describe('sendToPostHog payload contract', () => {
+  const fetchMock = vi.fn();
+
+  beforeEach(() => {
+    fetchMock.mockReset();
+    fetchMock.mockResolvedValue(new Response('{}', { status: 200 }));
+    vi.stubGlobal('fetch', fetchMock);
+    process.env.NEXT_PUBLIC_POSTHOG_TOKEN = 'phc_test';
+    process.env.NEXT_PUBLIC_POSTHOG_HOST = 'https://us.i.posthog.com';
+  });
+
+  afterEach(() => {
+    vi.unstubAllGlobals();
+  });
+
+  const lastBody = () => JSON.parse(fetchMock.mock.calls[0][1].body as string);
+
+  it('posts a crawler visit to the ingest endpoint with the anonymous property set', async () => {
+    await sendToPostHog({
+      event: 'marketing:ai_crawler_visit',
+      distinctId: 'ai_crawler:gptbot',
+      properties: { ai_crawler: 'gptbot', source_page: '/blog/a', user_agent: 'GPTBot/1.2' },
+    });
+
+    expect(fetchMock).toHaveBeenCalledTimes(1);
+    const [url, init] = fetchMock.mock.calls[0];
+    expect(url).toBe('https://us.i.posthog.com/i/v0/e/');
+    expect(init.method).toBe('POST');
+    expect(init.headers).toEqual({ 'content-type': 'application/json' });
+    expect(init.signal).toBeInstanceOf(AbortSignal);
+    // `keepalive` is a browser-unload primitive; waitUntil is what holds the
+    // invocation open here. Its presence would imply a mechanism that is not
+    // operating.
+    expect(init.keepalive).toBeUndefined();
+
+    const body = lastBody();
+    expect(body.api_key).toBe('phc_test');
+    expect(body.event).toBe('marketing:ai_crawler_visit');
+    expect(body.distinct_id).toBe('ai_crawler:gptbot');
+    expect(body.properties.$process_person_profile).toBe(false);
+    expect(body.properties.$ip).toBeNull();
+    expect(Object.prototype.hasOwnProperty.call(body.properties, '$ip')).toBe(true);
+    expect(body.properties.ai_crawler).toBe('gptbot');
+    expect(body.properties.source_page).toBe('/blog/a');
+  });
+
+  it('posts a referral visit carrying neither the user agent nor the referrer url', async () => {
+    await sendToPostHog({
+      event: 'marketing:ai_referral_visit',
+      distinctId: 'ai_referral:chatgpt',
+      properties: { ai_source: 'chatgpt', source_page: '/pricing' },
+    });
+
+    const body = lastBody();
+    expect(body.properties.$process_person_profile).toBe(false);
+    expect(body.properties.$ip).toBeNull();
+    expect(body.properties.user_agent).toBeUndefined();
+    expect(Object.keys(body.properties).sort()).toEqual([
+      '$ip',
+      '$lib',
+      '$process_person_profile',
+      'ai_source',
+      'source_page',
+    ]);
+  });
+
+  it('never lets a query string or a referrer url reach the wire', async () => {
+    await sendToPostHog({
+      event: 'marketing:ai_referral_visit',
+      distinctId: 'ai_referral:perplexity',
+      // `classifyRequest` only ever supplies a bare pathname; assert the
+      // serializer does not reintroduce anything either.
+      properties: { ai_source: 'perplexity', source_page: '/pricing' },
+    });
+
+    const raw = fetchMock.mock.calls[0][1].body as string;
+    expect(raw).not.toContain('?');
+    expect(raw).not.toContain('perplexity.ai');
+    expect(raw).not.toContain('http://');
+    expect(raw.match(/https:/g)).toBeNull();
+  });
+
+  it('does not fire at all when no PostHog token is configured', async () => {
+    delete process.env.NEXT_PUBLIC_POSTHOG_TOKEN;
+    await sendToPostHog({
+      event: 'marketing:ai_crawler_visit',
+      distinctId: 'ai_crawler:gptbot',
+      properties: { ai_crawler: 'gptbot', source_page: '/' },
+    });
+    expect(fetchMock).not.toHaveBeenCalled();
+  });
+
+  it('swallows a failing capture so it can never surface to a visitor', async () => {
+    fetchMock.mockRejectedValue(new Error('network down'));
+    await expect(
+      sendToPostHog({
+        event: 'marketing:ai_crawler_visit',
+        distinctId: 'ai_crawler:gptbot',
+        properties: { ai_crawler: 'gptbot', source_page: '/' },
+      }),
+    ).resolves.toBeUndefined();
+  });
+
+  it('defaults to the PostHog cloud host when none is configured', async () => {
+    delete process.env.NEXT_PUBLIC_POSTHOG_HOST;
+    await sendToPostHog({
+      event: 'marketing:ai_crawler_visit',
+      distinctId: 'ai_crawler:gptbot',
+      properties: { ai_crawler: 'gptbot', source_page: '/' },
+    });
+    expect(fetchMock.mock.calls[0][0]).toBe('https://us.i.posthog.com/i/v0/e/');
+  });
+});
+
+describe('buildCapturePayload', () => {
+  it('cannot be overridden by a caller-supplied property', () => {
+    const payload = buildCapturePayload(
+      {
+        event: 'marketing:ai_crawler_visit',
+        distinctId: 'ai_crawler:gptbot',
+        // A hostile or careless caller must not be able to re-enable person
+        // processing or GeoIP.
+        properties: { $process_person_profile: true, $ip: '1.2.3.4', source_page: '/' },
+      },
+      'phc_test',
+      '2026-01-01T00:00:00.000Z',
+    );
+    expect(payload.properties.$process_person_profile).toBe(false);
+    expect(payload.properties.$ip).toBeNull();
+  });
+});
diff --git a/apps/website/src/middleware.ts b/apps/website/src/proxy.ts
similarity index 58%
rename from apps/website/src/middleware.ts
rename to apps/website/src/proxy.ts
index 69486d70a..abd2fabc6 100644
--- a/apps/website/src/middleware.ts
+++ b/apps/website/src/proxy.ts
@@ -2,19 +2,26 @@
 import { NextResponse, type NextFetchEvent, type NextRequest } from 'next/server';
 import { normalizePostHogHost, toSafeAnalyticsString } from '@threadplane/telemetry/shared';
 import { analyticsEvents, type AnalyticsEventName, type AnalyticsProperties } from './lib/analytics/events';
-import { classifyAiCrawler, classifyAiReferrer, shouldEmitCrawlerEvent } from './lib/analytics/ai-traffic';
+import {
+  classifyAiCrawler,
+  classifyAiReferrer,
+  createEmissionBudget,
+  shouldEmitCrawlerEvent,
+  takeEmissionToken,
+  type EmissionBudget,
+} from './lib/analytics/ai-traffic';
 
 /**
  * Observe AI crawlers and AI-answer-engine referrals.
  *
  * Google Search Console's Generative AI report has no API, and AI crawlers never
  * run JavaScript — so `instrumentation-client.ts` cannot see either signal. This
- * middleware is the only place we can.
+ * proxy (formerly "middleware") is the only place we can.
  *
- * Deliberately written against Web-standard APIs only (`fetch`, `NextRequest`,
- * `FetchEvent#waitUntil`) so it behaves identically whether Next runs middleware
- * on the Edge or Node.js runtime. `posthog-node` is intentionally NOT used here:
- * it is a Node library, and the Edge bundle is size-constrained.
+ * Written against Web-standard APIs only (`fetch`, `NextRequest`,
+ * `FetchEvent#waitUntil`) so it behaves identically on the Edge and Node.js
+ * runtimes. `posthog-node` is intentionally NOT used: it is a Node library and
+ * this file was Edge-resident until the proxy rename.
  *
  * Capture goes DIRECT to the PostHog ingest host, not through the `/ingest/*`
  * rewrites in `next.config.ts`. Those exist so ad-blockers cannot intercept the
@@ -22,11 +29,13 @@ import { classifyAiCrawler, classifyAiReferrer, shouldEmitCrawlerEvent } from '.
  * deployment issue an HTTP request to itself.
  */
 
-/** Best-effort, per-instance dedup state. See `shouldEmitCrawlerEvent`. */
+/** Best-effort, per-instance dedup + abuse ceiling. See `ai-traffic.ts`. */
 const seenCrawlerKeys = new Set<string>();
+const emissionBudget = createEmissionBudget(Date.now());
 
 function isLocalAnalyticsHost(hostname: string): boolean {
-  return hostname === 'localhost' || hostname === '127.0.0.1' || hostname === '::1' || hostname === '[::1]';
+  // NextUrl#hostname is already unbracketed, so `[::1]` never appears here.
+  return hostname === 'localhost' || hostname === '127.0.0.1' || hostname === '::1';
 }
 
 type PendingCapture = {
@@ -37,7 +46,8 @@ type PendingCapture = {
 
 /**
  * Classify the request. Returns the event to capture, or null when this is
- * ordinary human traffic (the overwhelmingly common case — keep it cheap).
+ * ordinary human traffic (the overwhelmingly common case — keep it cheap) or
+ * when the instance has exhausted its emission budget.
  */
 export function classifyRequest({
   userAgent,
@@ -45,17 +55,20 @@ export function classifyRequest({
   path,
   now,
   seen,
+  budget,
 }: {
   userAgent: string | null;
   referrer: string | null;
   path: string;
   now: number;
   seen: Set<string>;
+  budget: EmissionBudget;
 }): PendingCapture | null {
   const crawler = classifyAiCrawler(userAgent);
   if (crawler) {
     // A crawler that also carries a referrer is still a crawler — never both.
     if (!shouldEmitCrawlerEvent({ crawler, path, now, seen })) return null;
+    if (!takeEmissionToken(budget, now)) return null;
     return {
       event: analyticsEvents.marketingAiCrawlerVisit,
       distinctId: `ai_crawler:${crawler}`,
@@ -71,6 +84,9 @@ export function classifyRequest({
 
   const source = classifyAiReferrer(referrer);
   if (source) {
+    // The referrer header is trivially spoofable by anyone, so this path is the
+    // easiest to flood and gets the same ceiling.
+    if (!takeEmissionToken(budget, now)) return null;
     return {
       event: analyticsEvents.marketingAiReferralVisit,
       distinctId: `ai_referral:${source}`,
@@ -82,7 +98,30 @@ export function classifyRequest({
   return null;
 }
 
-async function sendToPostHog(capture: PendingCapture): Promise<void> {
+/**
+ * The exact wire payload. Split out from `sendToPostHog` so the privacy
+ * invariants — no person profile, no GeoIP, no query string, no referrer URL —
+ * are directly assertable in tests.
+ */
+export function buildCapturePayload(capture: PendingCapture, apiKey: string, timestamp: string) {
+  return {
+    api_key: apiKey,
+    event: capture.event,
+    distinct_id: capture.distinctId,
+    timestamp,
+    properties: {
+      ...capture.properties,
+      // Anonymous by construction: no person profile is created or updated,
+      // and `$ip: null` tells PostHog to skip GeoIP enrichment rather than
+      // geolocating our own server.
+      $process_person_profile: false,
+      $ip: null,
+      $lib: 'threadplane-website-proxy',
+    },
+  };
+}
+
+export async function sendToPostHog(capture: PendingCapture): Promise<void> {
   const token = toSafeAnalyticsString(process.env.NEXT_PUBLIC_POSTHOG_TOKEN, 500);
   if (!token) return;
 
@@ -91,31 +130,16 @@ async function sendToPostHog(capture: PendingCapture): Promise<void> {
     await fetch(`${host}/i/v0/e/`, {
       method: 'POST',
       headers: { 'content-type': 'application/json' },
-      body: JSON.stringify({
-        api_key: token,
-        event: capture.event,
-        distinct_id: capture.distinctId,
-        timestamp: new Date().toISOString(),
-        properties: {
-          ...capture.properties,
-          // Anonymous by construction: no person profile is created or updated,
-          // and `$ip: null` tells PostHog to skip GeoIP enrichment rather than
-          // geolocating our own edge node.
-          $process_person_profile: false,
-          $ip: null,
-          $lib: 'threadplane-website-middleware',
-        },
-      }),
+      body: JSON.stringify(buildCapturePayload(capture, token, new Date().toISOString())),
       // A dropped analytics event is acceptable; a hung request is not.
       signal: AbortSignal.timeout(2000),
-      keepalive: true,
     });
   } catch {
     // Swallow. Analytics must never surface to a visitor.
   }
 }
 
-export function middleware(request: NextRequest, event: NextFetchEvent) {
+export function proxy(request: NextRequest, event: NextFetchEvent) {
   const response = NextResponse.next();
 
   try {
@@ -130,6 +154,7 @@ export function middleware(request: NextRequest, event: NextFetchEvent) {
         path: request.nextUrl.pathname,
         now: Date.now(),
         seen: seenCrawlerKeys,
+        budget: emissionBudget,
       });
 
       // Fire-and-forget, but registered with the platform so the runtime keeps the
@@ -144,18 +169,30 @@ export function middleware(request: NextRequest, event: NextFetchEvent) {
 }
 
 /**
- * HTML routes only.
+ * Routes we want to observe.
+ *
+ * The first entry is HTML pages. The explicit entries after it are the files
+ * written FOR AI consumers plus the two strongest crawler-intent signals that
+ * exist — a hit on `llms.txt` or `sitemap.xml` is the clearest evidence that an
+ * AI engine is reading us, which is the whole point of this instrumentation.
+ * They would otherwise be lost to the blunt "has a file extension" rule.
  *
- * Excluded, and why:
+ * Excluded by the first entry, and why:
  * - `api`            — no HTML, and lead/checkout routes already capture server-side.
  * - `_next/static`, `_next/image` — build assets.
  * - `ingest`         — the PostHog proxy rewrites in `next.config.ts`; matching them
- *                      would put middleware in front of our own analytics traffic.
- * - `favicon.ico`, and any final segment containing a `.` — static files, plus
- *   `sitemap.xml`, `robots.txt`, `llms.txt`. (Trade-off: we therefore do not see
- *   crawler hits on `llms.txt`; server logs remain the source for those.)
+ *                      would put this in front of our own analytics traffic.
+ * - `favicon.ico`, and any final segment containing a `.` — static files.
  * - `opengraph-image` / `twitter-image` — prerendered PNG routes with no extension.
+ *   Anchored to a segment boundary so a page legitimately named
+ *   `/my-opengraph-image-guide` is still observed.
  */
 export const config = {
-  matcher: ['/((?!api|_next/static|_next/image|ingest|favicon.ico|.*opengraph-image|.*twitter-image|.*\\.[^/]*$).*)'],
+  matcher: [
+    '/((?!api|_next/static|_next/image|ingest|favicon\\.ico|.*opengraph-image(?:/|$)|.*twitter-image(?:/|$)|.*\\.[^/]*$).*)',
+    '/llms.txt',
+    '/llms-full.txt',
+    '/sitemap.xml',
+    '/robots.txt',
+  ],
 };
diff --git a/docs/gtm/taxonomy.md b/docs/gtm/taxonomy.md
index 8560f5830..aad3dd39c 100644
--- a/docs/gtm/taxonomy.md
+++ b/docs/gtm/taxonomy.md
@@ -40,8 +40,8 @@ The standard PostHog `$pageview` event is used as-is across all three surfaces.
 | `marketing:newsletter_signup_submit`  | Submit attempt                                                                                |
 | `marketing:newsletter_signup_success` | Server 2xx                                                                                    |
 | `marketing:newsletter_signup_fail`    | Failure                                                                                       |
-| `marketing:ai_crawler_visit`          | Edge middleware saw a known AI crawler UA on an HTML route. Props: `ai_crawler`, `source_page`, `user_agent`. Deduped per crawler/path/hour. |
-| `marketing:ai_referral_visit`         | Edge middleware saw a referrer from an AI answer engine. Props: `ai_source`, `source_page`. Anonymous (no person profile). |
+| `marketing:ai_crawler_visit`          | Proxy saw a known AI crawler UA on an observed route (HTML pages plus llms.txt / sitemap.xml / robots.txt). Props: `ai_crawler`, `source_page`, `user_agent`. Deduped per crawler/path/hour and capped by a per-instance emission ceiling. |
+| `marketing:ai_referral_visit`         | Proxy saw a referrer from an AI answer engine. Props: `ai_source`, `source_page`. Anonymous (no person profile). |
 | `docs:search_submit`                  | Docs search invocation                                                                        |
 | `docs:search_result_click`            | Result click                                                                                  |
 | `docs:copy_prompt_click`              | Prompt-copy button                                                                            |

From c6aa2b9d78cb25f665d05a3fd22b0e964aa9c2bb Mon Sep 17 00:00:00 2001
From: Brian Love <brian@liveloveapp.com>
Date: Thu, 20 Aug 2026 15:40:09 -0700
Subject: [PATCH 30/35] revert(website): keep ai-traffic middleware on the edge
 runtime
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Reverts only the proxy.ts rename from 3413824f. Every other change in that
commit — the emission token bucket, the sendToPostHog payload coverage, the
llms.txt/sitemap.xml/robots.txt matchers, the anchored og-image exclusion —
is kept.

The rename silenced a cosmetic deprecation warning at the cost of moving the
runtime from Edge to Node on every request to a public production site.
Next 16's proxy convention always runs on Node, so `git mv` was not a file
rename but a deployment-shape change: different cold-start and pricing
characteristics on Vercel, and unverifiable from a local build. The
deprecation is a warning, not a break, and 16.1.7 builds and runs the
middleware convention fine.

The migration is still worth doing — it additionally makes process.env
runtime-read instead of build-inlined, so token rotation would stop needing
a redeploy — but it belongs in its own change with a preview deploy behind
it, not bundled in as a side effect of a warning fix. A comment on the file
records that the warning is deliberate and that the migration is mechanical,
because the code uses only Web-standard APIs.

Re-verified on Edge after the revert, rather than assumed to carry over from
the Node run: chunks back under server/edge/ with all five matchers; a
5s-hanging PostHog left /contact, /llms.txt and /pricing returning 200 in
9-69ms with all three events still delivered; two 700-request floods
(spoofed chatgpt.com Referer, and GPTBot across 700 distinct paths) each
capped at 501 events; llms.txt, llms-full.txt, sitemap.xml and robots.txt
all captured; ordinary traffic, Googlebot, a google.com referrer and the
evil-chatgpt.com.attacker.net lookalike all emitted nothing.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
---
 .../src/{proxy.spec.ts => middleware.spec.ts} |  4 +--
 apps/website/src/{proxy.ts => middleware.ts}  | 25 +++++++++++++++----
 docs/gtm/taxonomy.md                          |  4 +--
 3 files changed, 24 insertions(+), 9 deletions(-)
 rename apps/website/src/{proxy.spec.ts => middleware.spec.ts} (99%)
 rename apps/website/src/{proxy.ts => middleware.ts} (85%)

diff --git a/apps/website/src/proxy.spec.ts b/apps/website/src/middleware.spec.ts
similarity index 99%
rename from apps/website/src/proxy.spec.ts
rename to apps/website/src/middleware.spec.ts
index 2725b00aa..25a1313f1 100644
--- a/apps/website/src/proxy.spec.ts
+++ b/apps/website/src/middleware.spec.ts
@@ -1,6 +1,6 @@
 // SPDX-License-Identifier: MIT
 import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest';
-import { buildCapturePayload, classifyRequest, config, sendToPostHog } from './proxy';
+import { buildCapturePayload, classifyRequest, config, sendToPostHog } from './middleware';
 import { createEmissionBudget, EMISSION_BUCKET_CAPACITY } from './lib/analytics/ai-traffic';
 
 const MATCHERS = config.matcher.map((m) => new RegExp(`^${m}$`));
@@ -8,7 +8,7 @@ const matches = (path: string) => MATCHERS.some((re) => re.test(path));
 
 const budget = () => createEmissionBudget(0);
 
-describe('proxy matcher', () => {
+describe('middleware matcher', () => {
   it.each([
     '/',
     '/blog/x',
diff --git a/apps/website/src/proxy.ts b/apps/website/src/middleware.ts
similarity index 85%
rename from apps/website/src/proxy.ts
rename to apps/website/src/middleware.ts
index abd2fabc6..9742b0a89 100644
--- a/apps/website/src/proxy.ts
+++ b/apps/website/src/middleware.ts
@@ -16,12 +16,27 @@ import {
  *
  * Google Search Console's Generative AI report has no API, and AI crawlers never
  * run JavaScript — so `instrumentation-client.ts` cannot see either signal. This
- * proxy (formerly "middleware") is the only place we can.
+ * middleware is the only place we can.
  *
  * Written against Web-standard APIs only (`fetch`, `NextRequest`,
  * `FetchEvent#waitUntil`) so it behaves identically on the Edge and Node.js
- * runtimes. `posthog-node` is intentionally NOT used: it is a Node library and
- * this file was Edge-resident until the proxy rename.
+ * runtimes. `posthog-node` is intentionally NOT used: it is a Node library, and
+ * this file runs on the Edge runtime.
+ *
+ * DEFERRED, DELIBERATELY: Next 16 deprecates the `middleware` file convention in
+ * favour of `proxy`, so the production build emits a deprecation warning. That
+ * warning is known, not overlooked. The rename is NOT cosmetic — a `proxy.ts`
+ * always runs on the Node.js runtime, so renaming this file silently moves every
+ * request on a public production site from Edge to Node, which has different
+ * cold-start and pricing characteristics on Vercel and cannot be validated from
+ * a local build. It belongs in its own change with a preview deploy behind it.
+ *
+ * When that happens the migration is mechanical — `git mv` to `proxy.ts`, rename
+ * the `middleware` export to `proxy` — precisely because everything here is
+ * Web-standard: `NextProxy` is a type alias for `NextMiddleware`, so the
+ * signature and `waitUntil` are unchanged. Verified on a throwaway branch: it
+ * works, and it additionally makes `process.env` runtime-read instead of
+ * build-inlined (so token rotation would stop needing a redeploy).
  *
  * Capture goes DIRECT to the PostHog ingest host, not through the `/ingest/*`
  * rewrites in `next.config.ts`. Those exist so ad-blockers cannot intercept the
@@ -116,7 +131,7 @@ export function buildCapturePayload(capture: PendingCapture, apiKey: string, tim
       // geolocating our own server.
       $process_person_profile: false,
       $ip: null,
-      $lib: 'threadplane-website-proxy',
+      $lib: 'threadplane-website-middleware',
     },
   };
 }
@@ -139,7 +154,7 @@ export async function sendToPostHog(capture: PendingCapture): Promise<void> {
   }
 }
 
-export function proxy(request: NextRequest, event: NextFetchEvent) {
+export function middleware(request: NextRequest, event: NextFetchEvent) {
   const response = NextResponse.next();
 
   try {
diff --git a/docs/gtm/taxonomy.md b/docs/gtm/taxonomy.md
index aad3dd39c..a3aae2262 100644
--- a/docs/gtm/taxonomy.md
+++ b/docs/gtm/taxonomy.md
@@ -40,8 +40,8 @@ The standard PostHog `$pageview` event is used as-is across all three surfaces.
 | `marketing:newsletter_signup_submit`  | Submit attempt                                                                                |
 | `marketing:newsletter_signup_success` | Server 2xx                                                                                    |
 | `marketing:newsletter_signup_fail`    | Failure                                                                                       |
-| `marketing:ai_crawler_visit`          | Proxy saw a known AI crawler UA on an observed route (HTML pages plus llms.txt / sitemap.xml / robots.txt). Props: `ai_crawler`, `source_page`, `user_agent`. Deduped per crawler/path/hour and capped by a per-instance emission ceiling. |
-| `marketing:ai_referral_visit`         | Proxy saw a referrer from an AI answer engine. Props: `ai_source`, `source_page`. Anonymous (no person profile). |
+| `marketing:ai_crawler_visit`          | Edge middleware saw a known AI crawler UA on an observed route (HTML pages plus llms.txt / sitemap.xml / robots.txt). Props: `ai_crawler`, `source_page`, `user_agent`. Deduped per crawler/path/hour and capped by a per-instance emission ceiling. |
+| `marketing:ai_referral_visit`         | Edge middleware saw a referrer from an AI answer engine. Props: `ai_source`, `source_page`. Anonymous (no person profile). |
 | `docs:search_submit`                  | Docs search invocation                                                                        |
 | `docs:search_result_click`            | Result click                                                                                  |
 | `docs:copy_prompt_click`              | Prompt-copy button                                                                            |

From 9f532fd660739ee88f2acae17af36cb8f646bb44 Mon Sep 17 00:00:00 2001
From: Brian Love <brian@liveloveapp.com>
Date: Thu, 20 Aug 2026 15:52:39 -0700
Subject: [PATCH 31/35] docs(blog): architecture diagrams for the tutorial
 posts
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Every blog post shipped zero images. Add three hand-authored SVG
diagrams, one per architecture-heavy post, each drawn from what the
post actually explains:

- ag-ui-event-flow: the client-tool round trip — the browser ships its
  tool catalog up, the server streams AG-UI events down, and the tool
  result the browser produces starts the next run.
- langgraph-threads-and-runs: the ACTIVE_THREAD signal as the pivot
  between the thread list and the active run.
- agent-contract-boundary: two runtimes reduced into one neutral
  contract of Angular signals, with user intent travelling back.

Each SVG paints its own surface and carries a <title>/<desc>, so it
reads on a light or dark page without depending on the host theme.
Colors come from the design tokens' light palette.

Add an `img` override to MdxRenderer that emits explicit width/height
(so the box is reserved before the file loads, keeping layout shift at
zero) plus lazy loading and async decoding.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
---
 ...ntic-ui-in-angular-production-patterns.mdx |  2 +
 ...3-angular-chat-app-tutorial-with-ag-ui.mdx |  2 +
 ...-app-tutorial-with-langchain-langgraph.mdx |  2 +
 .../public/blog/diagrams/ag-ui-event-flow.svg | 70 ++++++++++++++++++
 .../blog/diagrams/agent-contract-boundary.svg | 73 +++++++++++++++++++
 .../diagrams/langgraph-threads-and-runs.svg   | 67 +++++++++++++++++
 .../src/components/docs/MdxRenderer.tsx       | 18 +++++
 7 files changed, 234 insertions(+)
 create mode 100644 apps/website/public/blog/diagrams/ag-ui-event-flow.svg
 create mode 100644 apps/website/public/blog/diagrams/agent-contract-boundary.svg
 create mode 100644 apps/website/public/blog/diagrams/langgraph-threads-and-runs.svg

diff --git a/apps/website/content/blog/2026-08-09-agentic-ui-in-angular-production-patterns.mdx b/apps/website/content/blog/2026-08-09-agentic-ui-in-angular-production-patterns.mdx
index 10dc84de2..ed655d653 100644
--- a/apps/website/content/blog/2026-08-09-agentic-ui-in-angular-production-patterns.mdx
+++ b/apps/website/content/blog/2026-08-09-agentic-ui-in-angular-production-patterns.mdx
@@ -78,6 +78,8 @@ Let the adapter own accumulation, deduplication, and lifecycle transitions.
 Let the component read the result.
 The [Signals guide](/docs/langgraph/concepts/angular-signals) shows the boundary in practice.
 
+![LangGraph stream chunks and AG-UI SSE events both enter a runtime adapter that owns accumulation, deduplication and lifecycle transitions, and the adapter publishes one Agent contract of Angular signals - messages, status, toolCalls, state, error and interrupt - that chat components and an approved component registry read, with user intent travelling back through the same contract.](/blog/diagrams/agent-contract-boundary.svg)
+
 The tradeoff is that normalization can hide useful runtime detail.
 Keep an explicit event escape hatch for information that isn't durable UI state, but don't publish messages or tool calls through two competing sources.
 Two sources of truth create timing bugs that are difficult to reproduce and even harder to explain to a user.
diff --git a/apps/website/content/blog/2026-08-13-angular-chat-app-tutorial-with-ag-ui.mdx b/apps/website/content/blog/2026-08-13-angular-chat-app-tutorial-with-ag-ui.mdx
index b26b3c289..98b110708 100644
--- a/apps/website/content/blog/2026-08-13-angular-chat-app-tutorial-with-ag-ui.mdx
+++ b/apps/website/content/blog/2026-08-13-angular-chat-app-tutorial-with-ag-ui.mdx
@@ -47,6 +47,8 @@ A reading list. The user asks the assistant to save something; the assistant cal
 
 Three tools, three different shapes, and the server implements none of them.
 
+![The Angular chat component declares its action, view and ask client tools; the catalog travels to the FastAPI /agent endpoint where bind_client_tools binds it to the model for that run, the graph ends its turn and streams AG-UI events back over SSE, the @threadplane/ag-ui adapter reduces them into Angular signals, and the tool result the browser produces starts the next run.](/blog/diagrams/ag-ui-event-flow.svg)
+
 ## How do we get an AG-UI endpoint running?
 
 Install the integration:
diff --git a/apps/website/content/blog/2026-08-13-angular-chat-app-tutorial-with-langchain-langgraph.mdx b/apps/website/content/blog/2026-08-13-angular-chat-app-tutorial-with-langchain-langgraph.mdx
index 3006bfa33..60ed68f5f 100644
--- a/apps/website/content/blog/2026-08-13-angular-chat-app-tutorial-with-langchain-langgraph.mdx
+++ b/apps/website/content/blog/2026-08-13-angular-chat-app-tutorial-with-langchain-langgraph.mdx
@@ -51,6 +51,8 @@ Two Angular pieces, and they read from different places.
 
 That split is the thing to hold onto. The agent knows about one conversation. The thread adapter knows about all of them.
 
+![chat-sidenav renders every conversation from LangGraphThreadsAdapter while chat renders the active one from the @threadplane/langgraph agent; selecting a row sets the ACTIVE_THREAD signal, the agent adapter watches that signal and switches conversations, and onThreadId writes a newly created thread id back into it.](/blog/diagrams/langgraph-threads-and-runs.svg)
+
 ## How do we get a LangGraph server running?
 
 Let's do the backend first, because the Angular side has nothing to bind to without it.
diff --git a/apps/website/public/blog/diagrams/ag-ui-event-flow.svg b/apps/website/public/blog/diagrams/ag-ui-event-flow.svg
new file mode 100644
index 000000000..351c9bab7
--- /dev/null
+++ b/apps/website/public/blog/diagrams/ag-ui-event-flow.svg
@@ -0,0 +1,70 @@
+<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 880 480" width="880" height="480" role="img" aria-labelledby="d-title d-desc">
+  <title id="d-title">AG-UI client-tool round trip between an Angular browser app and the agent server</title>
+  <desc id="d-desc">The Angular chat component declares its action, view and ask client tools; the catalog travels to the FastAPI /agent endpoint, where bind_client_tools binds it to the model per run. The graph ends its turn and streams AG-UI events over SSE; the @threadplane/ag-ui adapter turns them into Angular signals, the browser executes the call, and the tool result starts the next run.</desc>
+  <defs>
+    <marker id="arrow" viewBox="0 0 10 10" refX="9" refY="5" markerWidth="7" markerHeight="7" orient="auto-start-reverse">
+      <path d="M0,0.5 L9.5,5 L0,9.5 z" fill="#004090"/>
+    </marker>
+  </defs>
+  <style>
+    text { font-family: system-ui, -apple-system, "Segoe UI", Roboto, "Helvetica Neue", Arial, sans-serif; }
+    .t-eyebrow { font-size: 11px; font-weight: 700; fill: #737373; letter-spacing: 0.09em; }
+    .t-head { font-size: 16.5px; font-weight: 600; fill: #1c1c1c; }
+    .t-title { font-size: 14.5px; font-weight: 600; fill: #1c1c1c; font-family: ui-monospace, SFMono-Regular, Menlo, Consolas, monospace; }
+    .t-meta { font-size: 12.5px; fill: #464646; }
+    .t-edge { font-size: 12px; font-weight: 600; fill: #004090; }
+    .edge { stroke: #004090; stroke-width: 1.6; fill: none; marker-end: url(#arrow); }
+  </style>
+
+  <rect x="0.5" y="0.5" width="879" height="479" rx="12" fill="#ffffff" stroke="#e5e5e5"/>
+  <text class="t-eyebrow" x="32" y="34">AG-UI · CLIENT TOOLS</text>
+  <text class="t-head" x="32" y="60">The browser declares the tools; the server streams the events</text>
+
+  <rect x="24" y="76" width="364" height="348" rx="10" fill="#fbfbfb" stroke="#f0f0f0"/>
+  <rect x="478" y="76" width="364" height="348" rx="10" fill="#fbfbfb" stroke="#f0f0f0"/>
+  <text class="t-eyebrow" x="44" y="98">BROWSER</text>
+  <text class="t-eyebrow" x="498" y="98">SERVER</text>
+
+  <rect x="44" y="106" width="324" height="86" rx="8" fill="#f2f5f9" stroke="#c3d1e2"/>
+  <text class="t-title" x="62" y="138">&lt;chat [clientTools]&gt;</text>
+  <text class="t-meta" x="62" y="162">declares action() · view()</text>
+  <text class="t-meta" x="62" y="180">and ask() tools</text>
+
+  <rect x="44" y="212" width="324" height="86" rx="8" fill="#ffffff" stroke="#d4d4d4"/>
+  <text class="t-title" x="62" y="244">@threadplane/ag-ui</text>
+  <text class="t-meta" x="62" y="268">reduces AG-UI events</text>
+  <text class="t-meta" x="62" y="286">into Angular signals</text>
+
+  <rect x="44" y="318" width="324" height="86" rx="8" fill="#ffffff" stroke="#d4d4d4"/>
+  <text class="t-title" x="62" y="350">the browser runs it</text>
+  <text class="t-meta" x="62" y="374">a handler returns, a component</text>
+  <text class="t-meta" x="62" y="392">mounts, or the user answers</text>
+
+  <rect x="498" y="106" width="324" height="86" rx="8" fill="#ffffff" stroke="#d4d4d4"/>
+  <text class="t-title" x="516" y="138">POST /agent</text>
+  <text class="t-meta" x="516" y="162">FastAPI + ag-ui-langgraph</text>
+
+  <rect x="498" y="212" width="324" height="86" rx="8" fill="#f2f5f9" stroke="#c3d1e2"/>
+  <text class="t-title" x="516" y="244">bind_client_tools()</text>
+  <text class="t-meta" x="516" y="268">binds the browser's catalog</text>
+  <text class="t-meta" x="516" y="286">to the model, per run</text>
+
+  <rect x="498" y="318" width="324" height="86" rx="8" fill="#ffffff" stroke="#d4d4d4"/>
+  <text class="t-title" x="516" y="350">the graph ends its turn</text>
+  <text class="t-meta" x="516" y="374">no server ToolNode — every</text>
+  <text class="t-meta" x="516" y="392">tool here is a client tool</text>
+
+  <path class="edge" d="M368,149 H494"/>
+  <text class="t-edge" x="433" y="140" text-anchor="middle">tool catalog</text>
+
+  <path class="edge" d="M206,192 V208"/>
+  <path class="edge" d="M660,192 V208"/>
+
+  <path class="edge" d="M498,255 H372"/>
+  <text class="t-edge" x="435" y="246" text-anchor="middle">SSE events</text>
+
+  <path class="edge" d="M206,298 V314"/>
+
+  <path class="edge" d="M206,404 V450 H862 V149 H826"/>
+  <text class="t-edge" x="534" y="442" text-anchor="middle">the tool result starts the next run</text>
+</svg>
diff --git a/apps/website/public/blog/diagrams/agent-contract-boundary.svg b/apps/website/public/blog/diagrams/agent-contract-boundary.svg
new file mode 100644
index 000000000..21c1f53c4
--- /dev/null
+++ b/apps/website/public/blog/diagrams/agent-contract-boundary.svg
@@ -0,0 +1,73 @@
+<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 880 480" width="880" height="480" role="img" aria-labelledby="d-title d-desc">
+  <title id="d-title">The runtime-neutral Agent contract between agent backends and Angular components</title>
+  <desc id="d-desc">LangGraph stream chunks and AG-UI SSE events both enter a runtime adapter that normalizes, deduplicates and accumulates them. The adapter publishes one Agent contract of Angular signals — messages, status, toolCalls, state, error and interrupt — which chat components and an approved component registry read. User intent travels back through the same contract.</desc>
+  <defs>
+    <marker id="arrow" viewBox="0 0 10 10" refX="9" refY="5" markerWidth="7" markerHeight="7" orient="auto-start-reverse">
+      <path d="M0,0.5 L9.5,5 L0,9.5 z" fill="#004090"/>
+    </marker>
+  </defs>
+  <style>
+    text { font-family: system-ui, -apple-system, "Segoe UI", Roboto, "Helvetica Neue", Arial, sans-serif; }
+    .t-eyebrow { font-size: 11px; font-weight: 700; fill: #737373; letter-spacing: 0.09em; }
+    .t-head { font-size: 16.5px; font-weight: 600; fill: #1c1c1c; }
+    .t-title { font-size: 14.5px; font-weight: 600; fill: #1c1c1c; font-family: ui-monospace, SFMono-Regular, Menlo, Consolas, monospace; }
+    .t-meta { font-size: 12.5px; fill: #464646; }
+    .t-sig { font-size: 13px; fill: #004090; font-family: ui-monospace, SFMono-Regular, Menlo, Consolas, monospace; }
+    .t-edge { font-size: 12px; font-weight: 600; fill: #004090; }
+    .t-caption { font-size: 12.5px; fill: #737373; }
+    .edge { stroke: #004090; stroke-width: 1.6; fill: none; marker-end: url(#arrow); }
+  </style>
+
+  <rect x="0.5" y="0.5" width="879" height="479" rx="12" fill="#ffffff" stroke="#e5e5e5"/>
+  <text class="t-eyebrow" x="32" y="34">AGENTIC UI · THE NEUTRAL BOUNDARY</text>
+  <text class="t-head" x="32" y="60">Runtime events go in, Angular signals come out</text>
+
+  <text class="t-eyebrow" x="32" y="106">RUNTIME</text>
+  <text class="t-eyebrow" x="242" y="106">ADAPTER</text>
+  <text class="t-eyebrow" x="452" y="106">AGENT CONTRACT</text>
+  <text class="t-eyebrow" x="680" y="106">COMPONENTS</text>
+
+  <rect x="32" y="120" width="178" height="82" rx="8" fill="#ffffff" stroke="#d4d4d4"/>
+  <text class="t-title" x="50" y="154">LangGraph</text>
+  <text class="t-meta" x="50" y="178">stream chunks</text>
+
+  <rect x="32" y="228" width="178" height="82" rx="8" fill="#ffffff" stroke="#d4d4d4"/>
+  <text class="t-title" x="50" y="262">AG-UI</text>
+  <text class="t-meta" x="50" y="286">SSE events</text>
+
+  <rect x="242" y="120" width="178" height="190" rx="8" fill="#ffffff" stroke="#d4d4d4"/>
+  <text class="t-title" x="260" y="154">runtime adapter</text>
+  <text class="t-meta" x="260" y="184">accumulation</text>
+  <text class="t-meta" x="260" y="206">deduplication</text>
+  <text class="t-meta" x="260" y="228">lifecycle status</text>
+  <text class="t-meta" x="260" y="250">interrupt shape</text>
+
+  <rect x="452" y="120" width="196" height="190" rx="8" fill="#f2f5f9" stroke="#c3d1e2"/>
+  <text class="t-title" x="470" y="154">Agent</text>
+  <text class="t-sig" x="470" y="182">messages()</text>
+  <text class="t-sig" x="470" y="204">status()</text>
+  <text class="t-sig" x="470" y="226">toolCalls()</text>
+  <text class="t-sig" x="470" y="248">state()</text>
+  <text class="t-sig" x="470" y="270">error()</text>
+  <text class="t-sig" x="470" y="292">interrupt()</text>
+
+  <rect x="680" y="120" width="168" height="82" rx="8" fill="#ffffff" stroke="#d4d4d4"/>
+  <text class="t-title" x="698" y="154">&lt;chat&gt;</text>
+  <text class="t-meta" x="698" y="178">tool UI · approvals</text>
+
+  <rect x="680" y="228" width="168" height="82" rx="8" fill="#ffffff" stroke="#d4d4d4"/>
+  <text class="t-title" x="698" y="262">ViewRegistry</text>
+  <text class="t-meta" x="698" y="286">approved components</text>
+
+  <path class="edge" d="M210,161 L238,182"/>
+  <path class="edge" d="M210,269 L238,248"/>
+  <path class="edge" d="M420,215 H448"/>
+  <path class="edge" d="M648,196 L676,163"/>
+  <path class="edge" d="M648,234 L676,267"/>
+
+  <path class="edge" d="M764,310 V372 H331 V314"/>
+  <text class="t-edge" x="548" y="352" text-anchor="middle">submit · abort · retry · respond to an interrupt</text>
+
+  <text class="t-caption" x="32" y="424">Components never read a LangGraph chunk or an AG-UI event name. What differs between runtimes —</text>
+  <text class="t-caption" x="32" y="444">checkpoint history, branching, subagents — is feature-detected at a deliberate edge, not assumed.</text>
+</svg>
diff --git a/apps/website/public/blog/diagrams/langgraph-threads-and-runs.svg b/apps/website/public/blog/diagrams/langgraph-threads-and-runs.svg
new file mode 100644
index 000000000..2fbf37441
--- /dev/null
+++ b/apps/website/public/blog/diagrams/langgraph-threads-and-runs.svg
@@ -0,0 +1,67 @@
+<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 880 480" width="880" height="480" role="img" aria-labelledby="d-title d-desc">
+  <title id="d-title">How one Angular signal switches the active LangGraph conversation</title>
+  <desc id="d-desc">chat-sidenav lists every thread from LangGraphThreadsAdapter, while chat renders one conversation from the @threadplane/langgraph agent. Selecting a row sets the ACTIVE_THREAD signal, the agent adapter watches that signal and switches conversations, and onThreadId writes a newly created thread id back into it.</desc>
+  <defs>
+    <marker id="arrow" viewBox="0 0 10 10" refX="9" refY="5" markerWidth="7" markerHeight="7" orient="auto-start-reverse">
+      <path d="M0,0.5 L9.5,5 L0,9.5 z" fill="#004090"/>
+    </marker>
+  </defs>
+  <style>
+    text { font-family: system-ui, -apple-system, "Segoe UI", Roboto, "Helvetica Neue", Arial, sans-serif; }
+    .t-eyebrow { font-size: 11px; font-weight: 700; fill: #737373; letter-spacing: 0.09em; }
+    .t-head { font-size: 16.5px; font-weight: 600; fill: #1c1c1c; }
+    .t-title { font-size: 14.5px; font-weight: 600; fill: #1c1c1c; font-family: ui-monospace, SFMono-Regular, Menlo, Consolas, monospace; }
+    .t-meta { font-size: 12.5px; fill: #464646; }
+    .t-edge { font-size: 12px; font-weight: 600; fill: #004090; }
+    .t-caption { font-size: 12.5px; fill: #737373; }
+    .edge { stroke: #004090; stroke-width: 1.6; fill: none; marker-end: url(#arrow); }
+    .edge-both { stroke: #004090; stroke-width: 1.6; fill: none; marker-end: url(#arrow); marker-start: url(#arrow); }
+  </style>
+
+  <rect x="0.5" y="0.5" width="879" height="479" rx="12" fill="#ffffff" stroke="#e5e5e5"/>
+  <text class="t-eyebrow" x="32" y="34">LANGGRAPH · THREADS AND RUNS</text>
+  <text class="t-head" x="32" y="60">One signal decides which conversation is on screen</text>
+
+  <text class="t-eyebrow" x="32" y="100">ANGULAR COMPONENTS</text>
+  <text class="t-eyebrow" x="624" y="100">@threadplane/langgraph</text>
+
+  <rect x="32" y="114" width="224" height="90" rx="8" fill="#ffffff" stroke="#d4d4d4"/>
+  <text class="t-title" x="50" y="146">&lt;chat-sidenav&gt;</text>
+  <text class="t-meta" x="50" y="170">every conversation,</text>
+  <text class="t-meta" x="50" y="188">titled by the server</text>
+
+  <rect x="32" y="312" width="224" height="90" rx="8" fill="#ffffff" stroke="#d4d4d4"/>
+  <text class="t-title" x="50" y="344">&lt;chat&gt;</text>
+  <text class="t-meta" x="50" y="368">the active conversation,</text>
+  <text class="t-meta" x="50" y="386">streaming</text>
+
+  <rect x="328" y="192" width="224" height="92" rx="8" fill="#f2f5f9" stroke="#c3d1e2"/>
+  <text class="t-title" x="346" y="224">ACTIVE_THREAD</text>
+  <text class="t-meta" x="346" y="248">signal&lt;string | null&gt;,</text>
+  <text class="t-meta" x="346" y="266">mirrored into the URL</text>
+
+  <rect x="624" y="114" width="224" height="90" rx="8" fill="#ffffff" stroke="#d4d4d4"/>
+  <text class="t-title" x="642" y="146">ThreadsAdapter</text>
+  <text class="t-meta" x="642" y="170">client.threads.* —</text>
+  <text class="t-meta" x="642" y="188">list, rename, archive</text>
+
+  <rect x="624" y="312" width="224" height="90" rx="8" fill="#ffffff" stroke="#d4d4d4"/>
+  <text class="t-title" x="642" y="344">provideAgent()</text>
+  <text class="t-meta" x="642" y="368">one thread's run stream</text>
+  <text class="t-meta" x="642" y="386">and checkpoint</text>
+
+  <path class="edge" d="M624,158 H260"/>
+  <text class="t-edge" x="442" y="149" text-anchor="middle">threads() · archivedThreads()</text>
+
+  <path class="edge" d="M624,356 H260"/>
+  <text class="t-edge" x="442" y="347" text-anchor="middle">messages() · status() · toolCalls()</text>
+
+  <path class="edge" d="M144,204 V238 H324"/>
+  <text class="t-edge" x="154" y="230">threadSelected</text>
+
+  <path class="edge-both" d="M556,238 H590 V334 H620"/>
+  <text class="t-edge" x="600" y="230">the adapter watches it,</text>
+  <text class="t-edge" x="600" y="248">onThreadId writes back</text>
+
+  <text class="t-caption" x="32" y="446">LangGraph owns the durable half — checkpoints and the thread store. Angular only owns which thread id is active.</text>
+</svg>
diff --git a/apps/website/src/components/docs/MdxRenderer.tsx b/apps/website/src/components/docs/MdxRenderer.tsx
index e7cc51d92..aea9d13de 100644
--- a/apps/website/src/components/docs/MdxRenderer.tsx
+++ b/apps/website/src/components/docs/MdxRenderer.tsx
@@ -15,6 +15,10 @@ import rehypePrettyCode from 'rehype-pretty-code';
 import rehypeSlug from 'rehype-slug';
 import remarkGfm from 'remark-gfm';
 
+/** Intrinsic size of the SVG diagrams in `public/blog/diagrams`. */
+const DIAGRAM_WIDTH = 880;
+const DIAGRAM_HEIGHT = 480;
+
 const mdxComponents = {
   Callout,
   Steps,
@@ -28,6 +32,20 @@ const mdxComponents = {
   AgUiArchDiagram,
   FeatureChips,
   pre: Pre,
+  // Markdown image syntax carries no dimensions, so fall back to the size the
+  // in-repo diagrams are authored at. Explicit width/height let the browser
+  // reserve the box before the file loads, which keeps layout shift at zero.
+  img: ({ width, height, alt, ...rest }: React.ImgHTMLAttributes<HTMLImageElement>) => (
+    <img
+      {...rest}
+      alt={alt ?? ''}
+      width={width ?? DIAGRAM_WIDTH}
+      height={height ?? DIAGRAM_HEIGHT}
+      loading="lazy"
+      decoding="async"
+      style={{ maxWidth: '100%', height: 'auto', display: 'block', margin: '1.75rem 0' }}
+    />
+  ),
   table: ({ children, ...rest }: React.HTMLAttributes<HTMLTableElement>) => (
     <div className="docs-table-scroll">
       <table {...rest}>{children}</table>

From 1e1c44f2fdac755886257bd734d6c7190c95e966 Mon Sep 17 00:00:00 2001
From: Brian Love <brian@liveloveapp.com>
Date: Thu, 20 Aug 2026 15:54:28 -0700
Subject: [PATCH 32/35] docs(gtm): ai search measurement runbook
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

The GSC harness README and every generated report already point at this
file. Write it.

Covers what each source can and cannot answer, the monthly routine over
gsc:pull / gsc:report, the AI crawler and referral events emitted from
Edge middleware, and the baseline from the first real pull
(2026-05-19 → 2026-08-17) so later pulls have something to compare to.

Two things it is deliberately blunt about:

- The Search Console Generative AI performance report is UI-only. It is
  not in searchanalytics.query, not a searchAppearance value, and not in
  the BigQuery export. The only way to read it is by hand, so the doc
  carries the manual procedure and a running log to paste it into.
- Query-dimension totals (528 impressions) are lower than page-dimension
  totals because Google anonymizes rare queries. Page-level is the true
  volume.

Plus a do-not-do list — llms.txt as a Search tactic, content chunking,
AI-specific keyword rewrites, inauthentic mentions — so nobody re-adds
them. We keep /llms.txt because some non-Google assistants read it, not
because it helps Google.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
---
 docs/gtm/ai-search-measurement.md | 127 ++++++++++++++++++++++++++++++
 1 file changed, 127 insertions(+)
 create mode 100644 docs/gtm/ai-search-measurement.md

diff --git a/docs/gtm/ai-search-measurement.md b/docs/gtm/ai-search-measurement.md
new file mode 100644
index 000000000..993138f83
--- /dev/null
+++ b/docs/gtm/ai-search-measurement.md
@@ -0,0 +1,127 @@
+# AI Search Measurement — Threadplane
+
+> Operational runbook for measuring how threadplane.ai performs in search, including AI-answer surfaces. Referenced from `apps/website/scripts/gsc/README.md` and from every generated `.gsc/report.md`. If the harness or the taxonomy changes, this file changes.
+
+## tl;dr
+
+- Everything except AI Overviews is automated: `npm run gsc:pull` then `npm run gsc:report`.
+- The Search Console **Generative AI performance report** is UI-only. There is no API for it. Read it by hand, monthly, and write the number down.
+- AI crawler hits and AI-engine referrals come from PostHog, emitted by Edge middleware. They are directional, not exact.
+- Several popular "AI SEO" tactics do nothing for Google Search. The [do-not-do list](#do-not-do) exists so nobody re-adds them.
+
+## What each source can and cannot answer
+
+| Source | Answers | Cannot answer |
+| --- | --- | --- |
+| `gsc:pull` / `gsc:report` (Search Console API) | Query and page performance, striking distance, weak CTR, index coverage, canonical choice, Discover, 90-day trend | Anything about AI Overviews or AI Mode |
+| Search Console UI → Generative AI performance | AI Overviews / AI Mode impressions, clicks, position | Nothing exportable through an API or BigQuery |
+| PostHog `marketing:ai_crawler_visit` | Which AI crawlers fetch us, and which pages they fetch | Whether the crawl produced a citation |
+| PostHog `marketing:ai_referral_visit` | Referrals arriving from ChatGPT, Perplexity, Claude, Gemini, Copilot, you.com | Referrals an engine strips (many do), or in-answer citations with no click |
+| Manual spot checks in the assistants themselves | Whether we are actually cited for a question we care about | Anything at scale, or anything trended over time |
+
+No source answers "how many people saw us inside an AI answer." That number does not exist for us. The closest proxies are the UI report (Google only) and the referral events (a click, not an impression).
+
+## The Search Console AI gap
+
+The **Generative AI performance report** — AI Overviews and AI Mode impressions and clicks — is UI-only as of 2026-08.
+
+- It is not in `searchanalytics.query`. That endpoint's `type` field accepts `web`, `image`, `video`, `news`, `discover`, and `googleNews`. Nothing else.
+- There is no `searchAppearance` value for AI features.
+- It is not in the BigQuery bulk export.
+
+Any tool or post claiming to pull AI Overview impressions programmatically is either wrong or is inferring them from something else. Do not build against it, and do not accept a vendor's claim that they have it.
+
+### Manual export procedure
+
+Once a month, at the same time as the pull:
+
+1. Open Search Console for the `threadplane.ai` **Domain property**.
+2. Go to **Performance** and open the **Generative AI performance** report.
+3. Set the date range to the same 90-day window the pull used (see `Window:` on the first line of `.gsc/report.md`).
+4. Record total impressions, total clicks, and average position.
+5. Export the query and page tables if you want detail; the export control on that report writes CSV or Google Sheets.
+6. Paste the four numbers into the running log at the bottom of this file.
+
+The UI labels move. If a step's wording no longer matches, follow the report, not the wording, and fix this list.
+
+## The monthly routine
+
+Run from the repo root, with `GSC_SERVICE_ACCOUNT_JSON` and `GSC_SITE_URL` exported (setup lives in `apps/website/scripts/gsc/README.md`):
+
+```bash
+npm run gsc:pull      # writes apps/website/.gsc/*.json
+npm run gsc:report    # writes apps/website/.gsc/report.md
+```
+
+`.gsc/` is gitignored. The snapshots are raw API output; the report is the readable layer over them. Both are disposable — re-pull rather than archive.
+
+Then, in order:
+
+1. **Read the trend first.** `dates.json` holds the daily series. Split the window in half and compare; a single day is noise.
+2. **Index health.** Anything under "Not indexed" is a page earning zero, permanently. `coverageState` distinguishes "crawled, not indexed" (a quality signal) from "URL is unknown to Google" (a discovery signal — usually links or sitemap). Fix discovery before you touch content.
+3. **Canonical mismatches.** Should stay at zero. A non-zero count means Google picked a different URL than we declared, and our metadata is arguing with itself.
+4. **Striking distance.** Queries at position 5–20 with real impressions. These are the cheapest wins: the page already ranks, it just isn't the answer yet.
+5. **Weak CTR on page one.** Ranks well, nobody clicks. Title and description rewrite candidates — read the position column before acting, because the threshold is flat across positions 1–10.
+6. **Zero-impression pages.** Pages in the sitemap that earned nothing in 90 days. Either they target nothing anyone searches for, or nothing links to them.
+7. **The AI report, by hand.** The procedure above.
+8. **AI traffic in PostHog.** `marketing:ai_crawler_visit` broken out by `ai_crawler` and `source_page`; `marketing:ai_referral_visit` by `ai_source`. Look at shape and direction, not exact counts.
+
+Quota note: the URL Inspection API allows 2000 calls/day, and the sweep uses one per sitemap URL. At ~140 URLs that is not close to the ceiling, but if a sweep partially fails, `pull.ts` writes `.gsc/inspection-errors.json` and the report labels its index-health counts as lower bounds. Believe the label.
+
+## AI crawler and referral events
+
+Both are emitted from Edge middleware, in `apps/website/src/lib/analytics/ai-traffic.ts`, because neither signal can reach the client snippet: crawlers do not execute JavaScript, and a referral needs the `Referer` header at request time.
+
+| Event | Properties |
+| --- | --- |
+| `marketing:ai_crawler_visit` | `ai_crawler`, `source_page`, `user_agent` |
+| `marketing:ai_referral_visit` | `ai_source`, `source_page` |
+
+Read these as directional:
+
+- Emission is **deduped** per crawler and path, hourly, per instance.
+- Emission is **rate-limited** to 500 events per hour per instance, as an abuse ceiling — both inputs are attacker-controlled headers.
+- Instances are serverless and horizontally scaled, so neither bound is fleet-global. The dataset under-counts by design.
+- Only AI-specific crawler variants classify. Plain `Googlebot` and plain `Applebot` are classic search crawlers and are deliberately excluded; `Google-Extended` and `Applebot-Extended` are not.
+- Referrals are anonymous — no person profile — and many engines strip the referrer entirely, so this is a floor on AI-sourced clicks, never a total.
+
+The taxonomy of record is [taxonomy.md](./taxonomy.md). If a property name changes there, change it here too.
+
+## Baseline: first real pull
+
+Window **2026-05-19 → 2026-08-17** (90 days). This is what "before" looks like; compare against it.
+
+| Signal | Value |
+| --- | --- |
+| Impressions, first half → second half of window (daily series) | 1,149 → 2,506 (+118%) |
+| Pages earning at least one click | 15 of 121 |
+| Average position on identified queries | 17.1 |
+| URLs inspected | 139 |
+| Indexed | 126 |
+| Not indexed | 13, including 3 of 9 blog posts and 2 docs pages "unknown to Google" |
+| Canonical mismatches | 0 |
+
+The one query worth naming: **`injectagent`** — 101 impressions, 2 clicks, 2.0% CTR, position 5.6. Ranking well and converting badly, which is a title and description problem, not a ranking problem.
+
+### Why the query totals look too small
+
+Query-dimension totals came to 528 impressions while the page dimension totals far more. That is not a bug in the harness. Google anonymizes rare queries and omits them from the query dimension entirely, so **page-level numbers are the true volume** and query-level numbers are a sample of the identifiable tail. Never quote a query-dimension total as site traffic, and never compute site CTR from it.
+
+## Do not do
+
+Google has said each of these does not help in Search. They are listed here because they keep coming back.
+
+- **`llms.txt`-style files as a *Search* tactic.** We keep `/llms.txt` because some non-Google assistants read it and it costs nothing. It does not affect Google ranking or AI Overviews. Do not cite it as an SEO deliverable, and do not expand it hoping for search gains.
+- **"Chunking" content for retrieval.** Restructuring pages into machine-shaped fragments is not a ranking or citation input. Write for the reader; the fragmenting happens downstream and is not ours to optimize.
+- **AI-specific keyword rewrites.** There is no separate keyword surface for AI answers. A page that answers a real question well is the whole tactic.
+- **Pursuing inauthentic mentions.** Paid, traded, or manufactured mentions to appear in AI answers are the same bad idea they always were, with a new justification.
+
+What actually moves the numbers is unglamorous: pages that answer a specific question, titles that match what the query asked, links and sitemap entries so Google can find the page at all, and fixing the 13 URLs it has not indexed.
+
+## Running log
+
+Append one row per monthly pull. Keep the AI columns even when they are zero — a zero we measured is worth more than a blank.
+
+| Pull date | Window | Impressions | Clicks | Avg position | AI Overview impressions | AI Overview clicks | Notes |
+| --- | --- | --- | --- | --- | --- | --- | --- |
+| 2026-08-20 | 2026-05-19 → 2026-08-17 | 528 (query dim) | — | 17.1 | not yet read | not yet read | First pull. Page-dimension volume is higher; see the anonymization note. |

From 5ffe40d3bfc22203d240008142bdd2accfb9a536 Mon Sep 17 00:00:00 2001
From: Brian Love <brian@liveloveapp.com>
Date: Thu, 20 Aug 2026 16:16:21 -0700
Subject: [PATCH 33/35] fix(blog): size diagrams for the real prose column
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

The diagrams were authored at 880 wide. `.docs-prose` computes to
706.56px — `max-width: 70ch` wins over Tailwind's `max-w-none` because
it sits later in the built stylesheet — so they rendered at scale 0.803
and put 12.5px labels at 10.0px. On a 375px viewport the column is 323px,
scale 0.372, detail text at 4.6px. Unreadable, and never measured.

Re-author all three at a 700 viewBox so they render 1:1 in the column,
with the type scale raised a step (meta 13px, eyebrow 11.5px). The wider
layouts do not survive 700px, so each one goes more vertical:

- ag-ui-event-flow: one column of six steps, browser/server marked by a
  tinted left rule and a corner tag, with the return rail on the left.
- langgraph-threads-and-runs: two rows pivoting on ACTIVE_THREAD, edge
  labels moved above each exchange instead of into the column gap.
- agent-contract-boundary: four stacked bands instead of four columns.

Below 706px the paragraph scrolls rather than the figure shrinking —
the same treatment `.docs-table-scroll` gives a wide table — so labels
never scale below their authored size. Verified: the page itself does
not gain a horizontal scrollbar at 371px.

Also drop the inline `style` from the img override in favour of a
`.docs-diagram` class. It duplicated `.docs-prose > p > img`, silently
overrode that rule's `margin: 2rem auto`, and being inline would have
clobbered any author-supplied `style` on a future markdown image.
Per-diagram intrinsic sizes replace the single shared constant now that
the three differ in height.

Measured effective font size of the smallest text class, in the built
page: 11.5px at 1280px wide and 11.5px at 375px (scale 1.0 at both).

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
---
 .../public/blog/diagrams/ag-ui-event-flow.svg | 107 ++++++++++--------
 .../blog/diagrams/agent-contract-boundary.svg |  98 ++++++++--------
 .../diagrams/langgraph-threads-and-runs.svg   |  88 +++++++-------
 apps/website/src/app/global.css               |   8 ++
 .../src/components/docs/MdxRenderer.tsx       |  49 +++++---
 5 files changed, 192 insertions(+), 158 deletions(-)

diff --git a/apps/website/public/blog/diagrams/ag-ui-event-flow.svg b/apps/website/public/blog/diagrams/ag-ui-event-flow.svg
index 351c9bab7..7a85a27d1 100644
--- a/apps/website/public/blog/diagrams/ag-ui-event-flow.svg
+++ b/apps/website/public/blog/diagrams/ag-ui-event-flow.svg
@@ -1,4 +1,4 @@
-<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 880 480" width="880" height="480" role="img" aria-labelledby="d-title d-desc">
+<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 700 690" width="700" height="690" role="img" aria-labelledby="d-title d-desc">
   <title id="d-title">AG-UI client-tool round trip between an Angular browser app and the agent server</title>
   <desc id="d-desc">The Angular chat component declares its action, view and ask client tools; the catalog travels to the FastAPI /agent endpoint, where bind_client_tools binds it to the model per run. The graph ends its turn and streams AG-UI events over SSE; the @threadplane/ag-ui adapter turns them into Angular signals, the browser executes the call, and the tool result starts the next run.</desc>
   <defs>
@@ -8,63 +8,78 @@
   </defs>
   <style>
     text { font-family: system-ui, -apple-system, "Segoe UI", Roboto, "Helvetica Neue", Arial, sans-serif; }
-    .t-eyebrow { font-size: 11px; font-weight: 700; fill: #737373; letter-spacing: 0.09em; }
-    .t-head { font-size: 16.5px; font-weight: 600; fill: #1c1c1c; }
-    .t-title { font-size: 14.5px; font-weight: 600; fill: #1c1c1c; font-family: ui-monospace, SFMono-Regular, Menlo, Consolas, monospace; }
-    .t-meta { font-size: 12.5px; fill: #464646; }
-    .t-edge { font-size: 12px; font-weight: 600; fill: #004090; }
-    .edge { stroke: #004090; stroke-width: 1.6; fill: none; marker-end: url(#arrow); }
+    .t-eyebrow { font-size: 11.5px; font-weight: 700; fill: #737373; letter-spacing: 0.09em; }
+    .t-head { font-size: 17px; font-weight: 600; fill: #1c1c1c; }
+    .t-title { font-size: 15px; font-weight: 600; fill: #1c1c1c; font-family: ui-monospace, SFMono-Regular, Menlo, Consolas, monospace; }
+    .t-meta { font-size: 13px; fill: #464646; }
+    .t-edge { font-size: 12.5px; font-weight: 600; fill: #004090; }
+    .edge { stroke: #004090; stroke-width: 1.7; fill: none; marker-end: url(#arrow); }
   </style>
 
-  <rect x="0.5" y="0.5" width="879" height="479" rx="12" fill="#ffffff" stroke="#e5e5e5"/>
-  <text class="t-eyebrow" x="32" y="34">AG-UI · CLIENT TOOLS</text>
-  <text class="t-head" x="32" y="60">The browser declares the tools; the server streams the events</text>
+  <rect x="0.5" y="0.5" width="699" height="689" rx="12" fill="#ffffff" stroke="#e5e5e5"/>
+  <text class="t-eyebrow" x="40" y="36">AG-UI · CLIENT TOOLS</text>
+  <text class="t-head" x="40" y="64">The browser declares the tools; the server streams the events</text>
 
-  <rect x="24" y="76" width="364" height="348" rx="10" fill="#fbfbfb" stroke="#f0f0f0"/>
-  <rect x="478" y="76" width="364" height="348" rx="10" fill="#fbfbfb" stroke="#f0f0f0"/>
-  <text class="t-eyebrow" x="44" y="98">BROWSER</text>
-  <text class="t-eyebrow" x="498" y="98">SERVER</text>
+  <g>
+    <rect x="40" y="104" width="620" height="62" rx="8" fill="#f2f5f9" stroke="#c3d1e2"/>
+    <rect x="40" y="104" width="4" height="62" fill="#004090"/>
+    <text class="t-eyebrow" x="640" y="126" text-anchor="end">BROWSER</text>
+    <text class="t-title" x="62" y="131">&lt;chat [clientTools]&gt;</text>
+    <text class="t-meta" x="62" y="152">declares action() · view() · ask() and ships them as a catalog</text>
+  </g>
 
-  <rect x="44" y="106" width="324" height="86" rx="8" fill="#f2f5f9" stroke="#c3d1e2"/>
-  <text class="t-title" x="62" y="138">&lt;chat [clientTools]&gt;</text>
-  <text class="t-meta" x="62" y="162">declares action() · view()</text>
-  <text class="t-meta" x="62" y="180">and ask() tools</text>
+  <path class="edge" d="M180,166 V192"/>
+  <text class="t-edge" x="198" y="184">the tool catalog, on every run</text>
 
-  <rect x="44" y="212" width="324" height="86" rx="8" fill="#ffffff" stroke="#d4d4d4"/>
-  <text class="t-title" x="62" y="244">@threadplane/ag-ui</text>
-  <text class="t-meta" x="62" y="268">reduces AG-UI events</text>
-  <text class="t-meta" x="62" y="286">into Angular signals</text>
+  <g>
+    <rect x="40" y="196" width="620" height="62" rx="8" fill="#ffffff" stroke="#d4d4d4"/>
+    <rect x="40" y="196" width="4" height="62" fill="#a3a3a3"/>
+    <text class="t-eyebrow" x="640" y="218" text-anchor="end">SERVER</text>
+    <text class="t-title" x="62" y="223">POST /agent</text>
+    <text class="t-meta" x="62" y="244">FastAPI + ag-ui-langgraph</text>
+  </g>
 
-  <rect x="44" y="318" width="324" height="86" rx="8" fill="#ffffff" stroke="#d4d4d4"/>
-  <text class="t-title" x="62" y="350">the browser runs it</text>
-  <text class="t-meta" x="62" y="374">a handler returns, a component</text>
-  <text class="t-meta" x="62" y="392">mounts, or the user answers</text>
+  <path class="edge" d="M180,258 V284"/>
 
-  <rect x="498" y="106" width="324" height="86" rx="8" fill="#ffffff" stroke="#d4d4d4"/>
-  <text class="t-title" x="516" y="138">POST /agent</text>
-  <text class="t-meta" x="516" y="162">FastAPI + ag-ui-langgraph</text>
+  <g>
+    <rect x="40" y="288" width="620" height="62" rx="8" fill="#f2f5f9" stroke="#c3d1e2"/>
+    <rect x="40" y="288" width="4" height="62" fill="#004090"/>
+    <text class="t-eyebrow" x="640" y="310" text-anchor="end">SERVER</text>
+    <text class="t-title" x="62" y="315">bind_client_tools(llm, [], state)</text>
+    <text class="t-meta" x="62" y="336">binds the browser's catalog to the model, per run</text>
+  </g>
 
-  <rect x="498" y="212" width="324" height="86" rx="8" fill="#f2f5f9" stroke="#c3d1e2"/>
-  <text class="t-title" x="516" y="244">bind_client_tools()</text>
-  <text class="t-meta" x="516" y="268">binds the browser's catalog</text>
-  <text class="t-meta" x="516" y="286">to the model, per run</text>
+  <path class="edge" d="M180,350 V376"/>
 
-  <rect x="498" y="318" width="324" height="86" rx="8" fill="#ffffff" stroke="#d4d4d4"/>
-  <text class="t-title" x="516" y="350">the graph ends its turn</text>
-  <text class="t-meta" x="516" y="374">no server ToolNode — every</text>
-  <text class="t-meta" x="516" y="392">tool here is a client tool</text>
+  <g>
+    <rect x="40" y="380" width="620" height="62" rx="8" fill="#ffffff" stroke="#d4d4d4"/>
+    <rect x="40" y="380" width="4" height="62" fill="#a3a3a3"/>
+    <text class="t-eyebrow" x="640" y="402" text-anchor="end">SERVER</text>
+    <text class="t-title" x="62" y="407">the graph ends its turn</text>
+    <text class="t-meta" x="62" y="428">no server ToolNode — every tool here is a client tool</text>
+  </g>
 
-  <path class="edge" d="M368,149 H494"/>
-  <text class="t-edge" x="433" y="140" text-anchor="middle">tool catalog</text>
+  <path class="edge" d="M180,442 V468"/>
+  <text class="t-edge" x="198" y="460">AG-UI events over SSE</text>
 
-  <path class="edge" d="M206,192 V208"/>
-  <path class="edge" d="M660,192 V208"/>
+  <g>
+    <rect x="40" y="472" width="620" height="62" rx="8" fill="#ffffff" stroke="#d4d4d4"/>
+    <rect x="40" y="472" width="4" height="62" fill="#004090"/>
+    <text class="t-eyebrow" x="640" y="494" text-anchor="end">BROWSER</text>
+    <text class="t-title" x="62" y="499">@threadplane/ag-ui</text>
+    <text class="t-meta" x="62" y="520">reduces the events into Angular signals</text>
+  </g>
 
-  <path class="edge" d="M498,255 H372"/>
-  <text class="t-edge" x="435" y="246" text-anchor="middle">SSE events</text>
+  <path class="edge" d="M180,534 V560"/>
 
-  <path class="edge" d="M206,298 V314"/>
+  <g>
+    <rect x="40" y="564" width="620" height="62" rx="8" fill="#ffffff" stroke="#d4d4d4"/>
+    <rect x="40" y="564" width="4" height="62" fill="#004090"/>
+    <text class="t-eyebrow" x="640" y="586" text-anchor="end">BROWSER</text>
+    <text class="t-title" x="62" y="591">the browser runs it</text>
+    <text class="t-meta" x="62" y="612">a handler returns, a component mounts, or the user answers</text>
+  </g>
 
-  <path class="edge" d="M206,404 V450 H862 V149 H826"/>
-  <text class="t-edge" x="534" y="442" text-anchor="middle">the tool result starts the next run</text>
+  <path class="edge" d="M350,626 V656 H20 V227 H36"/>
+  <text class="t-edge" x="380" y="650">the tool result starts the next run</text>
 </svg>
diff --git a/apps/website/public/blog/diagrams/agent-contract-boundary.svg b/apps/website/public/blog/diagrams/agent-contract-boundary.svg
index 21c1f53c4..98bb92457 100644
--- a/apps/website/public/blog/diagrams/agent-contract-boundary.svg
+++ b/apps/website/public/blog/diagrams/agent-contract-boundary.svg
@@ -1,4 +1,4 @@
-<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 880 480" width="880" height="480" role="img" aria-labelledby="d-title d-desc">
+<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 700 700" width="700" height="700" role="img" aria-labelledby="d-title d-desc">
   <title id="d-title">The runtime-neutral Agent contract between agent backends and Angular components</title>
   <desc id="d-desc">LangGraph stream chunks and AG-UI SSE events both enter a runtime adapter that normalizes, deduplicates and accumulates them. The adapter publishes one Agent contract of Angular signals — messages, status, toolCalls, state, error and interrupt — which chat components and an approved component registry read. User intent travels back through the same contract.</desc>
   <defs>
@@ -8,66 +8,62 @@
   </defs>
   <style>
     text { font-family: system-ui, -apple-system, "Segoe UI", Roboto, "Helvetica Neue", Arial, sans-serif; }
-    .t-eyebrow { font-size: 11px; font-weight: 700; fill: #737373; letter-spacing: 0.09em; }
-    .t-head { font-size: 16.5px; font-weight: 600; fill: #1c1c1c; }
-    .t-title { font-size: 14.5px; font-weight: 600; fill: #1c1c1c; font-family: ui-monospace, SFMono-Regular, Menlo, Consolas, monospace; }
-    .t-meta { font-size: 12.5px; fill: #464646; }
-    .t-sig { font-size: 13px; fill: #004090; font-family: ui-monospace, SFMono-Regular, Menlo, Consolas, monospace; }
-    .t-edge { font-size: 12px; font-weight: 600; fill: #004090; }
-    .t-caption { font-size: 12.5px; fill: #737373; }
-    .edge { stroke: #004090; stroke-width: 1.6; fill: none; marker-end: url(#arrow); }
+    .t-eyebrow { font-size: 11.5px; font-weight: 700; fill: #737373; letter-spacing: 0.09em; }
+    .t-head { font-size: 17px; font-weight: 600; fill: #1c1c1c; }
+    .t-title { font-size: 15px; font-weight: 600; fill: #1c1c1c; font-family: ui-monospace, SFMono-Regular, Menlo, Consolas, monospace; }
+    .t-meta { font-size: 13px; fill: #464646; }
+    .t-sig { font-size: 13.5px; fill: #004090; font-family: ui-monospace, SFMono-Regular, Menlo, Consolas, monospace; }
+    .t-edge { font-size: 12.5px; font-weight: 600; fill: #004090; }
+    .t-caption { font-size: 13px; fill: #737373; }
+    .edge { stroke: #004090; stroke-width: 1.7; fill: none; marker-end: url(#arrow); }
   </style>
 
-  <rect x="0.5" y="0.5" width="879" height="479" rx="12" fill="#ffffff" stroke="#e5e5e5"/>
-  <text class="t-eyebrow" x="32" y="34">AGENTIC UI · THE NEUTRAL BOUNDARY</text>
-  <text class="t-head" x="32" y="60">Runtime events go in, Angular signals come out</text>
+  <rect x="0.5" y="0.5" width="699" height="699" rx="12" fill="#ffffff" stroke="#e5e5e5"/>
+  <text class="t-eyebrow" x="40" y="36">AGENTIC UI · THE NEUTRAL BOUNDARY</text>
+  <text class="t-head" x="40" y="64">Runtime events go in, Angular signals come out</text>
 
-  <text class="t-eyebrow" x="32" y="106">RUNTIME</text>
-  <text class="t-eyebrow" x="242" y="106">ADAPTER</text>
-  <text class="t-eyebrow" x="452" y="106">AGENT CONTRACT</text>
-  <text class="t-eyebrow" x="680" y="106">COMPONENTS</text>
+  <text class="t-eyebrow" x="40" y="102">RUNTIME</text>
+  <rect x="40" y="114" width="300" height="70" rx="8" fill="#ffffff" stroke="#d4d4d4"/>
+  <text class="t-title" x="60" y="144">LangGraph</text>
+  <text class="t-meta" x="60" y="166">stream chunks</text>
 
-  <rect x="32" y="120" width="178" height="82" rx="8" fill="#ffffff" stroke="#d4d4d4"/>
-  <text class="t-title" x="50" y="154">LangGraph</text>
-  <text class="t-meta" x="50" y="178">stream chunks</text>
+  <rect x="360" y="114" width="300" height="70" rx="8" fill="#ffffff" stroke="#d4d4d4"/>
+  <text class="t-title" x="380" y="144">AG-UI</text>
+  <text class="t-meta" x="380" y="166">SSE events</text>
 
-  <rect x="32" y="228" width="178" height="82" rx="8" fill="#ffffff" stroke="#d4d4d4"/>
-  <text class="t-title" x="50" y="262">AG-UI</text>
-  <text class="t-meta" x="50" y="286">SSE events</text>
+  <path class="edge" d="M190,184 L336,256"/>
+  <path class="edge" d="M510,184 L364,256"/>
 
-  <rect x="242" y="120" width="178" height="190" rx="8" fill="#ffffff" stroke="#d4d4d4"/>
-  <text class="t-title" x="260" y="154">runtime adapter</text>
-  <text class="t-meta" x="260" y="184">accumulation</text>
-  <text class="t-meta" x="260" y="206">deduplication</text>
-  <text class="t-meta" x="260" y="228">lifecycle status</text>
-  <text class="t-meta" x="260" y="250">interrupt shape</text>
+  <text class="t-eyebrow" x="40" y="248">ADAPTER</text>
+  <rect x="40" y="260" width="620" height="70" rx="8" fill="#ffffff" stroke="#d4d4d4"/>
+  <text class="t-title" x="60" y="290">runtime adapter</text>
+  <text class="t-meta" x="60" y="312">accumulation · deduplication · lifecycle status · interrupt shape</text>
 
-  <rect x="452" y="120" width="196" height="190" rx="8" fill="#f2f5f9" stroke="#c3d1e2"/>
-  <text class="t-title" x="470" y="154">Agent</text>
-  <text class="t-sig" x="470" y="182">messages()</text>
-  <text class="t-sig" x="470" y="204">status()</text>
-  <text class="t-sig" x="470" y="226">toolCalls()</text>
-  <text class="t-sig" x="470" y="248">state()</text>
-  <text class="t-sig" x="470" y="270">error()</text>
-  <text class="t-sig" x="470" y="292">interrupt()</text>
+  <path class="edge" d="M350,330 V366"/>
 
-  <rect x="680" y="120" width="168" height="82" rx="8" fill="#ffffff" stroke="#d4d4d4"/>
-  <text class="t-title" x="698" y="154">&lt;chat&gt;</text>
-  <text class="t-meta" x="698" y="178">tool UI · approvals</text>
+  <text class="t-eyebrow" x="40" y="384">AGENT CONTRACT</text>
+  <rect x="40" y="396" width="620" height="98" rx="8" fill="#f2f5f9" stroke="#c3d1e2"/>
+  <text class="t-title" x="60" y="426">Agent</text>
+  <text class="t-sig" x="60" y="452">messages()</text>
+  <text class="t-sig" x="260" y="452">status()</text>
+  <text class="t-sig" x="460" y="452">toolCalls()</text>
+  <text class="t-sig" x="60" y="478">state()</text>
+  <text class="t-sig" x="260" y="478">error()</text>
+  <text class="t-sig" x="460" y="478">interrupt()</text>
 
-  <rect x="680" y="228" width="168" height="82" rx="8" fill="#ffffff" stroke="#d4d4d4"/>
-  <text class="t-title" x="698" y="262">ViewRegistry</text>
-  <text class="t-meta" x="698" y="286">approved components</text>
+  <path class="edge" d="M350,494 V530"/>
 
-  <path class="edge" d="M210,161 L238,182"/>
-  <path class="edge" d="M210,269 L238,248"/>
-  <path class="edge" d="M420,215 H448"/>
-  <path class="edge" d="M648,196 L676,163"/>
-  <path class="edge" d="M648,234 L676,267"/>
+  <rect x="40" y="534" width="300" height="66" rx="8" fill="#ffffff" stroke="#d4d4d4"/>
+  <text class="t-title" x="60" y="562">&lt;chat&gt;</text>
+  <text class="t-meta" x="60" y="584">tool progress · approvals</text>
 
-  <path class="edge" d="M764,310 V372 H331 V314"/>
-  <text class="t-edge" x="548" y="352" text-anchor="middle">submit · abort · retry · respond to an interrupt</text>
+  <rect x="360" y="534" width="300" height="66" rx="8" fill="#ffffff" stroke="#d4d4d4"/>
+  <text class="t-title" x="380" y="562">ViewRegistry</text>
+  <text class="t-meta" x="380" y="584">approved components only</text>
 
-  <text class="t-caption" x="32" y="424">Components never read a LangGraph chunk or an AG-UI event name. What differs between runtimes —</text>
-  <text class="t-caption" x="32" y="444">checkpoint history, branching, subagents — is feature-detected at a deliberate edge, not assumed.</text>
+  <path class="edge" d="M180,600 V632 H16 V295 H36"/>
+  <text class="t-edge" x="200" y="626">submit · abort · retry · respond to an interrupt</text>
+
+  <text class="t-caption" x="40" y="666">Components never read a LangGraph chunk or an AG-UI event name. What differs</text>
+  <text class="t-caption" x="40" y="686">between runtimes is feature-detected at a deliberate edge, not assumed.</text>
 </svg>
diff --git a/apps/website/public/blog/diagrams/langgraph-threads-and-runs.svg b/apps/website/public/blog/diagrams/langgraph-threads-and-runs.svg
index 2fbf37441..c6b1af484 100644
--- a/apps/website/public/blog/diagrams/langgraph-threads-and-runs.svg
+++ b/apps/website/public/blog/diagrams/langgraph-threads-and-runs.svg
@@ -1,4 +1,4 @@
-<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 880 480" width="880" height="480" role="img" aria-labelledby="d-title d-desc">
+<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 700 560" width="700" height="560" role="img" aria-labelledby="d-title d-desc">
   <title id="d-title">How one Angular signal switches the active LangGraph conversation</title>
   <desc id="d-desc">chat-sidenav lists every thread from LangGraphThreadsAdapter, while chat renders one conversation from the @threadplane/langgraph agent. Selecting a row sets the ACTIVE_THREAD signal, the agent adapter watches that signal and switches conversations, and onThreadId writes a newly created thread id back into it.</desc>
   <defs>
@@ -8,60 +8,60 @@
   </defs>
   <style>
     text { font-family: system-ui, -apple-system, "Segoe UI", Roboto, "Helvetica Neue", Arial, sans-serif; }
-    .t-eyebrow { font-size: 11px; font-weight: 700; fill: #737373; letter-spacing: 0.09em; }
-    .t-head { font-size: 16.5px; font-weight: 600; fill: #1c1c1c; }
-    .t-title { font-size: 14.5px; font-weight: 600; fill: #1c1c1c; font-family: ui-monospace, SFMono-Regular, Menlo, Consolas, monospace; }
-    .t-meta { font-size: 12.5px; fill: #464646; }
-    .t-edge { font-size: 12px; font-weight: 600; fill: #004090; }
-    .t-caption { font-size: 12.5px; fill: #737373; }
-    .edge { stroke: #004090; stroke-width: 1.6; fill: none; marker-end: url(#arrow); }
-    .edge-both { stroke: #004090; stroke-width: 1.6; fill: none; marker-end: url(#arrow); marker-start: url(#arrow); }
+    .t-eyebrow { font-size: 11.5px; font-weight: 700; fill: #737373; letter-spacing: 0.09em; }
+    .t-head { font-size: 17px; font-weight: 600; fill: #1c1c1c; }
+    .t-title { font-size: 15px; font-weight: 600; fill: #1c1c1c; font-family: ui-monospace, SFMono-Regular, Menlo, Consolas, monospace; }
+    .t-meta { font-size: 13px; fill: #464646; }
+    .t-edge { font-size: 12.5px; font-weight: 600; fill: #004090; }
+    .t-caption { font-size: 13px; fill: #737373; }
+    .edge { stroke: #004090; stroke-width: 1.7; fill: none; marker-end: url(#arrow); }
+    .edge-both { stroke: #004090; stroke-width: 1.7; fill: none; marker-end: url(#arrow); marker-start: url(#arrow); }
   </style>
 
-  <rect x="0.5" y="0.5" width="879" height="479" rx="12" fill="#ffffff" stroke="#e5e5e5"/>
-  <text class="t-eyebrow" x="32" y="34">LANGGRAPH · THREADS AND RUNS</text>
-  <text class="t-head" x="32" y="60">One signal decides which conversation is on screen</text>
+  <rect x="0.5" y="0.5" width="699" height="559" rx="12" fill="#ffffff" stroke="#e5e5e5"/>
+  <text class="t-eyebrow" x="40" y="36">LANGGRAPH · THREADS AND RUNS</text>
+  <text class="t-head" x="40" y="64">One signal decides which conversation is on screen</text>
 
-  <text class="t-eyebrow" x="32" y="100">ANGULAR COMPONENTS</text>
-  <text class="t-eyebrow" x="624" y="100">@threadplane/langgraph</text>
+  <text class="t-edge" x="350" y="110" text-anchor="middle">threads() · archivedThreads()</text>
 
-  <rect x="32" y="114" width="224" height="90" rx="8" fill="#ffffff" stroke="#d4d4d4"/>
-  <text class="t-title" x="50" y="146">&lt;chat-sidenav&gt;</text>
-  <text class="t-meta" x="50" y="170">every conversation,</text>
-  <text class="t-meta" x="50" y="188">titled by the server</text>
+  <rect x="40" y="122" width="280" height="86" rx="8" fill="#ffffff" stroke="#d4d4d4"/>
+  <text class="t-title" x="60" y="152">&lt;chat-sidenav&gt;</text>
+  <text class="t-meta" x="60" y="174">every conversation,</text>
+  <text class="t-meta" x="60" y="194">titled by the server</text>
 
-  <rect x="32" y="312" width="224" height="90" rx="8" fill="#ffffff" stroke="#d4d4d4"/>
-  <text class="t-title" x="50" y="344">&lt;chat&gt;</text>
-  <text class="t-meta" x="50" y="368">the active conversation,</text>
-  <text class="t-meta" x="50" y="386">streaming</text>
+  <rect x="380" y="122" width="280" height="86" rx="8" fill="#ffffff" stroke="#d4d4d4"/>
+  <text class="t-title" x="400" y="152">ThreadsAdapter</text>
+  <text class="t-meta" x="400" y="174">client.threads.* —</text>
+  <text class="t-meta" x="400" y="194">list, rename, archive</text>
 
-  <rect x="328" y="192" width="224" height="92" rx="8" fill="#f2f5f9" stroke="#c3d1e2"/>
-  <text class="t-title" x="346" y="224">ACTIVE_THREAD</text>
-  <text class="t-meta" x="346" y="248">signal&lt;string | null&gt;,</text>
-  <text class="t-meta" x="346" y="266">mirrored into the URL</text>
+  <path class="edge" d="M376,165 H324"/>
 
-  <rect x="624" y="114" width="224" height="90" rx="8" fill="#ffffff" stroke="#d4d4d4"/>
-  <text class="t-title" x="642" y="146">ThreadsAdapter</text>
-  <text class="t-meta" x="642" y="170">client.threads.* —</text>
-  <text class="t-meta" x="642" y="188">list, rename, archive</text>
+  <rect x="170" y="252" width="340" height="90" rx="8" fill="#f2f5f9" stroke="#c3d1e2"/>
+  <text class="t-title" x="190" y="282">ACTIVE_THREAD</text>
+  <text class="t-meta" x="190" y="304">signal&lt;string | null&gt;,</text>
+  <text class="t-meta" x="190" y="324">mirrored into the URL</text>
 
-  <rect x="624" y="312" width="224" height="90" rx="8" fill="#ffffff" stroke="#d4d4d4"/>
-  <text class="t-title" x="642" y="344">provideAgent()</text>
-  <text class="t-meta" x="642" y="368">one thread's run stream</text>
-  <text class="t-meta" x="642" y="386">and checkpoint</text>
+  <path class="edge" d="M200,208 V248"/>
+  <text class="t-edge" x="212" y="234">threadSelected</text>
 
-  <path class="edge" d="M624,158 H260"/>
-  <text class="t-edge" x="442" y="149" text-anchor="middle">threads() · archivedThreads()</text>
+  <path class="edge-both" d="M480,342 V386"/>
+  <text class="t-edge" x="496" y="358">the adapter watches it,</text>
+  <text class="t-edge" x="496" y="376">onThreadId writes back</text>
 
-  <path class="edge" d="M624,356 H260"/>
-  <text class="t-edge" x="442" y="347" text-anchor="middle">messages() · status() · toolCalls()</text>
+  <text class="t-edge" x="286" y="378" text-anchor="middle">messages() · status() · toolCalls()</text>
 
-  <path class="edge" d="M144,204 V238 H324"/>
-  <text class="t-edge" x="154" y="230">threadSelected</text>
+  <rect x="40" y="390" width="280" height="86" rx="8" fill="#ffffff" stroke="#d4d4d4"/>
+  <text class="t-title" x="60" y="420">&lt;chat&gt;</text>
+  <text class="t-meta" x="60" y="442">the active conversation,</text>
+  <text class="t-meta" x="60" y="462">streaming</text>
 
-  <path class="edge-both" d="M556,238 H590 V334 H620"/>
-  <text class="t-edge" x="600" y="230">the adapter watches it,</text>
-  <text class="t-edge" x="600" y="248">onThreadId writes back</text>
+  <rect x="380" y="390" width="280" height="86" rx="8" fill="#ffffff" stroke="#d4d4d4"/>
+  <text class="t-title" x="400" y="420">provideAgent()</text>
+  <text class="t-meta" x="400" y="442">one thread's run stream</text>
+  <text class="t-meta" x="400" y="462">and checkpoint</text>
 
-  <text class="t-caption" x="32" y="446">LangGraph owns the durable half — checkpoints and the thread store. Angular only owns which thread id is active.</text>
+  <path class="edge" d="M376,433 H324"/>
+
+  <text class="t-caption" x="40" y="512">LangGraph owns the durable half — checkpoints and the thread store.</text>
+  <text class="t-caption" x="40" y="532">Angular only owns which thread id is active.</text>
 </svg>
diff --git a/apps/website/src/app/global.css b/apps/website/src/app/global.css
index 1878ca18c..7bcf356bd 100644
--- a/apps/website/src/app/global.css
+++ b/apps/website/src/app/global.css
@@ -182,6 +182,14 @@ html {
   box-shadow: 0 4px 16px rgba(0, 32, 72, 0.08);
 }
 
+/* Architecture diagrams are authored at exactly the width `.docs-prose`
+ * computes to (70ch = ~706px), so they render 1:1 and their labels stay at
+ * their authored size. Below that, scaling the whole figure down would take
+ * 11.5px labels under 5px, so the paragraph scrolls instead — the same
+ * treatment `.docs-table-scroll` gives a wide table. */
+.docs-prose > p:has(> .docs-diagram) { overflow-x: auto; }
+.docs-prose > p > img.docs-diagram { max-width: none; }
+
 .docs-table-scroll { max-width: 100%; overflow-x: auto; margin: 1.5rem 0; }
 .docs-prose table { width: 100%; border-collapse: collapse; font-size: 0.875rem; margin: 0; }
 .docs-prose th { text-align: left; padding: 0.5rem 0.75rem; font-family: var(--font-mono); font-size: 0.75rem; text-transform: uppercase; color: #555770; border-bottom: 1px solid rgba(0, 64, 144, 0.15); }
diff --git a/apps/website/src/components/docs/MdxRenderer.tsx b/apps/website/src/components/docs/MdxRenderer.tsx
index aea9d13de..193ac3b7d 100644
--- a/apps/website/src/components/docs/MdxRenderer.tsx
+++ b/apps/website/src/components/docs/MdxRenderer.tsx
@@ -15,9 +15,19 @@ import rehypePrettyCode from 'rehype-pretty-code';
 import rehypeSlug from 'rehype-slug';
 import remarkGfm from 'remark-gfm';
 
-/** Intrinsic size of the SVG diagrams in `public/blog/diagrams`. */
-const DIAGRAM_WIDTH = 880;
-const DIAGRAM_HEIGHT = 480;
+/**
+ * Intrinsic size of each SVG diagram in `public/blog/diagrams`.
+ *
+ * Markdown image syntax carries no dimensions and MDX gives us no build step
+ * that could measure the file, so the sizes live here. They only need to be
+ * right enough to reserve the correct box before the file loads; the rendered
+ * size comes from the SVG itself.
+ */
+const DIAGRAM_DIMENSIONS: Record<string, { width: number; height: number }> = {
+  '/blog/diagrams/ag-ui-event-flow.svg': { width: 700, height: 690 },
+  '/blog/diagrams/langgraph-threads-and-runs.svg': { width: 700, height: 560 },
+  '/blog/diagrams/agent-contract-boundary.svg': { width: 700, height: 700 },
+};
 
 const mdxComponents = {
   Callout,
@@ -32,20 +42,25 @@ const mdxComponents = {
   AgUiArchDiagram,
   FeatureChips,
   pre: Pre,
-  // Markdown image syntax carries no dimensions, so fall back to the size the
-  // in-repo diagrams are authored at. Explicit width/height let the browser
-  // reserve the box before the file loads, which keeps layout shift at zero.
-  img: ({ width, height, alt, ...rest }: React.ImgHTMLAttributes<HTMLImageElement>) => (
-    <img
-      {...rest}
-      alt={alt ?? ''}
-      width={width ?? DIAGRAM_WIDTH}
-      height={height ?? DIAGRAM_HEIGHT}
-      loading="lazy"
-      decoding="async"
-      style={{ maxWidth: '100%', height: 'auto', display: 'block', margin: '1.75rem 0' }}
-    />
-  ),
+  // Explicit width/height let the browser reserve the box before the file
+  // loads, which keeps layout shift at zero. Presentation stays in global.css
+  // so it cannot silently override the shared bare-image rule, and so an
+  // author-supplied `style` on a future image still wins.
+  img: ({ width, height, alt, src, className, ...rest }: React.ImgHTMLAttributes<HTMLImageElement>) => {
+    const diagram = typeof src === 'string' ? DIAGRAM_DIMENSIONS[src] : undefined;
+    return (
+      <img
+        {...rest}
+        src={src}
+        alt={alt ?? ''}
+        width={width ?? diagram?.width}
+        height={height ?? diagram?.height}
+        className={[className, diagram ? 'docs-diagram' : undefined].filter(Boolean).join(' ') || undefined}
+        loading="lazy"
+        decoding="async"
+      />
+    );
+  },
   table: ({ children, ...rest }: React.HTMLAttributes<HTMLTableElement>) => (
     <div className="docs-table-scroll">
       <table {...rest}>{children}</table>

From be357103d323222f83ae749d73681593e2877b44 Mon Sep 17 00:00:00 2001
From: Brian Love <brian@liveloveapp.com>
Date: Thu, 20 Aug 2026 16:16:21 -0700
Subject: [PATCH 34/35] docs(gtm): scope the dedup claim to crawler events

The bullet sat under a heading covering both AI events, but
`shouldEmitCrawlerEvent` is only called on the crawler path in
middleware.ts. The 500/hour token bucket is the one bound both share.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
---
 docs/gtm/ai-search-measurement.md | 4 ++--
 1 file changed, 2 insertions(+), 2 deletions(-)

diff --git a/docs/gtm/ai-search-measurement.md b/docs/gtm/ai-search-measurement.md
index 993138f83..836cab273 100644
--- a/docs/gtm/ai-search-measurement.md
+++ b/docs/gtm/ai-search-measurement.md
@@ -79,8 +79,8 @@ Both are emitted from Edge middleware, in `apps/website/src/lib/analytics/ai-tra
 
 Read these as directional:
 
-- Emission is **deduped** per crawler and path, hourly, per instance.
-- Emission is **rate-limited** to 500 events per hour per instance, as an abuse ceiling — both inputs are attacker-controlled headers.
+- Crawler events are **deduped** per crawler and path, hourly, per instance. Referral events are not deduped.
+- Both event types share one **rate limit**: 500 events per hour per instance, as an abuse ceiling — both inputs are attacker-controlled headers.
 - Instances are serverless and horizontally scaled, so neither bound is fleet-global. The dataset under-counts by design.
 - Only AI-specific crawler variants classify. Plain `Googlebot` and plain `Applebot` are classic search crawlers and are deliberately excluded; `Google-Extended` and `Applebot-Extended` are not.
 - Referrals are anonymous — no person profile — and many engines strip the referrer entirely, so this is a floor on AI-sourced clicks, never a total.

From 29857e1238ab8ae8988990a15be931f677b971d5 Mon Sep 17 00:00:00 2001
From: Brian Love <brian@liveloveapp.com>
Date: Thu, 20 Aug 2026 16:17:01 -0700
Subject: [PATCH 35/35] chore: ignore local service-account keys directory

Keeps keys/gcp.json (Search Console service account) out of git.
Also added to .git/info/exclude so it takes effect in every worktree
immediately, not only after this branch merges.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
---
 .gitignore | 3 +++
 1 file changed, 3 insertions(+)

diff --git a/.gitignore b/.gitignore
index 856009b4a..e6a543dbd 100644
--- a/.gitignore
+++ b/.gitignore
@@ -67,3 +67,6 @@ libs/licensing/src/lib/license-public-key.generated.ts
 examples/ag-ui/angular/src/environments/generated-keys.local.ts
 # Chat example generated API keys (injected from .env at build time)
 examples/chat/angular/src/environments/generated-keys.local.ts
+
+# Local service-account keys (GSC, etc). Never commit these.
+keys/