@prenta/admin 1.16.0 → 1.17.0

package/src/components/seo/FaqProposalPreview.tsx

@@ -0,0 +1,134 @@
+'use client'
+
+/**
+ * Expanded-row body for an `add-section` (FAQ) proposal in the SEO inbox:
+ * the signal that earned the page a proposal, an editable section heading,
+ * and one checkbox per drafted question so the reviewer can drop weak ones
+ * before approving. Fully controlled — the tab owns the draft.
+ */
+import { MessageCircleQuestionMark } from 'lucide-react'
+import { useId } from 'react'
+import type { SeoFaqSignals } from '../../lib/seo-service.js'
+
+/** Server-enforced floor: a FAQ section with one question is not a FAQ. */
+export const FAQ_MIN_SELECTED = 2
+/** Mirrors core's `FAQ_HEADING_MAX` (measured after trim). */
+export const FAQ_HEADING_MAX = 80
+/** The window core aggregates FAQ signals over (`FAQ_SIGNAL_WINDOW_DAYS`). */
+const SIGNAL_WINDOW_DAYS = 28
+
+export interface FaqProposalPreviewItem {
+  question: string
+  answer: string
+  /** Verbatim page quote the answer was grounded in; omit / `''` when none survived. */
+  sourceQuote?: string
+}
+
+export interface FaqProposalPreviewProps {
+  /** The heading the AI drafted (shown as the input's placeholder). */
+  heading: string
+  items: FaqProposalPreviewItem[]
+  signals: SeoFaqSignals | null
+  /** Controlled; parallel to `items`. */
+  selected: boolean[]
+  onToggle: (index: number) => void
+  /** Controlled heading field value. */
+  headingValue: string
+  onHeadingChange: (value: string) => void
+  disabled?: boolean
+}
+
+/**
+ * One-line "why this page" summary: referral citations win over retrieval
+ * fetches, and the top question-shaped query is appended when present.
+ * Engine names are rendered as the server sends them (registry display names).
+ */
+export function faqSignalLine(signals: SeoFaqSignals | null): string | null {
+  if (!signals) return null
+  const parts: string[] = []
+  const g = signals.geo
+  const engines = g?.engines.join(', ') || 'AI engines'
+  if (g && g.referralVisits > 0) {
+    parts.push(`Cited by ${engines} ${g.referralVisits}× in ${SIGNAL_WINDOW_DAYS} days`)
+  } else if (g && g.retrievalHits > 0) {
+    parts.push(`Fetched by ${engines} ${g.retrievalHits}× in ${SIGNAL_WINDOW_DAYS} days`)
+  }
+  const q = signals.queries[0]
+  if (q) parts.push(`asked "${q.query}" ${q.impressions}× on Google`)
+  return parts.length > 0 ? parts.join(' · ') : null
+}
+
+/**
+ * Why the current draft cannot be approved, or `null` when it can. Shared by
+ * the status line below and the tab's Approve buttons so both agree. The
+ * heading is deliberately not a blocker: a blank field means "use the drafted
+ * heading" (the input's placeholder), and the tab sends no override.
+ */
+export function faqDraftBlocker(selected: boolean[]): string | null {
+  const count = selected.filter(Boolean).length
+  if (count < FAQ_MIN_SELECTED) {
+    return `Select at least ${FAQ_MIN_SELECTED} questions to approve (${count} selected).`
+  }
+  return null
+}
+
+export function FaqProposalPreview(props: FaqProposalPreviewProps) {
+  const headingId = useId()
+  const selectedCount = props.selected.filter(Boolean).length
+  const line = faqSignalLine(props.signals)
+  const blocker = faqDraftBlocker(props.selected)
+  return (
+    <div className="space-y-4">
+      {line ? (
+        <p className="text-muted-foreground flex items-center gap-2 text-sm">
+          <MessageCircleQuestionMark size={16} aria-hidden="true" />
+          <span>{line}</span>
+        </p>
+      ) : null}
+      <div className="space-y-1">
+        <label htmlFor={headingId} className="text-foreground block text-sm font-medium">
+          Section heading
+        </label>
+        <input
+          id={headingId}
+          type="text"
+          value={props.headingValue}
+          placeholder={props.heading}
+          maxLength={FAQ_HEADING_MAX}
+          disabled={props.disabled}
+          onChange={(e) => props.onHeadingChange(e.target.value)}
+          className="bg-input-background text-foreground border-border focus-visible:ring-ring w-full max-w-md rounded-md border px-3 py-2 text-sm focus-visible:ring-2 focus-visible:outline-none disabled:opacity-60"
+        />
+      </div>
+      <ul className="divide-border divide-y" aria-label="Proposed questions">
+        {props.items.map((item, i) => {
+          const id = `${headingId}-item-${i}`
+          return (
+            <li key={id} className="flex gap-3 py-3">
+              <input
+                id={id}
+                type="checkbox"
+                checked={props.selected[i] ?? true}
+                disabled={props.disabled}
+                onChange={() => props.onToggle(i)}
+                className="border-border text-primary focus-visible:ring-ring mt-1 h-4 w-4 shrink-0 rounded"
+              />
+              <div className="min-w-0 space-y-1">
+                <label htmlFor={id} className="text-foreground block text-sm font-medium">
+                  {item.question}
+                </label>
+                <p className="text-foreground text-sm">{item.answer}</p>
+                {item.sourceQuote ? (
+                  <p className="text-muted-foreground text-sm">Source: “{item.sourceQuote}”</p>
+                ) : null}
+              </div>
+            </li>
+          )
+        })}
+      </ul>
+      <p role="status" className="text-muted-foreground text-sm">
+        {blocker ?? `${selectedCount} of ${props.items.length} questions will be added.`}
+      </p>
+    </div>
+  )
+}

package/src/components/seo/SeoIssueFixPanel.tsx

@@ -24,6 +24,9 @@ import { PlanUpgradeCallout } from '../PlanUpgradeCallout.js'
 import { ChangePreview } from './ChangePreview.js'
 import { SeoErrorState, btnPrimary, btnSecondary } from './primitives.js'
 
+// Redirect suggestions always carry `fixStrategy: 'redirect'` (core
+// `issue-fix-redirect.ts`); an undefined strategy is a metadata / schema patch
+// (meta title, description, canonical, structured data, FAQPage node).
 function approveButtonLabel(strategy: SeoIssueFixSuggestion['fixStrategy']): string {
   switch (strategy) {
     case 'fix-link':
@@ -31,8 +34,9 @@ function approveButtonLabel(strategy: SeoIssueFixSuggestion['fixStrategy']): str
     case 'insert-link':
       return 'Approve link'
     case 'redirect':
-    case undefined:
       return 'Approve redirect'
+    case undefined:
+      return 'Approve fix'
     default: {
       const _exhaustive: never = strategy
       return _exhaustive
@@ -47,8 +51,9 @@ function approveSuccessToast(strategy: SeoIssueFixSuggestion['fixStrategy']): st
     case 'insert-link':
       return 'Link added and issue resolved.'
     case 'redirect':
-    case undefined:
       return 'Redirect created and issue resolved.'
+    case undefined:
+      return 'Fix applied and issue resolved.'
     default: {
       const _exhaustive: never = strategy
       return _exhaustive

package/src/lib/seo-service.ts

@@ -501,15 +501,30 @@ export async function fetchSeoIssueFixSuggestion(issueId: string): Promise<{
   return { suggestion: res.data?.suggestion }
 }
 
+/**
+ * Per-approval refinements for an `add-section` (FAQ) fix. Both are ignored by
+ * the server for every other fix strategy.
+ */
+export interface SeoApplyFixOptions {
+  /** Indices into `section.content.items` to keep; the server requires at least two. */
+  includeItems?: number[]
+  /** Replacement section heading (server trims, then enforces `FAQ_HEADING_MAX`, mirrored from core). */
+  headingOverride?: string
+}
+
 export async function applySeoIssueFix(
   issueId: string,
   fingerprint: string,
+  opts?: SeoApplyFixOptions,
 ): Promise<{ issue?: SeoIssue; error?: string }> {
+  const body: Record<string, unknown> = { fingerprint }
+  if (opts?.includeItems) body.includeItems = opts.includeItems
+  if (opts?.headingOverride !== undefined) body.headingOverride = opts.headingOverride
   const res = await cmsApi<{ issue: SeoIssue }>(
     `/seo/issues/${encodeURIComponent(issueId)}/apply-fix`,
     {
       method: 'POST',
-      body: JSON.stringify({ fingerprint }),
+      body: JSON.stringify(body),
     },
   )
   if (res.error) return { error: res.error }
@@ -561,6 +576,7 @@ export const SEO_INLINE_FIX_ISSUE_TYPES = new Set([
   'duplicate-meta-title',
   'duplicate-meta-description',
   'missing-structured-data',
+  'faq-schema-missing',
   'broken-internal-link',
   'orphan-page',
 ])
@@ -843,6 +859,7 @@ export type SeoAutopilotIssueType =
   | 'missing-canonical'
   | 'accidental-noindex'
   | 'missing-structured-data'
+  | 'faq-schema-missing'
   | 'redirect'
 
 export const SEO_AUTOPILOT_ISSUE_TYPES: readonly SeoAutopilotIssueType[] = [
@@ -855,6 +872,7 @@ export const SEO_AUTOPILOT_ISSUE_TYPES: readonly SeoAutopilotIssueType[] = [
   'missing-canonical',
   'accidental-noindex',
   'missing-structured-data',
+  'faq-schema-missing',
   'redirect',
 ]
 
@@ -1747,6 +1765,28 @@ export async function fetchLinkHealthIssues(): Promise<{
 }
 
 // ─── AI proposals inbox ─────────────────────────────────────────────────
+// Mirrors `packages/cms-core/src/seo/proposals.ts` (`SeoProposal`) and
+// `seo/faq-signals.ts` (`FaqSignals`). The server is the contract.
+
+/** Same union as core's `SeoProposalFixStrategy`; `null` for plain metadata writes. */
+export type SeoProposalFixStrategy = 'redirect' | 'fix-link' | 'insert-link' | 'add-section'
+
+/** Why a page got a `missing-faq` proposal (28-day window). */
+export interface SeoFaqSignals {
+  /**
+   * Answer-engine activity. `engines` carries the referrer registry's display
+   * names (`ChatGPT`, `Perplexity`, …), sorted; empty when only retrieval
+   * crawls were seen.
+   */
+  geo: { referralVisits: number; retrievalHits: number; engines: string[] } | null
+  /** Question-shaped Search Console queries, highest impressions first. */
+  queries: Array<{ query: string; impressions: number; clicks: number }>
+}
+
+export interface SeoFaqSectionDraft {
+  sectionType: 'faq'
+  content: { heading: string; items: Array<{ question: string; answer: string }> }
+}
 
 export interface SeoProposal {
   /** `issue:<issueId>` | `redirect:<suggestionId>` */
@@ -1770,6 +1810,22 @@ export interface SeoProposal {
   severity: SeoSeverity | null
   issueId: string | null
   suggestionId: string | null
+  /** Always `'redirect'` for redirect rows; `null` when the cached patch carries none. */
+  fixStrategy: SeoProposalFixStrategy | null
+  /**
+   * `add-section` only: the section approval will insert. `null` when the
+   * cached patch failed core's structural checks — the row must still render
+   * (badge + signals) but cannot be approved from the inbox.
+   */
+  section: SeoFaqSectionDraft | null
+  /**
+   * `add-section` only: verbatim page quotes parallel to `section.content.items`.
+   * A malformed row arrives as `sourceQuote: ''` — render as "no quote", never
+   * as an empty blockquote.
+   */
+  grounding: Array<{ sourceQuote: string }> | null
+  /** `missing-faq` only. */
+  signals: SeoFaqSignals | null
 }
 
 export interface SeoProposalsPayload {

package/src/views/seo/ProposalsTab.tsx

@@ -5,9 +5,11 @@
  * in one review surface. Batch approve honours server governance
  * (`allowBulkApply`); the UI only pre-disables the button using the flags the
  * list payload exposes. Generation is human-triggered, capped per pass, and
- * loops client-side while the server reports `remaining > 0`.
+ * loops client-side while the server reports `remaining > 0`. FAQ
+ * (`add-section`) rows expand into a per-question preview and approve one at
+ * a time through `apply-fix`; in a batch they apply the whole drafted section.
  */
-import { useCallback, useEffect, useMemo, useRef, useState } from 'react'
+import { useCallback, useEffect, useId, useMemo, useRef, useState, type ReactNode } from 'react'
 import {
   AlertTriangle,
   ArrowRightLeft,
@@ -22,11 +24,13 @@ import {
 } from 'lucide-react'
 import { toast } from 'sonner'
 import {
+  applySeoIssueFix,
   bulkApplySeoProposals,
   dismissRedirectSuggestion,
   dismissSeoIssueFix,
   fetchSeoProposals,
   generateSeoProposals,
+  type SeoApplyFixOptions,
   type SeoProposal,
   type SeoProposalBulkApplyItem,
   type SeoProposalsPayload,
@@ -35,6 +39,11 @@ import { hasPlanFeature, type PlanInfo } from '../../lib/plan.js'
 import { brandAlignmentLabel, brandAlignmentTone } from '../../lib/brand-voice-client.js'
 import { PlanUpgradeCallout } from '../../components/PlanUpgradeCallout.js'
 import { ChangePreview } from '../../components/seo/ChangePreview.js'
+import {
+  FaqProposalPreview,
+  faqDraftBlocker,
+  faqSignalLine,
+} from '../../components/seo/FaqProposalPreview.js'
 import {
   SectionCard,
   SeoEmptyState,
@@ -76,6 +85,77 @@ function toBulkItem(p: SeoProposal): SeoProposalBulkApplyItem {
     : { kind: 'issue-fix', id: p.issueId ?? '', fingerprint: p.fingerprint ?? undefined }
 }
 
+/** An `add-section` (FAQ) proposal; `p.section` may still be `null` when the cache was unreadable. */
+function isFaqProposal(p: SeoProposal): boolean {
+  return p.fixStrategy === 'add-section'
+}
+
+/**
+ * Reviewer edits to a FAQ proposal before approval. `selected` is parallel to
+ * `section.content.items`; `heading` is the raw input value (trimmed on send).
+ */
+interface FaqDraft {
+  selected: boolean[]
+  heading: string
+}
+
+/**
+ * Drafts are keyed by the drafted content, not just the issue: `fingerprint`
+ * tracks the page (`updatedAt`), so dismiss + regenerate on an unchanged page
+ * keeps the same id and fingerprint while the questions change. Folding the
+ * questions (and `generatedAt`) into the key makes a regenerated proposal
+ * start clean instead of inheriting stale ticks or a stale heading edit.
+ */
+function faqDraftKey(p: SeoProposal): string {
+  const questions = p.section?.content.items.map((i) => i.question).join('\u0001') ?? ''
+  return `${p.id}:${p.generatedAt ?? ''}:${questions}`
+}
+
+function initialFaqDraft(p: SeoProposal): FaqDraft {
+  const section = p.section
+  return {
+    selected: section ? section.content.items.map(() => true) : [],
+    heading: section?.content.heading ?? '',
+  }
+}
+
+/**
+ * The row's stored draft when it still fits the section (one `selected` flag
+ * per item), otherwise the untouched default. Every reader *and* writer goes
+ * through this so a mismatched draft is replaced rather than mutated.
+ */
+function currentFaqDraft(drafts: Record<string, FaqDraft>, p: SeoProposal): FaqDraft {
+  const draft = drafts[faqDraftKey(p)]
+  if (draft && draft.selected.length === (p.section?.content.items.length ?? 0)) return draft
+  return initialFaqDraft(p)
+}
+
+/**
+ * Body of the single-row `apply-fix` call. `includeItems` only when the
+ * reviewer dropped a question; `headingOverride` only when the trimmed heading
+ * is non-empty and differs from the draft — so an untouched row sends exactly
+ * `{ fingerprint }`, the same request the Audit tab makes.
+ */
+function faqApplyOptions(p: SeoProposal, draft: FaqDraft): SeoApplyFixOptions {
+  const opts: SeoApplyFixOptions = {}
+  const includeItems = draft.selected.flatMap((on, i) => (on ? [i] : []))
+  if (includeItems.length < draft.selected.length) opts.includeItems = includeItems
+  const heading = draft.heading.trim()
+  if (heading !== '' && heading !== p.section?.content.heading) opts.headingOverride = heading
+  return opts
+}
+
+/** Change-column text for a FAQ row: question count plus the strongest signal. */
+function faqSummary(p: SeoProposal): string {
+  const signal = faqSignalLine(p.signals)
+  if (!p.section) return signal ?? p.justification
+  const count = plural(p.section.content.items.length, 'question')
+  return signal ? `${count} · ${signal}` : count
+}
+
+const FAQ_UNREADABLE_HINT =
+  'The drafted section could not be read from the cache. Dismiss this proposal and generate again to get a fresh draft.'
+
 function BrandScoreBadge({ score }: { score: number }) {
   return (
     <span
@@ -187,6 +267,8 @@ export function ProposalsTab({
   const [confirmGenerate, setConfirmGenerate] = useState(false)
   const [mutation, setMutation] = useState<Mutation | null>(null)
   const [pendingItems, setPendingItems] = useState<SeoProposalBulkApplyItem[]>([])
+  /** Per-row FAQ review edits, created lazily on first interaction (see `faqDraftKey`). */
+  const [faqDrafts, setFaqDrafts] = useState<Record<string, FaqDraft>>({})
   const [generating, setGenerating] = useState<{ done: number; total: number } | null>(null)
   /** Bumped after every mutation so the autopilot ledger below refetches with the inbox. */
   const [refreshKey, setRefreshKey] = useState(0)
@@ -305,6 +387,70 @@ export function ProposalsTab({
     [afterMutation, beginMutation, endMutation],
   )
 
+  /** The row's current draft, or the untouched default when the reviewer has not edited it. */
+  const faqDraftFor = useCallback(
+    (p: SeoProposal): FaqDraft => currentFaqDraft(faqDrafts, p),
+    [faqDrafts],
+  )
+  const toggleFaqItem = useCallback((p: SeoProposal, index: number) => {
+    setFaqDrafts((cur) => {
+      const base = currentFaqDraft(cur, p)
+      const selected = base.selected.map((on, i) => (i === index ? !on : on))
+      return { ...cur, [faqDraftKey(p)]: { ...base, selected } }
+    })
+  }, [])
+  const setFaqHeading = useCallback((p: SeoProposal, heading: string) => {
+    setFaqDrafts((cur) => ({ ...cur, [faqDraftKey(p)]: { ...currentFaqDraft(cur, p), heading } }))
+  }, [])
+
+  // Drop drafts whose proposal is gone or was regenerated, so the map cannot grow across refetches.
+  useEffect(() => {
+    const liveKeys = new Set(proposals.filter(isFaqProposal).map(faqDraftKey))
+    setFaqDrafts((cur) => {
+      const stale = Object.keys(cur).filter((key) => !liveKeys.has(key))
+      if (stale.length === 0) return cur
+      const next = { ...cur }
+      for (const key of stale) delete next[key]
+      return next
+    })
+  }, [proposals])
+
+  /**
+   * Single-row approve for a FAQ proposal. Goes through `apply-fix` (not
+   * bulk-apply) so the reviewer's per-question selection and heading edit are
+   * honoured; the bulk path applies the whole drafted section unchanged.
+   */
+  const handleApproveFaq = useCallback(
+    async (p: SeoProposal) => {
+      if (!p.issueId || !p.fingerprint || !p.section) return
+      const draft = faqDraftFor(p)
+      if (faqDraftBlocker(draft.selected) !== null) return
+      if (!beginMutation('apply')) return
+      try {
+        const res = await applySeoIssueFix(p.issueId, p.fingerprint, faqApplyOptions(p, draft))
+        if (!mountedRef.current) return
+        if (res.error) {
+          toast.error(res.error)
+          return
+        }
+        toast.success('FAQ section added.')
+        setFaqDrafts((cur) => {
+          const key = faqDraftKey(p)
+          if (!(key in cur)) return cur
+          const rest = { ...cur }
+          delete rest[key]
+          return rest
+        })
+        afterMutation()
+      } catch (err) {
+        if (mountedRef.current) toast.error(errorMessage(err))
+      } finally {
+        endMutation()
+      }
+    },
+    [afterMutation, beginMutation, endMutation, faqDraftFor],
+  )
+
   const handleDismissSelected = useCallback(async () => {
     const targets = selectedProposals
     if (targets.length === 0) return
@@ -573,6 +719,41 @@ export function ProposalsTab({
                 <tbody className="divide-border divide-y">
                   {proposals.map((p) => {
                     const first = p.changes[0]
+                    const canApply = inlineApplyEnabled || p.kind === 'redirect'
+                    if (isFaqProposal(p)) {
+                      const draft = faqDraftFor(p)
+                      const blocker = p.section
+                        ? faqDraftBlocker(draft.selected)
+                        : FAQ_UNREADABLE_HINT
+                      return (
+                        <ProposalRow
+                          key={p.id}
+                          proposal={p}
+                          selected={selected.has(p.id)}
+                          expanded={expanded.has(p.id)}
+                          summary={faqSummary(p)}
+                          onToggleSelect={() => toggleSelect(p.id)}
+                          onToggleExpanded={() => toggleExpanded(p.id)}
+                          onApprove={() => void handleApproveFaq(p)}
+                          onDismiss={() => void handleDismissOne(p)}
+                          busy={busy}
+                          canApply={canApply}
+                          approveBlocker={blocker}
+                          details={
+                            <FaqProposalDetails
+                              proposal={p}
+                              draft={draft}
+                              blocker={blocker}
+                              busy={busy}
+                              canApply={canApply}
+                              onToggle={(i) => toggleFaqItem(p, i)}
+                              onHeadingChange={(h) => setFaqHeading(p, h)}
+                              onApprove={() => void handleApproveFaq(p)}
+                            />
+                          }
+                        />
+                      )
+                    }
                     return (
                       <ProposalRow
                         key={p.id}
@@ -589,7 +770,7 @@ export function ProposalsTab({
                         onApprove={() => void runApply([toBulkItem(p)])}
                         onDismiss={() => void handleDismissOne(p)}
                         busy={busy}
-                        canApply={inlineApplyEnabled || p.kind === 'redirect'}
+                        canApply={canApply}
                       />
                     )
                   })}
@@ -637,6 +818,8 @@ function ProposalRow({
   onDismiss,
   busy,
   canApply,
+  approveBlocker = null,
+  details,
 }: {
   proposal: SeoProposal
   selected: boolean
@@ -648,7 +831,16 @@ function ProposalRow({
   onDismiss: () => void
   busy: boolean
   canApply: boolean
+  /**
+   * Why the row-level Approve is disabled (FAQ rows). Exposed as the button's
+   * tooltip and accessible description so the reason is available while the
+   * row is collapsed, not only in the expanded body.
+   */
+  approveBlocker?: string | null
+  /** Replaces the default before/after table in the expanded row. */
+  details?: ReactNode
 }) {
+  const approveHintId = `${useId()}-approve-hint`
   return (
     <>
       <tr className={`${selected ? 'bg-accent/30' : ''} hover:bg-accent/20 transition-colors`}>
@@ -666,6 +858,7 @@ function ProposalRow({
         <td className="px-3 py-3 align-top">
           <div className="flex flex-wrap items-center gap-2">
             <span className="text-foreground font-medium">{p.title}</span>
+            {isFaqProposal(p) ? <SeoStatusBadge label="FAQ section" tone="neutral" /> : null}
             {p.severity ? (
               <SeoStatusBadge
                 label={p.severity}
@@ -724,15 +917,24 @@ function ProposalRow({
         <td className="px-3 py-3 align-top">
           <div className="flex items-center justify-end gap-1">
             {!p.stale && canApply ? (
-              <button
-                type="button"
-                onClick={onApprove}
-                disabled={busy}
-                className="text-success hover:bg-accent focus-visible:ring-ring rounded-md p-1.5 focus-visible:ring-2 focus-visible:outline-none disabled:opacity-60"
-                aria-label={`Approve ${p.title}`}
-              >
-                <Check className="h-4 w-4" aria-hidden />
-              </button>
+              <>
+                <button
+                  type="button"
+                  onClick={onApprove}
+                  disabled={busy || approveBlocker !== null}
+                  className="text-success hover:bg-accent focus-visible:ring-ring rounded-md p-1.5 focus-visible:ring-2 focus-visible:outline-none disabled:opacity-60"
+                  aria-label={`Approve ${p.title}`}
+                  title={approveBlocker ?? undefined}
+                  aria-describedby={approveBlocker ? approveHintId : undefined}
+                >
+                  <Check className="h-4 w-4" aria-hidden />
+                </button>
+                {approveBlocker ? (
+                  <span id={approveHintId} className="sr-only">
+                    {approveBlocker}
+                  </span>
+                ) : null}
+              </>
             ) : null}
             <button
               type="button"
@@ -751,7 +953,7 @@ function ProposalRow({
           <td colSpan={6} className="bg-muted/30 px-4 py-4">
             <div className="space-y-3">
               <p className="text-foreground text-sm">{p.justification}</p>
-              <ChangePreview changes={p.changes} />
+              {details ?? <ChangePreview changes={p.changes} />}
             </div>
           </td>
         </tr>
@@ -759,3 +961,67 @@ function ProposalRow({
     </>
   )
 }
+
+/**
+ * Expanded body of a FAQ row: the per-question preview plus a reviewed
+ * Approve button. When core could not read the cached section the row shows
+ * the recovery hint instead of a preview and offers no approve at all.
+ */
+function FaqProposalDetails({
+  proposal: p,
+  draft,
+  blocker,
+  busy,
+  canApply,
+  onToggle,
+  onHeadingChange,
+  onApprove,
+}: {
+  proposal: SeoProposal
+  draft: FaqDraft
+  blocker: string | null
+  busy: boolean
+  canApply: boolean
+  onToggle: (index: number) => void
+  onHeadingChange: (value: string) => void
+  onApprove: () => void
+}) {
+  const section = p.section
+  if (!section) {
+    return (
+      <p className="text-muted-foreground flex items-start gap-2 text-sm">
+        <AlertTriangle className="text-warning mt-0.5 h-4 w-4 shrink-0" aria-hidden />
+        <span>{FAQ_UNREADABLE_HINT}</span>
+      </p>
+    )
+  }
+  const items = section.content.items.map((item, i) => ({
+    ...item,
+    sourceQuote: p.grounding?.[i]?.sourceQuote || undefined,
+  }))
+  return (
+    <div className="space-y-4">
+      <FaqProposalPreview
+        heading={section.content.heading}
+        items={items}
+        signals={p.signals}
+        selected={draft.selected}
+        onToggle={onToggle}
+        headingValue={draft.heading}
+        onHeadingChange={onHeadingChange}
+        disabled={busy}
+      />
+      {!p.stale && canApply ? (
+        <button
+          type="button"
+          className={btnPrimary}
+          onClick={onApprove}
+          disabled={busy || blocker !== null}
+        >
+          <Check className="h-4 w-4" aria-hidden />
+          Approve
+        </button>
+      ) : null}
+    </div>
+  )
+}

package/src/views/settings/SeoAutopilotCard.tsx

@@ -120,6 +120,12 @@ export const AUTOPILOT_TYPE_GROUPS: ReadonlyArray<{
         help: 'Adds the collection’s default Schema.org type.',
         producer: 'Rule-based',
       },
+      {
+        id: 'faq-schema-missing',
+        label: 'FAQ schema for visible FAQ sections',
+        help: 'Adds a FAQPage node to a page’s stored structured data when a visible FAQ section has none — typically pages published before the section was added. Re-publishing the page clears it too.',
+        producer: 'Rule-based',
+      },
     ],
   },
   {