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

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

src/lib/hooks/before-change-dedicated-date-modified.ts

@@ -0,0 +1,58 @@
+import type { CollectionBeforeChangeHook } from 'payload'
+
+/**
+ * Payload beforeChange hook for the Posts collection.
+ *
+ * Maintains `dedicatedDateModified` as a deliberate signal of meaningful
+ * content changes — independent of Payload's auto-updated `updatedAt`,
+ * which fires on every admin save (toggling featured flag, swapping a tag,
+ * etc.). Used by `generateBlogPostingSchema` as the canonical
+ * `BlogPosting.dateModified` value.
+ *
+ * Semantics:
+ *   - create operations: pass through unchanged (the post is new; an editor
+ *     can fill `dedicatedDateModified` manually or leave it null).
+ *   - update operations: Payload's `data` partial only contains fields the
+ *     editor actually touched in this save, so presence of the key in
+ *     `data` is the correct test for "editor set this field explicitly".
+ *     - If `dedicatedDateModified` IS in the partial → respect the editor
+ *       value, return data unchanged.
+ *     - Else if `body`, `title`, or `summary` is in the partial (meaningful
+ *       content changed) → stamp `data.dedicatedDateModified` with the
+ *       current ISO timestamp.
+ *     - Else → no-op (non-content field change like `featured`).
+ *
+ * The hook is non-blocking: it never throws and never rejects a save.
+ */
+const MEANINGFUL_FIELDS = ['body', 'title', 'summary'] as const
+
+export const beforeChangeDedicatedDateModified: CollectionBeforeChangeHook = ({
+  data,
+  operation,
+}) => {
+  if (operation === 'create') {
+    return data
+  }
+
+  // Payload's `data` on update is a partial containing only the fields the
+  // editor changed. Presence of the key is the correct signal that the
+  // editor set the field explicitly — a value-vs-originalDoc comparison
+  // would treat any unchanged save as an editor override.
+  const editorSetField = data != null && 'dedicatedDateModified' in data
+
+  if (editorSetField) {
+    return data
+  }
+
+  const meaningfulContentChanged =
+    data != null && MEANINGFUL_FIELDS.some((field) => field in data)
+
+  if (meaningfulContentChanged) {
+    return {
+      ...data,
+      dedicatedDateModified: new Date().toISOString(),
+    }
+  }
+
+  return data
+}

src/lib/schema/blog-posting.ts

@@ -60,15 +60,11 @@ export function generateBlogPostingSchema(post: Post): BlogPostingSchema {
       ? post.references.map(mapReferenceToCitation)
       : undefined;
 
-  // dateModified: Post.updatedAt is always present (Payload sets it on every save).
-  // It is a proxy for dateModified — accurate for content changes, but also updates
-  // on non-content admin saves (e.g., toggling featured flag, changing tags).
-  //
-  // TODO: Replace post.updatedAt with post.dateModified when the dedicated
-  // dateModified field is added to the Posts collection (SEO impl plan item 1).
-  // The field should use a beforeChange hook that only fires on body/title/summary
-  // field changes, not on status or admin field changes.
-  const dateModified = post.updatedAt;
+  // dateModified: prefer the deliberate `dedicatedDateModified` signal, which a
+  // beforeChange hook (src/lib/hooks/before-change-dedicated-date-modified.ts)
+  // stamps only when `body`, `title`, or `summary` actually change. Falls back
+  // to Payload's auto-updated `updatedAt` for posts that pre-date the field.
+  const dateModified = post.dedicatedDateModified ?? post.updatedAt;
 
   // Build the schema object. Required fields are always present.
   // Optional fields use conditional assignment to avoid undefined-valued keys