feat(adp): citation-bait schema fields + FAQPage emission

migrations/20260517_184638_dedicated_date_modified.ts

@@ -0,0 +1,41 @@
+import { MigrateUpArgs, MigrateDownArgs, sql } from '@payloadcms/db-postgres'
+
+/**
+ * Database Migration: Add dedicatedDateModified to Posts
+ *
+ * Adds a nullable timestamp column to the `posts` table:
+ *   - `dedicated_date_modified` — manually set when meaningful content changes
+ *     ship. Used as the `dateModified` signal in BlogPosting JSON-LD. The
+ *     beforeChange hook auto-stamps this on body/title/summary edits;
+ *     rendering falls back to `updated_at` if unset.
+ *
+ * The column is nullable so existing posts are not broken by the migration —
+ * pre-existing rows have NULL and the schema render falls back to
+ * `updated_at` until the next meaningful edit triggers the hook.
+ *
+ * Uses ADD COLUMN IF NOT EXISTS / DROP COLUMN IF EXISTS for idempotency so
+ * the migration is safe against databases where the column may already exist
+ * (e.g. if `push: true` was used in development).
+ *
+ * N-1 safe: the previous container revision SELECTs `posts.*` via Drizzle's
+ * generated column list. Adding a nullable column does not break old SELECTs
+ * (Drizzle's column list is generated from the schema baked into that
+ * revision, so it neither reads nor writes the new column). New code reads
+ * dedicatedDateModified and falls back to updatedAt when null.
+ *
+ * Down migration: drops the column.
+ */
+
+export async function up({ db }: MigrateUpArgs): Promise<void> {
+  await db.execute(sql`
+    ALTER TABLE "posts"
+      ADD COLUMN IF NOT EXISTS "dedicated_date_modified" timestamp(3) with time zone;
+  `)
+}
+
+export async function down({ db }: MigrateDownArgs): Promise<void> {
+  await db.execute(sql`
+    ALTER TABLE "posts"
+      DROP COLUMN IF EXISTS "dedicated_date_modified";
+  `)
+}

migrations/index.ts

@@ -10,6 +10,7 @@ import * as migration_20260424_035219_add_mermaid_block from './20260424_035219_
 import * as migration_20260425_202704_add_posts_focal_point from './20260425_202704_add_posts_focal_point';
 import * as migration_20260425_220000_add_media_lqip from './20260425_220000_add_media_lqip';
 import * as migration_20260428_010142_add_media_preview from './20260428_010142_add_media_preview';
+import * as migration_20260517_184638_dedicated_date_modified from './20260517_184638_dedicated_date_modified';
 
 export const migrations = [
   {
@@ -72,4 +73,9 @@ export const migrations = [
     down: migration_20260428_010142_add_media_preview.down,
     name: '20260428_010142_add_media_preview',
   },
+  {
+    up: migration_20260517_184638_dedicated_date_modified.up,
+    down: migration_20260517_184638_dedicated_date_modified.down,
+    name: '20260517_184638_dedicated_date_modified'
+  },
 ];

src/app/(frontend)/agentic-design-patterns/[slug]/page.tsx

@@ -25,6 +25,7 @@ import { DisclosureSection } from "@/components/agentic-patterns/DisclosureSecti
 import { RealizingDisclosure } from "@/components/agentic-patterns/RealizingDisclosure";
 import { PrevNextNav } from "@/components/agentic-patterns/PrevNextNav";
 import {
+  generateFaqPageSchema,
   generateHubChildBreadcrumb,
   generatePatternArticleSchema,
 } from "@/lib/schema";
@@ -80,14 +81,19 @@ export default async function PatternSatellitePage({
   const overviewLead = pattern.bodySummary[0];
   const backgroundParagraphs = pattern.bodySummary.slice(1);
 
+  // FAQPage emits as a SECOND top-level schema (per Google's rich-result
+  // guidance) only when the pattern declares related questions. Null when
+  // absent, so we spread-and-filter to keep the schemas array clean.
+  const faqSchema = generateFaqPageSchema(pattern, siteUrl);
+  const schemas = [
+    generatePatternArticleSchema(pattern, siteUrl),
+    generateHubChildBreadcrumb(pattern.slug, pattern.name),
+    ...(faqSchema ? [faqSchema] : []),
+  ];
+
   return (
     <>
-      <SchemaScript
-        schema={[
-          generatePatternArticleSchema(pattern, siteUrl),
-          generateHubChildBreadcrumb(pattern.slug, pattern.name),
-        ]}
-      />
+      <SchemaScript schema={schemas} />
       <PageLayout maxWidth="full">
         <Link
           href="/agentic-design-patterns"

src/collections/Posts.ts

@@ -1,6 +1,7 @@
 import type { CollectionConfig } from 'payload'
 import { createSlugHook } from '@/lib/slug'
 import { publishedOrAuthenticated } from '@/lib/access-control'
+import { beforeChangeDedicatedDateModified } from '@/lib/hooks/before-change-dedicated-date-modified'
 import { revalidateAfterChange, revalidateAfterDelete } from '@/lib/revalidate-post'
 
 export const Posts: CollectionConfig = {
@@ -17,6 +18,7 @@ export const Posts: CollectionConfig = {
     delete: ({ req: { user } }) => !!user,
   },
   hooks: {
+    beforeChange: [beforeChangeDedicatedDateModified],
     afterChange: [revalidateAfterChange],
     afterDelete: [revalidateAfterDelete],
   },
@@ -149,6 +151,16 @@ export const Posts: CollectionConfig = {
       },
       index: true, // Index for sorting by publication date
     },
+    {
+      name: 'dedicatedDateModified',
+      type: 'date',
+      admin: {
+        position: 'sidebar',
+        date: { pickerAppearance: 'dayAndTime' },
+        description:
+          'Manually set when meaningful content changes ship. Used as the `dateModified` signal in BlogPosting schema. The beforeChange hook auto-stamps this on body/title/summary edits; falls back to `updatedAt` if unset.',
+      },
+    },
     {
       name: 'featured',
       type: 'checkbox',

src/components/agentic-patterns/ExpertQuoteBlock.tsx

@@ -0,0 +1,46 @@
+// ---------------------------------------------------------------------------
+// ExpertQuoteBlock
+// ---------------------------------------------------------------------------
+// Semantic <blockquote> rendering an authoritative external quote with its
+// attribution linked back to a public source. Sits between the diagram and
+// the decision matrix so the satellite reads as: visual model → external
+// validation → go/no-go.
+//
+// Visibility: not wrapped in <DisclosureSection> by design — the quote
+// must render unconditionally for citation lift.
+
+import type { Pattern } from "@/data/agentic-design-patterns/types";
+
+interface ExpertQuoteBlockProps {
+  quote: NonNullable<Pattern["expertQuote"]>;
+}
+
+export function ExpertQuoteBlock({ quote }: ExpertQuoteBlockProps) {
+  return (
+    <section
+      id="expert-quote"
+      aria-labelledby="expert-quote-heading"
+      className="scroll-mt-24"
+    >
+      <h2 id="expert-quote-heading" className="sr-only">
+        Expert quote
+      </h2>
+      <figure className="rounded-sm border-l-2 border-accent/60 border-y border-r border-border-subtle bg-surface px-5 py-4">
+        <blockquote className="text-body italic leading-7 text-text-primary [text-wrap:pretty]">
+          {quote.text}
+        </blockquote>
+        <figcaption className="mt-3 text-meta text-text-tertiary">
+          <span aria-hidden="true">— </span>
+          <a
+            href={quote.sourceUrl}
+            rel="noopener noreferrer"
+            target="_blank"
+            className="text-accent underline underline-offset-4 hover:text-accent-muted"
+          >
+            {quote.attribution}
+          </a>
+        </figcaption>
+      </figure>
+    </section>
+  );
+}

src/components/agentic-patterns/KeyStatisticCallout.tsx

@@ -0,0 +1,55 @@
+// ---------------------------------------------------------------------------
+// KeyStatisticCallout
+// ---------------------------------------------------------------------------
+// Above-fold callout box that surfaces a single quantitative claim with a
+// linked public source and the year of the claim. Designed to live just
+// before the pattern's diagram so the most citable line of the page is
+// visible in the reader's first viewport.
+//
+// Visibility: not wrapped in <DisclosureSection>. The claim must render
+// unconditionally so AI crawlers and SERP snippets can extract it.
+
+import type { Pattern } from "@/data/agentic-design-patterns/types";
+
+interface KeyStatisticCalloutProps {
+  statistic: NonNullable<Pattern["keyStatistic"]>;
+}
+
+function hostnameOf(url: string): string {
+  try {
+    return new URL(url).hostname.replace(/^www\./, "");
+  } catch {
+    return url;
+  }
+}
+
+export function KeyStatisticCallout({ statistic }: KeyStatisticCalloutProps) {
+  return (
+    <section
+      id="key-statistic"
+      aria-labelledby="key-statistic-heading"
+      className="scroll-mt-24"
+    >
+      <h2 id="key-statistic-heading" className="sr-only">
+        Key statistic
+      </h2>
+      <div className="rounded-sm border border-border bg-surface p-5">
+        <p className="text-body leading-7 text-text-primary [text-wrap:pretty]">
+          {statistic.claim}
+        </p>
+        <p className="mt-3 text-meta text-text-tertiary">
+          <a
+            href={statistic.sourceUrl}
+            rel="noopener noreferrer"
+            target="_blank"
+            className="font-mono text-xs text-accent underline underline-offset-4 hover:text-accent-muted"
+          >
+            {hostnameOf(statistic.sourceUrl)} →
+          </a>
+          <span className="mx-1.5 text-text-tertiary">·</span>
+          <span className="font-mono text-xs">{statistic.year}</span>
+        </p>
+      </div>
+    </section>
+  );
+}

src/components/agentic-patterns/PatternBody.tsx

@@ -6,20 +6,28 @@
 // + Overview/Background disclosures by [slug]/page.tsx.
 //
 // Body slot order (top to bottom):
+//   0. Key statistic          — optional, callout above the diagram
 //   1. Diagram                — figure, no h2
+//   1b. afterDiagram slot     — e.g. RealizingDisclosure cards
+//   1c. Expert quote          — optional, semantic <blockquote>
 //   2. Decision matrix        — h2 "Decision" (replaces When-to-use + When-NOT)
+//   2b. Related questions     — optional, visible <dl> Q&A (unlocks FAQPage JSON-LD)
 //   3. In the wild            — h2, source/claim table
 //   4. Reader gotcha          — h2, optional, red-bordered callout
 //   5. Implementation sketch  — h2, denser pre, frameworks subsection
 //
-// Heading count: this body emits up to 4 h2s (Decision, In the wild,
-// Reader gotcha, Implementation sketch). Plus h2 from References + the
+// Heading count: this body emits up to 5 h2s (Decision, Common questions,
+// In the wild, Reader gotcha, Implementation sketch) plus optional sr-only
+// h2s on Key statistic and Expert quote. Plus h2 from References + the
 // disclosure summaries (which are NOT h2s — <summary> elements). The E2E
-// fixture must be updated.
+// fixture must be updated when relatedQuestions is populated for a pattern.
 
 import type { Framework, Pattern, SdkAvailability } from "@/data/agentic-design-patterns/types";
 import { MermaidDiagram } from "@/components/MermaidDiagram";
 import { DecisionMatrix } from "./DecisionMatrix";
+import { ExpertQuoteBlock } from "./ExpertQuoteBlock";
+import { KeyStatisticCallout } from "./KeyStatisticCallout";
+import { RelatedQuestionsBlock } from "./RelatedQuestionsBlock";
 import { SourcedClaimTable } from "./SourcedClaimTable";
 
 interface PatternBodyProps {
@@ -69,6 +77,11 @@ export function PatternBody({ pattern, afterDiagram }: PatternBodyProps) {
 
   return (
     <div className="flex flex-col gap-10">
+      {/* 0. Key statistic — optional above-fold callout */}
+      {pattern.keyStatistic && (
+        <KeyStatisticCallout statistic={pattern.keyStatistic} />
+      )}
+
       {/* 1. Diagram */}
       {pattern.mermaidSource && (
         <section>
@@ -87,9 +100,19 @@ export function PatternBody({ pattern, afterDiagram }: PatternBodyProps) {
       {/* 1b. Optional slot — e.g. RealizingDisclosure card sits here */}
       {afterDiagram}
 
+      {/* 1c. Expert quote — optional semantic <blockquote> */}
+      {pattern.expertQuote && (
+        <ExpertQuoteBlock quote={pattern.expertQuote} />
+      )}
+
       {/* 2. Decision matrix — replaces When-to-use + When-NOT */}
       <DecisionMatrix pattern={pattern} />
 
+      {/* 2b. Related questions — optional visible Q&A; unlocks FAQPage JSON-LD */}
+      {pattern.relatedQuestions && pattern.relatedQuestions.length > 0 && (
+        <RelatedQuestionsBlock questions={pattern.relatedQuestions} />
+      )}
+
       {/* 3. In the wild — source/claim table */}
       <SourcedClaimTable pattern={pattern} />
 

src/components/agentic-patterns/RelatedQuestionsBlock.tsx

@@ -0,0 +1,53 @@
+// ---------------------------------------------------------------------------
+// RelatedQuestionsBlock
+// ---------------------------------------------------------------------------
+// Renders a visible Q&A list as <dl>/<dt>/<dd>. Sits after the decision
+// matrix and before the "In the wild" table. Pairs 1:1 with the FAQPage
+// JSON-LD emitted from generateFaqPageSchema(): the questions and answers
+// in the JSON-LD must also be visible to the user so AI-search engines
+// (Perplexity, ChatGPT, Gemini, Google AI Overviews) can verify the
+// citation signal against rendered content — which means this component
+// must NOT be wrapped in <DisclosureSection>. Note: Google deprecated the
+// FAQ rich result in Search on 2026-05-07; the JSON-LD remains valuable as
+// an AI-search citation signal rather than a SERP enhancement. See
+// https://developers.google.com/search/docs/appearance/structured-data/faqpage.
+
+import type { Pattern } from "@/data/agentic-design-patterns/types";
+
+interface RelatedQuestionsBlockProps {
+  questions: NonNullable<Pattern["relatedQuestions"]>;
+}
+
+export function RelatedQuestionsBlock({ questions }: RelatedQuestionsBlockProps) {
+  if (questions.length === 0) return null;
+
+  return (
+    <section
+      id="common-questions"
+      aria-labelledby="common-questions-heading"
+      className="scroll-mt-24"
+    >
+      <h2
+        id="common-questions-heading"
+        className="font-mono text-nav font-semibold uppercase tracking-[0.08em] text-text-tertiary"
+      >
+        Common questions
+      </h2>
+      <dl className="mt-4 flex flex-col gap-4">
+        {questions.map((qa, idx) => (
+          <div
+            key={idx}
+            className="rounded-sm border border-border-subtle bg-surface px-4 py-3"
+          >
+            <dt className="text-body font-semibold text-text-primary [text-wrap:pretty]">
+              {qa.q}
+            </dt>
+            <dd className="mt-2 text-body leading-7 text-text-secondary [text-wrap:pretty]">
+              {qa.a}
+            </dd>
+          </div>
+        ))}
+      </dl>
+    </section>
+  );
+}

src/data/agentic-design-patterns/types.ts

@@ -136,6 +136,18 @@ export type Pattern = {
   implementationSketch: string // ~15 lines; TypeScript or pseudocode
   sdkAvailability: SdkAvailability
   readerGotcha?: { text: string; sourceUrl: string }
+  // -------------------------------------------------------------------------
+  // Citation-bait fields (optional; populated per-pattern in a follow-up).
+  // All three render visibly on the satellite page (NOT inside DisclosureSection)
+  // and feed schema.org signals. relatedQuestions additionally unlocks emission
+  // of FAQPage JSON-LD as a second top-level schema on the satellite page.
+  // -------------------------------------------------------------------------
+  /** Visible Q&A block rendered as <dl>; unlocks FAQPage JSON-LD emission. */
+  relatedQuestions?: { q: string; a: string }[]
+  /** Above-fold quantitative claim rendered as a callout; cites a public source. */
+  keyStatistic?: { claim: string; sourceUrl: string; year: number }
+  /** Authoritative quote rendered as a semantic <blockquote>; attribution links to source. */
+  expertQuote?: { text: string; attribution: string; sourceUrl: string }
   relatedSlugs: string[]      // 2-4 cross-link chips; build fails if any don't resolve
   frameworks: Framework[]
   references: Reference[]     // 3-7 references