From 3bc8cea40d11901c7fcd5b0ce2c29be62d062186 Mon Sep 17 00:00:00 2001
From: DavidBabinec <hello@davidbabinec.com>
Date: Fri, 12 Jun 2026 12:18:00 +0200
Subject: [PATCH 01/26] feat(seo): core SEO model, resolver, JSON-LD, robots
 generation

New @core/seo engine module: persisted schemas (SeoMetadata, SiteSeoSettings),
two-stage title resolver shared by publisher/admin/server, JSON-LD builders
(WebSite/Organization/Article/BreadcrumbList) with safe serialization,
robots.txt generation with AI-crawler group controls, health indicators,
and pixel-width length meters.

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
---
 .../no-core-barrel-deep-imports.test.ts       |   2 +
 src/core/seo/__tests__/health.test.ts         |  42 ++++
 src/core/seo/__tests__/jsonLd.test.ts         | 117 +++++++++++
 src/core/seo/__tests__/resolve.test.ts        | 174 ++++++++++++++++
 src/core/seo/__tests__/robots.test.ts         |  51 +++++
 src/core/seo/aiCrawlers.ts                    |  26 +++
 src/core/seo/health.ts                        |  62 ++++++
 src/core/seo/index.ts                         |  59 ++++++
 src/core/seo/jsonLd.ts                        | 121 +++++++++++
 src/core/seo/lengthMeter.ts                   |  50 +++++
 src/core/seo/resolve.ts                       | 196 ++++++++++++++++++
 src/core/seo/robots.ts                        |  41 ++++
 src/core/seo/schema.ts                        | 124 +++++++++++
 13 files changed, 1065 insertions(+)
 create mode 100644 src/core/seo/__tests__/health.test.ts
 create mode 100644 src/core/seo/__tests__/jsonLd.test.ts
 create mode 100644 src/core/seo/__tests__/resolve.test.ts
 create mode 100644 src/core/seo/__tests__/robots.test.ts
 create mode 100644 src/core/seo/aiCrawlers.ts
 create mode 100644 src/core/seo/health.ts
 create mode 100644 src/core/seo/index.ts
 create mode 100644 src/core/seo/jsonLd.ts
 create mode 100644 src/core/seo/lengthMeter.ts
 create mode 100644 src/core/seo/resolve.ts
 create mode 100644 src/core/seo/robots.ts
 create mode 100644 src/core/seo/schema.ts

diff --git a/src/__tests__/architecture/no-core-barrel-deep-imports.test.ts b/src/__tests__/architecture/no-core-barrel-deep-imports.test.ts
index 6ee37600c..8cf047c6d 100644
--- a/src/__tests__/architecture/no-core-barrel-deep-imports.test.ts
+++ b/src/__tests__/architecture/no-core-barrel-deep-imports.test.ts
@@ -10,6 +10,7 @@
  *   - `@core/framework`
  *   - `@core/framework-schema`
  *   - `@core/fonts`
+ *   - `@core/seo`
  *
  * Per the barrel convention (CLAUDE.md → "Barrel imports"): everything OUTSIDE
  * a module imports through its barrel; files INSIDE the module import each
@@ -36,6 +37,7 @@ const BARRELLED_MODULES = [
   'framework',
   'framework-schema',
   'fonts',
+  'seo',
 ]
 
 // Scan production + test sources in both the app and the server.
diff --git a/src/core/seo/__tests__/health.test.ts b/src/core/seo/__tests__/health.test.ts
new file mode 100644
index 000000000..89b3bc542
--- /dev/null
+++ b/src/core/seo/__tests__/health.test.ts
@@ -0,0 +1,42 @@
+import { describe, expect, test } from 'bun:test'
+import { computeSeoHealth } from '../health'
+import { resolveSeoMetadata } from '../resolve'
+import { approxPixelWidth, meterZone, TITLE_PIXEL_BUDGET } from '../lengthMeter'
+
+const BASE = { siteName: 'Acme', routeKind: 'page' as const, routePath: '/about' }
+
+describe('computeSeoHealth', () => {
+  test('healthy target has zero issues', () => {
+    const target = {
+      title: 'Nice short title',
+      description: 'A reasonable description for the page.',
+      ogImage: '/img.png',
+      ogImageAlt: 'An image',
+    }
+    const health = computeSeoHealth(target, resolveSeoMetadata({ ...BASE, target }))
+    expect(health).toEqual({
+      title: 'ok',
+      description: 'ok',
+      image: 'ok',
+      indexable: true,
+      issueCount: 0,
+    })
+  })
+
+  test('flags missing description, image, alt, and noindex', () => {
+    const target = { title: 'T', noindex: true, ogImage: '/img.png' }
+    const health = computeSeoHealth(target, resolveSeoMetadata({ ...BASE, target }))
+    expect(health.description).toBe('missing')
+    expect(health.image).toBe('missingAlt')
+    expect(health.indexable).toBe(false)
+    expect(health.issueCount).toBe(3)
+  })
+
+  test('flags over-budget title as long', () => {
+    const longTitle = 'Wide MMMM Words '.repeat(8)
+    expect(meterZone(approxPixelWidth(longTitle), TITLE_PIXEL_BUDGET)).toBe('over')
+    const target = { title: longTitle }
+    const health = computeSeoHealth(target, resolveSeoMetadata({ ...BASE, target }))
+    expect(health.title).toBe('long')
+  })
+})
diff --git a/src/core/seo/__tests__/jsonLd.test.ts b/src/core/seo/__tests__/jsonLd.test.ts
new file mode 100644
index 000000000..d5beda730
--- /dev/null
+++ b/src/core/seo/__tests__/jsonLd.test.ts
@@ -0,0 +1,117 @@
+import { describe, expect, test } from 'bun:test'
+import { buildJsonLdEntities, serializeJsonLd } from '../jsonLd'
+import { resolveSeoMetadata } from '../resolve'
+
+const ORIGIN = 'https://acme.com'
+
+function resolvedFor(routePath: string, kind: 'page' | 'row', extra = {}) {
+  return resolveSeoMetadata({
+    siteName: 'Acme',
+    routeKind: kind,
+    routePath,
+    origin: ORIGIN,
+    baseTitle: 'Hello',
+    ...extra,
+  })
+}
+
+describe('buildJsonLdEntities', () => {
+  test('homepage emits WebSite, and Organization when configured', () => {
+    const entities = buildJsonLdEntities(resolvedFor('/', 'page'), {
+      kind: 'page',
+      routePath: '/',
+      origin: ORIGIN,
+      siteName: 'Acme',
+      organization: { name: 'Acme Inc', logoUrl: 'https://acme.com/logo.png' },
+    })
+    const types = entities.map((e) => e['@type'])
+    expect(types).toContain('WebSite')
+    expect(types).toContain('Organization')
+    const org = entities.find((e) => e['@type'] === 'Organization')!
+    expect(org.logo).toBe('https://acme.com/logo.png')
+  })
+
+  test('homepage without organization emits WebSite only', () => {
+    const entities = buildJsonLdEntities(resolvedFor('/', 'page'), {
+      kind: 'page',
+      routePath: '/',
+      origin: ORIGIN,
+      siteName: 'Acme',
+    })
+    expect(entities.map((e) => e['@type'])).toEqual(['WebSite'])
+  })
+
+  test('row routes emit Article with dates and BreadcrumbList when deep', () => {
+    const resolved = resolvedFor('/posts/hello', 'row', {
+      publishedAt: '2026-06-01T00:00:00Z',
+      updatedAt: '2026-06-02T00:00:00Z',
+    })
+    const entities = buildJsonLdEntities(resolved, {
+      kind: 'row',
+      routePath: '/posts/hello',
+      origin: ORIGIN,
+      siteName: 'Acme',
+    })
+    const types = entities.map((e) => e['@type'])
+    expect(types).toContain('Article')
+    expect(types).toContain('BreadcrumbList')
+    const article = entities.find((e) => e['@type'] === 'Article')!
+    expect(article.headline).toBe('Hello')
+    expect(article.datePublished).toBe('2026-06-01T00:00:00Z')
+    expect(article.dateModified).toBe('2026-06-02T00:00:00Z')
+    const breadcrumbs = entities.find((e) => e['@type'] === 'BreadcrumbList')!
+    const items = breadcrumbs.itemListElement as { item: string; position: number }[]
+    expect(items).toHaveLength(3)
+    expect(items[2]!.item).toBe('https://acme.com/posts/hello')
+  })
+
+  test('single-segment page emits no breadcrumbs', () => {
+    const entities = buildJsonLdEntities(resolvedFor('/about', 'page'), {
+      kind: 'page',
+      routePath: '/about',
+      origin: ORIGIN,
+      siteName: 'Acme',
+    })
+    expect(entities.map((e) => e['@type'])).not.toContain('BreadcrumbList')
+  })
+
+  test('noindex targets emit nothing', () => {
+    const resolved = resolvedFor('/posts/hello', 'row', { target: { noindex: true } })
+    expect(
+      buildJsonLdEntities(resolved, {
+        kind: 'row',
+        routePath: '/posts/hello',
+        origin: ORIGIN,
+        siteName: 'Acme',
+      }),
+    ).toEqual([])
+  })
+
+  test('origin-dependent entities are omitted without an origin', () => {
+    const resolved = resolveSeoMetadata({
+      siteName: 'Acme',
+      routeKind: 'page',
+      routePath: '/',
+      baseTitle: 'Home',
+    })
+    const entities = buildJsonLdEntities(resolved, {
+      kind: 'page',
+      routePath: '/',
+      siteName: 'Acme',
+      organization: { name: 'Acme Inc' },
+    })
+    expect(entities).toEqual([])
+  })
+})
+
+describe('serializeJsonLd', () => {
+  test('escapes script terminators and comment openers', () => {
+    const out = serializeJsonLd({ name: 'x</script><script>alert(1)</script>', note: '<!-- hi' })
+    expect(out).not.toContain('</script')
+    expect(out).not.toContain('<!--')
+    // Round-trips back to the original values
+    const parsed = JSON.parse(out) as { name: string; note: string }
+    expect(parsed.name).toBe('x</script><script>alert(1)</script>')
+    expect(parsed.note).toBe('<!-- hi')
+  })
+})
diff --git a/src/core/seo/__tests__/resolve.test.ts b/src/core/seo/__tests__/resolve.test.ts
new file mode 100644
index 000000000..71689ecff
--- /dev/null
+++ b/src/core/seo/__tests__/resolve.test.ts
@@ -0,0 +1,174 @@
+import { describe, expect, test } from 'bun:test'
+import { resolveSeoMetadata, isSafeCanonicalUrl, absoluteUrl } from '../resolve'
+
+const BASE = {
+  siteName: 'Acme',
+  routeKind: 'page' as const,
+  routePath: '/about',
+}
+
+describe('resolveSeoMetadata — title (two-stage)', () => {
+  test('explicit target title wins as-is, no pattern applied', () => {
+    const resolved = resolveSeoMetadata({
+      ...BASE,
+      target: { title: 'Custom title' },
+      siteSeo: { titlePattern: '{page.title} — {site.name}' },
+      interpolate: () => 'INTERPOLATED',
+    })
+    expect(resolved.title).toBe('Custom title')
+  })
+
+  test('pattern interpolates when no explicit title', () => {
+    const resolved = resolveSeoMetadata({
+      ...BASE,
+      baseTitle: 'About',
+      siteSeo: { titlePattern: '{page.title} — {site.name}' },
+      interpolate: (p) => p.replace('{page.title}', 'About').replace('{site.name}', 'Acme'),
+    })
+    expect(resolved.title).toBe('About — Acme')
+  })
+
+  test('template pattern beats site pattern', () => {
+    const resolved = resolveSeoMetadata({
+      ...BASE,
+      templateSeo: { title: 'T:{x}' },
+      siteSeo: { titlePattern: 'S:{x}' },
+      interpolate: (p) => p,
+    })
+    expect(resolved.title).toBe('T:{x}')
+  })
+
+  test('falls back baseTitle then siteName without pattern', () => {
+    expect(resolveSeoMetadata({ ...BASE, baseTitle: 'About' }).title).toBe('About')
+    expect(resolveSeoMetadata(BASE).title).toBe('Acme')
+  })
+
+  test('empty-string target title is treated as unset', () => {
+    expect(resolveSeoMetadata({ ...BASE, target: { title: '' }, baseTitle: 'About' }).title).toBe(
+      'About',
+    )
+  })
+})
+
+describe('resolveSeoMetadata — description', () => {
+  test('target → template(interpolated) → site default', () => {
+    expect(
+      resolveSeoMetadata({ ...BASE, target: { description: 'mine' }, siteSeo: { description: 'site' } })
+        .description,
+    ).toBe('mine')
+    expect(
+      resolveSeoMetadata({
+        ...BASE,
+        templateSeo: { description: '{currentEntry.excerpt}' },
+        siteSeo: { description: 'site' },
+        interpolate: () => 'from-template',
+      }).description,
+    ).toBe('from-template')
+    expect(resolveSeoMetadata({ ...BASE, siteSeo: { description: 'site' } }).description).toBe('site')
+    expect(resolveSeoMetadata(BASE).description).toBeUndefined()
+  })
+})
+
+describe('resolveSeoMetadata — canonical / absolute URLs', () => {
+  test('origin produces canonical and ogUrl', () => {
+    const resolved = resolveSeoMetadata({ ...BASE, origin: 'https://acme.com/' })
+    expect(resolved.canonicalUrl).toBe('https://acme.com/about')
+    expect(resolved.ogUrl).toBe('https://acme.com/about')
+  })
+
+  test('no origin ⇒ canonical and ogUrl omitted, never guessed', () => {
+    const resolved = resolveSeoMetadata(BASE)
+    expect(resolved.canonicalUrl).toBeUndefined()
+    expect(resolved.ogUrl).toBeUndefined()
+  })
+
+  test('explicit safe canonical wins; unsafe one is ignored', () => {
+    expect(
+      resolveSeoMetadata({ ...BASE, target: { canonicalUrl: 'https://other.com/x' } }).canonicalUrl,
+    ).toBe('https://other.com/x')
+    expect(
+      resolveSeoMetadata({
+        ...BASE,
+        // eslint-disable-next-line no-script-url
+        target: { canonicalUrl: 'javascript:alert(1)' },
+        origin: 'https://acme.com',
+      }).canonicalUrl,
+    ).toBe('https://acme.com/about')
+  })
+})
+
+describe('resolveSeoMetadata — social fallbacks', () => {
+  test('og falls back to search values, x falls back to og', () => {
+    const resolved = resolveSeoMetadata({
+      ...BASE,
+      target: { title: 'T', description: 'D', ogImage: '/img.png', ogImageAlt: 'alt' },
+    })
+    expect(resolved.ogTitle).toBe('T')
+    expect(resolved.ogDescription).toBe('D')
+    expect(resolved.xTitle).toBe('T')
+    expect(resolved.xImage).toBe('/img.png')
+    expect(resolved.xImageAlt).toBe('alt')
+  })
+
+  test('xCard: explicit → site default → image-derived', () => {
+    expect(resolveSeoMetadata({ ...BASE, target: { xCard: 'summary' } }).xCard).toBe('summary')
+    expect(
+      resolveSeoMetadata({ ...BASE, siteSeo: { defaultXCard: 'summary' }, target: { ogImage: '/i.png' } })
+        .xCard,
+    ).toBe('summary')
+    expect(resolveSeoMetadata({ ...BASE, target: { ogImage: '/i.png' } }).xCard).toBe(
+      'summary_large_image',
+    )
+    expect(resolveSeoMetadata(BASE).xCard).toBe('summary')
+  })
+
+  test('ogType defaults by route kind; article carries timestamps', () => {
+    expect(resolveSeoMetadata(BASE).ogType).toBe('website')
+    const row = resolveSeoMetadata({
+      ...BASE,
+      routeKind: 'row',
+      publishedAt: '2026-06-01T00:00:00Z',
+      updatedAt: '2026-06-02T00:00:00Z',
+    })
+    expect(row.ogType).toBe('article')
+    expect(row.articlePublishedTime).toBe('2026-06-01T00:00:00Z')
+    expect(row.articleModifiedTime).toBe('2026-06-02T00:00:00Z')
+    // website pages carry no article times even when timestamps are present
+    const page = resolveSeoMetadata({ ...BASE, publishedAt: '2026-06-01T00:00:00Z' })
+    expect(page.articlePublishedTime).toBeUndefined()
+  })
+
+  test('x site handle is normalised to leading @', () => {
+    expect(resolveSeoMetadata({ ...BASE, siteSeo: { xSiteHandle: 'acme' } }).xSiteHandle).toBe('@acme')
+    expect(resolveSeoMetadata({ ...BASE, siteSeo: { xSiteHandle: '@acme' } }).xSiteHandle).toBe('@acme')
+    expect(resolveSeoMetadata({ ...BASE, siteSeo: { xSiteHandle: '' } }).xSiteHandle).toBeUndefined()
+  })
+})
+
+describe('resolveSeoMetadata — locale + noindex', () => {
+  test('og:locale derives from language', () => {
+    expect(resolveSeoMetadata({ ...BASE, language: 'en' }).ogLocale).toBe('en')
+    expect(resolveSeoMetadata({ ...BASE, language: 'en-US' }).ogLocale).toBe('en_US')
+    expect(resolveSeoMetadata(BASE).ogLocale).toBeUndefined()
+  })
+
+  test('noindex flag carries through', () => {
+    expect(resolveSeoMetadata({ ...BASE, target: { noindex: true } }).noindex).toBe(true)
+    expect(resolveSeoMetadata(BASE).noindex).toBe(false)
+  })
+})
+
+describe('url helpers', () => {
+  test('isSafeCanonicalUrl', () => {
+    expect(isSafeCanonicalUrl('https://a.com/x')).toBe(true)
+    expect(isSafeCanonicalUrl('http://a.com')).toBe(true)
+    // eslint-disable-next-line no-script-url
+    expect(isSafeCanonicalUrl('javascript:alert(1)')).toBe(false)
+    expect(isSafeCanonicalUrl('/relative')).toBe(false)
+  })
+
+  test('absoluteUrl joins without double slashes', () => {
+    expect(absoluteUrl('https://a.com/', '/x')).toBe('https://a.com/x')
+    expect(absoluteUrl('https://a.com', 'x')).toBe('https://a.com/x')
+  })
+})
diff --git a/src/core/seo/__tests__/robots.test.ts b/src/core/seo/__tests__/robots.test.ts
new file mode 100644
index 000000000..1370ff5f9
--- /dev/null
+++ b/src/core/seo/__tests__/robots.test.ts
@@ -0,0 +1,51 @@
+import { describe, expect, test } from 'bun:test'
+import { generateRobotsTxt } from '../robots'
+import { AI_ANSWER_CRAWLERS, AI_TRAINING_CRAWLERS } from '../aiCrawlers'
+
+describe('generateRobotsTxt', () => {
+  test('default output allows everything and links the sitemap', () => {
+    const out = generateRobotsTxt({ sitemapEnabled: true, origin: 'https://acme.com' })
+    expect(out).toBe('User-agent: *\nAllow: /\n\nSitemap: https://acme.com/sitemap.xml\n')
+  })
+
+  test('omits the sitemap line without an origin or when disabled', () => {
+    expect(generateRobotsTxt({ sitemapEnabled: true })).not.toContain('Sitemap:')
+    expect(generateRobotsTxt({ sitemapEnabled: false, origin: 'https://a.com' })).not.toContain(
+      'Sitemap:',
+    )
+  })
+
+  test('indexing disabled produces a global Disallow', () => {
+    const out = generateRobotsTxt({
+      robots: { indexingEnabled: false },
+      sitemapEnabled: true,
+      origin: 'https://acme.com',
+    })
+    expect(out).toContain('User-agent: *\nDisallow: /')
+    expect(out).not.toContain('Allow: /')
+  })
+
+  test('blocking AI training crawlers emits one block per bot', () => {
+    const out = generateRobotsTxt({
+      robots: { allowAiTrainingCrawlers: false },
+      sitemapEnabled: false,
+    })
+    for (const bot of AI_TRAINING_CRAWLERS) {
+      expect(out).toContain(`User-agent: ${bot}\nDisallow: /`)
+    }
+    for (const bot of AI_ANSWER_CRAWLERS) {
+      expect(out).not.toContain(`User-agent: ${bot}`)
+    }
+  })
+
+  test('blocking AI answer crawlers emits one block per bot', () => {
+    const out = generateRobotsTxt({
+      robots: { allowAiAnswerCrawlers: false },
+      sitemapEnabled: false,
+    })
+    for (const bot of AI_ANSWER_CRAWLERS) {
+      expect(out).toContain(`User-agent: ${bot}\nDisallow: /`)
+    }
+    expect(out).toContain('User-agent: *\nAllow: /')
+  })
+})
diff --git a/src/core/seo/aiCrawlers.ts b/src/core/seo/aiCrawlers.ts
new file mode 100644
index 000000000..442643f7c
--- /dev/null
+++ b/src/core/seo/aiCrawlers.ts
@@ -0,0 +1,26 @@
+/**
+ * AI crawler user-agent lists — the bots the Robots.txt tab's two toggles
+ * control. These lists churn as the AI ecosystem evolves; this constant is
+ * the ONE place to update them. Rendered as per-agent `Disallow: /` blocks
+ * by `generateRobotsTxt` when the corresponding group is blocked.
+ *
+ * Training crawlers ingest content for model training; answer crawlers fetch
+ * content to ground live answers (AI search). Operators commonly want to
+ * block the former while staying visible to the latter, so the toggles are
+ * separate.
+ */
+
+export const AI_TRAINING_CRAWLERS = [
+  'GPTBot',
+  'Google-Extended',
+  'CCBot',
+  'Applebot-Extended',
+  'meta-externalagent',
+] as const
+
+export const AI_ANSWER_CRAWLERS = [
+  'OAI-SearchBot',
+  'PerplexityBot',
+  'ChatGPT-User',
+  'Claude-SearchBot',
+] as const
diff --git a/src/core/seo/health.ts b/src/core/seo/health.ts
new file mode 100644
index 000000000..c41dccb2a
--- /dev/null
+++ b/src/core/seo/health.ts
@@ -0,0 +1,62 @@
+/**
+ * SEO health indicators — computed client-side from raw target values plus
+ * the resolved metadata, so the target index, the preview editor, and
+ * published output agree by construction (one resolver, one health rule set).
+ */
+
+import type { SeoMetadata } from './schema'
+import type { ResolvedSeoMetadata } from './resolve'
+import {
+  approxPixelWidth,
+  meterZone,
+  TITLE_PIXEL_BUDGET,
+  DESCRIPTION_PIXEL_BUDGET,
+} from './lengthMeter'
+
+export type TextHealth = 'ok' | 'missing' | 'long'
+export type ImageHealth = 'ok' | 'missing' | 'missingAlt'
+
+export interface SeoHealth {
+  title: TextHealth
+  description: TextHealth
+  image: ImageHealth
+  /** false when the target is set to noindex. */
+  indexable: boolean
+  /** Count of non-ok indicators, for index sorting / summary chips. */
+  issueCount: number
+}
+
+export function computeSeoHealth(
+  target: SeoMetadata | undefined,
+  resolved: ResolvedSeoMetadata,
+): SeoHealth {
+  const title: TextHealth =
+    resolved.title === ''
+      ? 'missing'
+      : meterZone(approxPixelWidth(resolved.title), TITLE_PIXEL_BUDGET) === 'over'
+        ? 'long'
+        : 'ok'
+
+  const description: TextHealth =
+    resolved.description === undefined || resolved.description === ''
+      ? 'missing'
+      : meterZone(approxPixelWidth(resolved.description), DESCRIPTION_PIXEL_BUDGET) === 'over'
+        ? 'long'
+        : 'ok'
+
+  const image: ImageHealth = !resolved.ogImage
+    ? 'missing'
+    : !resolved.ogImageAlt
+      ? 'missingAlt'
+      : 'ok'
+
+  const indexable = target?.noindex !== true
+
+  const issueCount =
+    (title === 'ok' ? 0 : 1) +
+    (description === 'ok' ? 0 : 1) +
+    (image === 'ok' ? 0 : 1) +
+    (indexable ? 0 : 1)
+
+  return { title, description, image, indexable, issueCount }
+}
diff --git a/src/core/seo/index.ts b/src/core/seo/index.ts
new file mode 100644
index 000000000..7d77b294f
--- /dev/null
+++ b/src/core/seo/index.ts
@@ -0,0 +1,59 @@
+/**
+ * @core/seo — public barrel.
+ *
+ * The SEO engine: persisted schemas, the shared fallback resolver, JSON-LD
+ * builders, robots.txt generation, AI-crawler lists, health indicators, and
+ * length meters. Imported by the publisher, server handlers, and the admin
+ * SEO workspace. Deep imports are gated by
+ * `src/__tests__/architecture/no-core-barrel-deep-imports.test.ts`.
+ */
+
+export {
+  SeoMetadataSchema,
+  SiteSeoSettingsSchema,
+  SeoOrganizationSchema,
+  SeoRobotsSettingsSchema,
+  SeoSitemapSettingsSchema,
+  OgTypeSchema,
+  XCardTypeSchema,
+  parseSeoMetadata,
+  parseSiteSeoSettings,
+  type SeoMetadata,
+  type SiteSeoSettings,
+  type SeoOrganization,
+  type SeoRobotsSettings,
+  type SeoSitemapSettings,
+  type OgType,
+  type XCardType,
+} from './schema'
+
+export {
+  resolveSeoMetadata,
+  isSafeCanonicalUrl,
+  absoluteUrl,
+  type ResolveSeoInput,
+  type ResolvedSeoMetadata,
+} from './resolve'
+
+export {
+  buildJsonLdEntities,
+  serializeJsonLd,
+  type JsonLdContext,
+  type JsonLdEntity,
+} from './jsonLd'
+
+export { AI_TRAINING_CRAWLERS, AI_ANSWER_CRAWLERS } from './aiCrawlers'
+
+export { generateRobotsTxt, type GenerateRobotsTxtInput } from './robots'
+
+export { computeSeoHealth, type SeoHealth, type TextHealth, type ImageHealth } from './health'
+
+export {
+  approxPixelWidth,
+  meterZone,
+  TITLE_PIXEL_BUDGET,
+  DESCRIPTION_PIXEL_BUDGET,
+  TITLE_CHAR_GUIDE,
+  DESCRIPTION_CHAR_GUIDE,
+  type MeterZone,
+} from './lengthMeter'
diff --git a/src/core/seo/jsonLd.ts b/src/core/seo/jsonLd.ts
new file mode 100644
index 000000000..4ca364aff
--- /dev/null
+++ b/src/core/seo/jsonLd.ts
@@ -0,0 +1,121 @@
+/**
+ * JSON-LD structured data builders — schema.org entities generated
+ * automatically from resolved SEO metadata. Zero configuration in v1:
+ * no per-target schema editor, the builders derive everything from the
+ * same resolved values the meta tags use.
+ *
+ *   - Homepage (`routePath === '/'`): `WebSite`, plus `Organization` when
+ *     site organization defaults are set.
+ *   - Row routes: `Article` (headline, description, image, dates).
+ *   - Routes deeper than one segment: `BreadcrumbList`.
+ *
+ * Entities that require absolute URLs are omitted when no public origin is
+ * configured. `noindex` targets emit no JSON-LD at all.
+ *
+ * `serializeJsonLd` escapes `</script` and `<!--` so user-controlled strings
+ * cannot break out of the `<script type="application/ld+json">` element.
+ * JSON-LD is non-executing, so no CSP change is needed.
+ */
+
+import type { SeoOrganization } from './schema'
+import type { ResolvedSeoMetadata } from './resolve'
+import { absoluteUrl } from './resolve'
+
+export interface JsonLdContext {
+  kind: 'page' | 'row'
+  routePath: string
+  origin?: string
+  siteName: string
+  organization?: SeoOrganization
+}
+
+export type JsonLdEntity = Record<string, unknown>
+
+function breadcrumbList(ctx: JsonLdContext): JsonLdEntity | null {
+  if (!ctx.origin) return null
+  const segments = ctx.routePath.split('/').filter(Boolean)
+  if (segments.length < 2) return null
+
+  const items = [
+    {
+      '@type': 'ListItem',
+      position: 1,
+      name: ctx.siteName,
+      item: absoluteUrl(ctx.origin, '/'),
+    },
+    ...segments.map((segment, index) => ({
+      '@type': 'ListItem',
+      position: index + 2,
+      name: decodeURIComponent(segment),
+      item: absoluteUrl(ctx.origin!, `/${segments.slice(0, index + 1).join('/')}`),
+    })),
+  ]
+  return {
+    '@context': 'https://schema.org',
+    '@type': 'BreadcrumbList',
+    itemListElement: items,
+  }
+}
+
+/**
+ * Build the JSON-LD entities for one route. Returns `[]` for noindex
+ * targets — content excluded from search must not advertise itself to
+ * answer engines either.
+ */
+export function buildJsonLdEntities(
+  resolved: ResolvedSeoMetadata,
+  ctx: JsonLdContext,
+): JsonLdEntity[] {
+  if (resolved.noindex) return []
+
+  const entities: JsonLdEntity[] = []
+  const isHomepage = ctx.routePath === '/'
+
+  if (isHomepage && ctx.origin) {
+    entities.push({
+      '@context': 'https://schema.org',
+      '@type': 'WebSite',
+      name: ctx.siteName,
+      url: absoluteUrl(ctx.origin, '/'),
+    })
+    const org = ctx.organization
+    if (org?.name) {
+      entities.push({
+        '@context': 'https://schema.org',
+        '@type': 'Organization',
+        name: org.name,
+        url: absoluteUrl(ctx.origin, '/'),
+        ...(org.logoUrl ? { logo: org.logoUrl } : {}),
+      })
+    }
+  }
+
+  if (ctx.kind === 'row') {
+    entities.push({
+      '@context': 'https://schema.org',
+      '@type': 'Article',
+      headline: resolved.title,
+      ...(resolved.description ? { description: resolved.description } : {}),
+      ...(resolved.ogImage ? { image: resolved.ogImage } : {}),
+      ...(resolved.canonicalUrl ? { mainEntityOfPage: resolved.canonicalUrl } : {}),
+      ...(resolved.articlePublishedTime ? { datePublished: resolved.articlePublishedTime } : {}),
+      ...(resolved.articleModifiedTime ? { dateModified: resolved.articleModifiedTime } : {}),
+    })
+  }
+
+  const breadcrumbs = breadcrumbList(ctx)
+  if (breadcrumbs) entities.push(breadcrumbs)
+
+  return entities
+}
+
+/**
+ * Serialize one entity for embedding in `<script type="application/ld+json">`.
+ * Escapes the two sequences that could terminate or corrupt the script
+ * element when they appear inside user-controlled string values.
+ */
+export function serializeJsonLd(entity: JsonLdEntity): string {
+  return JSON.stringify(entity)
+    .replaceAll('</script', '<\\/script')
+    .replaceAll('<!--', '\\u003C!--')
+}
diff --git a/src/core/seo/lengthMeter.ts b/src/core/seo/lengthMeter.ts
new file mode 100644
index 000000000..2c553553c
--- /dev/null
+++ b/src/core/seo/lengthMeter.ts
@@ -0,0 +1,50 @@
+/**
+ * Approximate pixel-width metering for SEO title / description fields.
+ *
+ * Google truncates result snippets by rendered pixel width, not character
+ * count (~580px titles, ~990px descriptions on desktop). An exact
+ * measurement would need the SERP font metrics; a per-character-class
+ * width table gets within a few percent, which is plenty for an editor
+ * meter with ok / amber / over zones.
+ *
+ * Pure module — usable from admin UI and tests without a DOM.
+ */
+
+export const TITLE_PIXEL_BUDGET = 580
+export const DESCRIPTION_PIXEL_BUDGET = 990
+
+/** Sensible character guides shown alongside the pixel meter. */
+export const TITLE_CHAR_GUIDE = 60
+export const DESCRIPTION_CHAR_GUIDE = 160
+
+const NARROW = /[iljtf.,:;'!|()\[\]{} ]/
+const WIDE = /[mwMW@%]/
+const UPPER = /[A-Z0-9]/
+
+/**
+ * Approximate rendered width in pixels at the Google SERP's ~18px Arial
+ * (titles) scale. Description text renders smaller, but the budgets above
+ * are calibrated to the same per-class table, so one function serves both.
+ */
+export function approxPixelWidth(text: string): number {
+  let width = 0
+  for (const char of text) {
+    if (NARROW.test(char)) width += 5
+    else if (WIDE.test(char)) width += 15
+    else if (UPPER.test(char)) width += 12
+    else width += 9
+  }
+  return width
+}
+
+export type MeterZone = 'ok' | 'amber' | 'over'
+
+/**
+ * Zone for a measured width against a budget: green up to 85%, amber from
+ * 85% to the budget, over beyond it.
+ */
+export function meterZone(pixelWidth: number, budget: number): MeterZone {
+  if (pixelWidth > budget) return 'over'
+  if (pixelWidth > budget * 0.85) return 'amber'
+  return 'ok'
+}
diff --git a/src/core/seo/resolve.ts b/src/core/seo/resolve.ts
new file mode 100644
index 000000000..a1d8ed5bc
--- /dev/null
+++ b/src/core/seo/resolve.ts
@@ -0,0 +1,196 @@
+/**
+ * SEO metadata resolver — the single fallback engine shared by the
+ * publisher (published `<head>` output), the admin SEO workspace (preview
+ * placeholders + health indicators), and the server SEO endpoints.
+ *
+ * Title resolution is TWO-STAGE — literals resolve first, then a pattern
+ * (if any) interpolates around the resolved base:
+ *
+ *   1. `baseTitle = target.title ?? input.baseTitle` (row/page display title)
+ *   2. explicit `target.title` wins as-is (the user overriding the pattern);
+ *      otherwise `templateSeo.title ?? siteSeo.titlePattern` is treated as a
+ *      token pattern and interpolated via the provided `interpolate` closure
+ *      (the shared `{source.field}` engine from `@core/templates`).
+ *
+ * Patterns and literal values never share a `??` chain.
+ *
+ * Absolute URLs (canonical, og:url) require `origin`; when absent they are
+ * OMITTED — the publisher must never bake a guessed host into static HTML.
+ */
+
+import type { OgType, SeoMetadata, SiteSeoSettings, XCardType } from './schema'
+
+export interface ResolveSeoInput {
+  /** The target's own `cells_json.seo` (page or row). */
+  target?: SeoMetadata
+  /**
+   * SEO object from the entry-template page row wrapping this target.
+   * `title` / `description` may carry `{source.field}` tokens.
+   */
+  templateSeo?: SeoMetadata
+  /** Site-wide defaults from `site.settings.seo`. */
+  siteSeo?: SiteSeoSettings
+  siteName: string
+  /** Row/page display title — stage-1 fallback for the SEO title. */
+  baseTitle?: string
+  routeKind: 'page' | 'row'
+  /** Public route path, e.g. `/` or `/posts/hello`. */
+  routePath: string
+  /** Absolute public origin (`https://example.com`). Absent ⇒ omit absolute URLs. */
+  origin?: string
+  /** Site language (BCP-47), drives `og:locale`. */
+  language?: string
+  /** ISO datetime — row publish time (article:published_time). */
+  publishedAt?: string
+  /** ISO datetime — row update time (article:modified_time, lastmod). */
+  updatedAt?: string
+  /**
+   * Token interpolation closure — `interpolateTokens(pattern, context)`
+   * partially applied over the render's TemplateRenderDataContext.
+   * Defaults to identity (patterns emit verbatim), which admin previews
+   * override with a synthetic context.
+   */
+  interpolate?: (pattern: string) => string
+}
+
+export interface ResolvedSeoMetadata {
+  title: string
+  description?: string
+  canonicalUrl?: string
+  noindex: boolean
+  ogTitle: string
+  ogDescription?: string
+  ogImage?: string
+  ogImageAlt?: string
+  ogType: OgType
+  ogUrl?: string
+  ogLocale?: string
+  xCard: XCardType
+  xTitle: string
+  xDescription?: string
+  xImage?: string
+  xImageAlt?: string
+  /** `twitter:site` handle, normalised to include the leading `@`. */
+  xSiteHandle?: string
+  articlePublishedTime?: string
+  articleModifiedTime?: string
+}
+
+/** Allow only http(s) absolute URLs for user-provided canonicals. */
+export function isSafeCanonicalUrl(value: string): boolean {
+  try {
+    const url = new URL(value)
+    return url.protocol === 'https:' || url.protocol === 'http:'
+  } catch {
+    return false
+  }
+}
+
+/** `en` → `en`, `en-US` → `en_US`, `cs` → `cs`. Invalid tags ⇒ undefined. */
+function ogLocaleFromLanguage(language: string | undefined): string | undefined {
+  if (!language) return undefined
+  const match = language.trim().match(/^([a-zA-Z]{2,3})(?:-([a-zA-Z]{2}))?/)
+  if (!match) return undefined
+  const lang = match[1]!.toLowerCase()
+  return match[2] ? `${lang}_${match[2].toUpperCase()}` : lang
+}
+
+function normalizeXHandle(handle: string | undefined): string | undefined {
+  if (!handle) return undefined
+  const trimmed = handle.trim()
+  if (trimmed === '' || trimmed === '@') return undefined
+  return trimmed.startsWith('@') ? trimmed : `@${trimmed}`
+}
+
+/** Join origin + path without double slashes. */
+export function absoluteUrl(origin: string, routePath: string): string {
+  const base = origin.replace(/\/+$/, '')
+  const path = routePath.startsWith('/') ? routePath : `/${routePath}`
+  return `${base}${path}`
+}
+
+export function resolveSeoMetadata(input: ResolveSeoInput): ResolvedSeoMetadata {
+  const target = input.target ?? {}
+  const templateSeo = input.templateSeo ?? {}
+  const siteSeo = input.siteSeo ?? {}
+  const interpolate = input.interpolate ?? ((pattern: string) => pattern)
+
+  // ── Title: two-stage ──────────────────────────────────────────────────────
+  // Explicit per-target title wins as-is — the user overriding the pattern.
+  const pattern = templateSeo.title ?? siteSeo.titlePattern
+  let title: string
+  if (target.title !== undefined && target.title !== '') {
+    title = target.title
+  } else if (pattern !== undefined && pattern !== '') {
+    title = interpolate(pattern)
+  } else {
+    title = input.baseTitle !== undefined && input.baseTitle !== '' ? input.baseTitle : input.siteName
+  }
+
+  // Description: per-target → template (interpolated) → site default.
+  const templateDescription =
+    templateSeo.description !== undefined && templateSeo.description !== ''
+      ? interpolate(templateSeo.description)
+      : undefined
+  const description = firstNonEmpty(target.description, templateDescription, siteSeo.description)
+
+  // Canonical: explicit (validated) → origin + route path → omitted.
+  let canonicalUrl: string | undefined
+  if (target.canonicalUrl !== undefined && isSafeCanonicalUrl(target.canonicalUrl)) {
+    canonicalUrl = target.canonicalUrl
+  } else if (input.origin) {
+    canonicalUrl = absoluteUrl(input.origin, input.routePath)
+  }
+
+  const ogTitle = firstNonEmpty(target.ogTitle) ?? title
+  const ogDescription = firstNonEmpty(target.ogDescription) ?? description
+  const ogImage = firstNonEmpty(target.ogImage, siteSeo.defaultOgImage)
+  const ogImageAlt = firstNonEmpty(target.ogImageAlt, siteSeo.defaultOgImageAlt)
+  const ogType: OgType = target.ogType ?? (input.routeKind === 'row' ? 'article' : 'website')
+
+  const xTitle = firstNonEmpty(target.xTitle) ?? ogTitle
+  const xDescription = firstNonEmpty(target.xDescription) ?? ogDescription
+  const xImage = firstNonEmpty(target.xImage) ?? ogImage
+  const xImageAlt = firstNonEmpty(target.xImageAlt) ?? ogImageAlt
+  const xCard: XCardType =
+    target.xCard ?? siteSeo.defaultXCard ?? (xImage ? 'summary_large_image' : 'summary')
+
+  const isArticle = ogType === 'article'
+
+  return {
+    title,
+    ...(description !== undefined ? { description } : {}),
+    ...(canonicalUrl !== undefined ? { canonicalUrl } : {}),
+    noindex: target.noindex === true,
+    ogTitle,
+    ...(ogDescription !== undefined ? { ogDescription } : {}),
+    ...(ogImage !== undefined ? { ogImage } : {}),
+    ...(ogImageAlt !== undefined ? { ogImageAlt } : {}),
+    ogType,
+    ...(canonicalUrl !== undefined ? { ogUrl: canonicalUrl } : {}),
+    ...(ogLocaleFromLanguage(input.language) !== undefined
+      ? { ogLocale: ogLocaleFromLanguage(input.language) }
+      : {}),
+    xCard,
+    xTitle,
+    ...(xDescription !== undefined ? { xDescription } : {}),
+    ...(xImage !== undefined ? { xImage } : {}),
+    ...(xImageAlt !== undefined ? { xImageAlt } : {}),
+    ...(normalizeXHandle(siteSeo.xSiteHandle) !== undefined
+      ? { xSiteHandle: normalizeXHandle(siteSeo.xSiteHandle) }
+      : {}),
+    ...(isArticle && input.publishedAt !== undefined
+      ? { articlePublishedTime: input.publishedAt }
+      : {}),
+    ...(isArticle && input.updatedAt !== undefined
+      ? { articleModifiedTime: input.updatedAt }
+      : {}),
+  }
+}
+
+function firstNonEmpty(...values: (string | undefined)[]): string | undefined {
+  for (const value of values) {
+    if (value !== undefined && value !== '') return value
+  }
+  return undefined
+}
diff --git a/src/core/seo/robots.ts b/src/core/seo/robots.ts
new file mode 100644
index 000000000..85d77250e
--- /dev/null
+++ b/src/core/seo/robots.ts
@@ -0,0 +1,41 @@
+/**
+ * robots.txt generation — pure function from robots settings + context to
+ * the served `text/plain` body. Used by the server endpoint
+ * (`server/publish/seoEndpoints.ts`) and the admin Robots.txt tab's live
+ * preview, so what the tab shows is byte-identical to what crawlers get.
+ */
+
+import { AI_ANSWER_CRAWLERS, AI_TRAINING_CRAWLERS } from './aiCrawlers'
+import type { SeoRobotsSettings } from './schema'
+
+export interface GenerateRobotsTxtInput {
+  robots?: SeoRobotsSettings
+  /** Whether sitemap generation is enabled (adds the `Sitemap:` line). */
+  sitemapEnabled: boolean
+  /** Absolute public origin for the Sitemap line; absent ⇒ line omitted. */
+  origin?: string
+}
+
+export function generateRobotsTxt(input: GenerateRobotsTxtInput): string {
+  const robots = input.robots ?? {}
+  const lines: string[] = []
+
+  if (robots.indexingEnabled === false) {
+    lines.push('User-agent: *', 'Disallow: /')
+  } else {
+    lines.push('User-agent: *', 'Allow: /')
+
+    const blockedBots: string[] = []
+    if (robots.allowAiTrainingCrawlers === false) blockedBots.push(...AI_TRAINING_CRAWLERS)
+    if (robots.allowAiAnswerCrawlers === false) blockedBots.push(...AI_ANSWER_CRAWLERS)
+    for (const bot of blockedBots) {
+      lines.push('', `User-agent: ${bot}`, 'Disallow: /')
+    }
+  }
+
+  if (input.sitemapEnabled && input.origin) {
+    lines.push('', `Sitemap: ${input.origin.replace(/\/+$/, '')}/sitemap.xml`)
+  }
+
+  return `${lines.join('\n')}\n`
+}
diff --git a/src/core/seo/schema.ts b/src/core/seo/schema.ts
new file mode 100644
index 000000000..2c8051a38
--- /dev/null
+++ b/src/core/seo/schema.ts
@@ -0,0 +1,124 @@
+/**
+ * SEO metadata schemas — the persisted shapes for per-target SEO data and
+ * site-wide SEO defaults.
+ *
+ * `SeoMetadata` is the structured object stored in `cells_json.seo` on
+ * `page` and `postType` rows (built-in `seoMetadata` field). `SiteSeoSettings`
+ * lives under `site.settings.seo` and carries the site-wide defaults the
+ * resolver (`./resolve.ts`) falls back to.
+ *
+ * Title/description values on entry-template rows may carry `{source.field}`
+ * tokens from the shared token engine (`@core/templates` —
+ * `tokenInterpolation.ts`); the resolver receives an `interpolate` closure so
+ * this module stays decoupled from the templates engine.
+ *
+ * Pure leaf module: no imports from publisher, server, or admin code.
+ */
+
+import { Type, type Static } from '@core/utils/typeboxHelpers'
+import { compiledCheck } from '@core/utils/typeboxCompiler'
+
+// ---------------------------------------------------------------------------
+// SeoMetadata — per-target structured SEO object (cells_json.seo)
+// ---------------------------------------------------------------------------
+
+export const OgTypeSchema = Type.Union([
+  Type.Literal('website'),
+  Type.Literal('article'),
+])
+
+export type OgType = Static<typeof OgTypeSchema>
+
+export const XCardTypeSchema = Type.Union([
+  Type.Literal('summary'),
+  Type.Literal('summary_large_image'),
+])
+
+export type XCardType = Static<typeof XCardTypeSchema>
+
+export const SeoMetadataSchema = Type.Object({
+  title: Type.Optional(Type.String()),
+  description: Type.Optional(Type.String()),
+  canonicalUrl: Type.Optional(Type.String()),
+  noindex: Type.Optional(Type.Boolean()),
+
+  ogTitle: Type.Optional(Type.String()),
+  ogDescription: Type.Optional(Type.String()),
+  ogImage: Type.Optional(Type.String()),
+  ogImageAlt: Type.Optional(Type.String()),
+  ogType: Type.Optional(OgTypeSchema),
+
+  xTitle: Type.Optional(Type.String()),
+  xDescription: Type.Optional(Type.String()),
+  xImage: Type.Optional(Type.String()),
+  xImageAlt: Type.Optional(Type.String()),
+  xCard: Type.Optional(XCardTypeSchema),
+})
+
+export type SeoMetadata = Static<typeof SeoMetadataSchema>
+
+/**
+ * Tolerant parse for `cells_json.seo` blobs read from storage. Returns
+ * `undefined` for anything that isn't a valid SeoMetadata object — a corrupt
+ * SEO cell must never prevent loading the row.
+ */
+export function parseSeoMetadata(raw: unknown): SeoMetadata | undefined {
+  if (!raw || typeof raw !== 'object' || Array.isArray(raw)) return undefined
+  return compiledCheck(SeoMetadataSchema, raw) ? (raw as SeoMetadata) : undefined
+}
+
+// ---------------------------------------------------------------------------
+// SiteSeoSettings — site-wide defaults (site.settings.seo)
+// ---------------------------------------------------------------------------
+
+export const SeoOrganizationSchema = Type.Object({
+  name: Type.Optional(Type.String()),
+  logoUrl: Type.Optional(Type.String()),
+})
+
+export type SeoOrganization = Static<typeof SeoOrganizationSchema>
+
+export const SeoRobotsSettingsSchema = Type.Object({
+  /** false ⇒ `Disallow: /` for every user agent. Defaults to true. */
+  indexingEnabled: Type.Optional(Type.Boolean()),
+  /** false ⇒ Disallow blocks for AI_TRAINING_CRAWLERS. Defaults to true. */
+  allowAiTrainingCrawlers: Type.Optional(Type.Boolean()),
+  /** false ⇒ Disallow blocks for AI_ANSWER_CRAWLERS. Defaults to true. */
+  allowAiAnswerCrawlers: Type.Optional(Type.Boolean()),
+})
+
+export type SeoRobotsSettings = Static<typeof SeoRobotsSettingsSchema>
+
+export const SeoSitemapSettingsSchema = Type.Object({
+  /** Defaults to true. */
+  enabled: Type.Optional(Type.Boolean()),
+  /** Target ids (`page:<rowId>` / `row:<rowId>`) excluded from the sitemap. */
+  excludedTargets: Type.Optional(Type.Array(Type.String())),
+})
+
+export type SeoSitemapSettings = Static<typeof SeoSitemapSettingsSchema>
+
+export const SiteSeoSettingsSchema = Type.Object({
+  /** Site-wide title pattern, e.g. `'{page.title} — {site.name}'`. */
+  titlePattern: Type.Optional(Type.String()),
+  description: Type.Optional(Type.String()),
+  defaultOgImage: Type.Optional(Type.String()),
+  defaultOgImageAlt: Type.Optional(Type.String()),
+  defaultXCard: Type.Optional(XCardTypeSchema),
+  /** X account handle for `twitter:site`, with or without the leading `@`. */
+  xSiteHandle: Type.Optional(Type.String()),
+  organization: Type.Optional(SeoOrganizationSchema),
+  robots: Type.Optional(SeoRobotsSettingsSchema),
+  sitemap: Type.Optional(SeoSitemapSettingsSchema),
+})
+
+export type SiteSeoSettings = Static<typeof SiteSeoSettingsSchema>
+
+/**
+ * Tolerant parse for `site.settings.seo`. Invalid blobs become `undefined`
+ * (site loads with no SEO defaults rather than failing).
+ */
+export function parseSiteSeoSettings(raw: unknown): SiteSeoSettings | undefined {
+  if (!raw || typeof raw !== 'object' || Array.isArray(raw)) return undefined
+  return compiledCheck(SiteSeoSettingsSchema, raw) ? (raw as SiteSeoSettings) : undefined
+}

From 9ea3cd6a3004250fd7e89702acd69d2f6871e12c Mon Sep 17 00:00:00 2001
From: DavidBabinec <hello@davidbabinec.com>
Date: Fri, 12 Jun 2026 12:32:52 +0200
Subject: [PATCH 02/26] feat(seo)!: replace flat seoTitle/seoDescription with
 structured seo field

One built-in seoMetadata field (id: seo) on page and postType tables,
stored as a structured SeoMetadata object in cells_json.seo. Page schema
and site settings gain seo objects; content panel title/description merge
into the structured cell; migrations, data grid, binding catalog, AI
content tools, and tests updated. Pre-release: no compat path retained.

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
---
 server/ai/tools/content/systemPrompt.ts       |  4 +-
 server/db/migrations-pg.ts                    |  4 +-
 server/db/migrations-sqlite.ts                |  4 +-
 .../data-tables-system-flag.test.ts           |  6 +--
 src/__tests__/data/contentAdmin.test.tsx      | 50 +++++++------------
 src/admin/pages/content/ContentPage.tsx       |  7 ++-
 .../pages/content/agent/ContentAgentMount.tsx | 18 ++++---
 .../ContentCollectionCreateDialog.tsx         |  5 +-
 .../ContentCollectionSettingsDialog.tsx       |  7 ++-
 .../ContentSettingsPanel.tsx                  |  4 +-
 .../content/hooks/useContentEntryDraft.ts     | 41 +++++++++++----
 .../content/hooks/useContentWorkspace.ts      |  4 --
 .../DataGrid/cells/CellDisplayRenderer.tsx    |  6 +++
 .../DataGrid/cells/CellEditorRenderer.tsx     |  5 ++
 .../DataInspector/fieldEditState.ts           |  2 +
 .../components/DataInspector/fieldGuards.ts   |  3 +-
 src/admin/pages/data/utils/fieldDefaults.ts   |  3 ++
 src/admin/pages/data/utils/fieldIcons.ts      |  2 +
 .../BindingPickerPopover.tsx                  |  2 -
 .../property-controls/bindingCompatibility.ts |  7 +--
 src/core/data/cells.ts                        | 14 +++---
 src/core/data/fields.ts                       | 22 +++-----
 src/core/data/pageFromRow.ts                  | 10 +++-
 src/core/data/schemas.ts                      | 23 ++++++---
 src/core/forms/validation.ts                  |  1 +
 src/core/loops/sources/dataRows.ts            |  2 -
 src/core/page-tree/page.ts                    |  9 ++++
 src/core/page-tree/siteSettings.ts            |  6 +++
 src/core/plugin-sdk/types/serverApi.ts        |  2 +-
 src/core/seo/__tests__/jsonLd.test.ts         |  4 +-
 src/core/seo/__tests__/resolve.test.ts        |  4 +-
 src/core/templates/templatePreviewData.ts     |  9 ++--
 32 files changed, 170 insertions(+), 120 deletions(-)

diff --git a/server/ai/tools/content/systemPrompt.ts b/server/ai/tools/content/systemPrompt.ts
index ba56acfb3..bd8661027 100644
--- a/server/ai/tools/content/systemPrompt.ts
+++ b/server/ai/tools/content/systemPrompt.ts
@@ -13,7 +13,7 @@ import type { ContentSnapshot, ActiveDocument } from './snapshot'
 const STATIC_PROMPT_PREFIX = `You manage the user's website content (posts, pages, custom collections) by calling tools. No filesystem or shell. Bias toward action — execute the prompt, don't ask scoping questions.
 
 Scope:
-- Each collection is a typed table of documents (posts, pages, or custom). Documents have a fixed schema: built-in fields (title, slug, body, featuredMedia, seoTitle, seoDescription) plus any custom fields.
+- Each collection is a typed table of documents (posts, pages, or custom). Documents have a fixed schema: built-in fields (title, slug, body, featuredMedia, seo) plus any custom fields.
 - The active document is the one currently open in the editor. Most edits target it; call set_active_document to switch the user's view before editing another doc.
 - Body content is exchanged as **markdown**. Use standard markdown (headings, paragraphs, lists, links, bold/italic, code, blockquotes) — the bridge converts to the editor's internal format on write.
 
@@ -50,7 +50,7 @@ Media + users:
 - list_users to look up an author id before set_document_author.
 
 Other:
-- Field ids are stable (title, slug, body, featuredMedia, seoTitle, seoDescription, plus custom). Use them verbatim; case-sensitive.
+- Field ids are stable (title, slug, body, featuredMedia, seo, plus custom). Use them verbatim; case-sensitive. The seo field holds a structured object; set seo.title / seo.description rather than replacing the whole object.
 - Don't invent option ids for select fields — read the schema first.
 - create_document success data includes the new id as documentId.
 - On tool error: read the message and retry with corrected input.
diff --git a/server/db/migrations-pg.ts b/server/db/migrations-pg.ts
index 597f55e16..5d314b6d2 100644
--- a/server/db/migrations-pg.ts
+++ b/server/db/migrations-pg.ts
@@ -243,7 +243,7 @@ export const pgMigrations: Migration[] = [
 
       insert into data_tables (id, name, slug, kind, route_base, singular_label, plural_label, primary_field_id, system, fields_json)
       values ('posts', 'Posts', 'posts', 'postType', '/posts', 'Post', 'Posts', 'title', true,
-        '[{"type":"text","id":"title","label":"Title","required":true,"builtIn":true},{"type":"text","id":"slug","label":"Slug","required":true,"builtIn":true},{"type":"richText","id":"body","label":"Body","format":"markdown","builtIn":true},{"type":"media","id":"featuredMedia","label":"Featured media","mediaKind":"image","builtIn":true},{"type":"text","id":"seoTitle","label":"SEO title","builtIn":true},{"type":"longText","id":"seoDescription","label":"SEO description","builtIn":true}]'::jsonb)
+        '[{"type":"text","id":"title","label":"Title","required":true,"builtIn":true},{"type":"text","id":"slug","label":"Slug","required":true,"builtIn":true},{"type":"richText","id":"body","label":"Body","format":"markdown","builtIn":true},{"type":"media","id":"featuredMedia","label":"Featured media","mediaKind":"image","builtIn":true},{"type":"seoMetadata","id":"seo","label":"SEO","builtIn":true}]'::jsonb)
       on conflict (id) do update
         set name = excluded.name,
             slug = excluded.slug,
@@ -259,7 +259,7 @@ export const pgMigrations: Migration[] = [
 
       insert into data_tables (id, name, slug, kind, route_base, singular_label, plural_label, primary_field_id, system, fields_json)
       values ('pages', 'Pages', 'pages', 'page', '', 'Page', 'Pages', 'title', true,
-        '[{"type":"text","id":"title","label":"Title","required":true,"builtIn":true},{"type":"text","id":"slug","label":"Slug","required":true,"builtIn":true},{"type":"pageTree","id":"body","label":"Body","required":true,"builtIn":true},{"type":"text","id":"seoTitle","label":"SEO title","builtIn":true},{"type":"longText","id":"seoDescription","label":"SEO description","builtIn":true},{"type":"boolean","id":"templateEnabled","label":"Template","builtIn":true},{"type":"longText","id":"templateTarget","label":"Template target","builtIn":true},{"type":"number","id":"templatePriority","label":"Template priority","integer":true,"builtIn":true}]'::jsonb)
+        '[{"type":"text","id":"title","label":"Title","required":true,"builtIn":true},{"type":"text","id":"slug","label":"Slug","required":true,"builtIn":true},{"type":"pageTree","id":"body","label":"Body","required":true,"builtIn":true},{"type":"seoMetadata","id":"seo","label":"SEO","builtIn":true},{"type":"boolean","id":"templateEnabled","label":"Template","builtIn":true},{"type":"longText","id":"templateTarget","label":"Template target","builtIn":true},{"type":"number","id":"templatePriority","label":"Template priority","integer":true,"builtIn":true}]'::jsonb)
       on conflict (id) do update
         set name = excluded.name,
             slug = excluded.slug,
diff --git a/server/db/migrations-sqlite.ts b/server/db/migrations-sqlite.ts
index 206b50b5a..c44ac5ee8 100644
--- a/server/db/migrations-sqlite.ts
+++ b/server/db/migrations-sqlite.ts
@@ -223,7 +223,7 @@ export const sqliteMigrations: Migration[] = [
 
       insert into data_tables (id, name, slug, kind, route_base, singular_label, plural_label, primary_field_id, system, fields_json)
       values ('posts', 'Posts', 'posts', 'postType', '/posts', 'Post', 'Posts', 'title', 1,
-        '[{"type":"text","id":"title","label":"Title","required":true,"builtIn":true},{"type":"text","id":"slug","label":"Slug","required":true,"builtIn":true},{"type":"richText","id":"body","label":"Body","format":"markdown","builtIn":true},{"type":"media","id":"featuredMedia","label":"Featured media","mediaKind":"image","builtIn":true},{"type":"text","id":"seoTitle","label":"SEO title","builtIn":true},{"type":"longText","id":"seoDescription","label":"SEO description","builtIn":true}]')
+        '[{"type":"text","id":"title","label":"Title","required":true,"builtIn":true},{"type":"text","id":"slug","label":"Slug","required":true,"builtIn":true},{"type":"richText","id":"body","label":"Body","format":"markdown","builtIn":true},{"type":"media","id":"featuredMedia","label":"Featured media","mediaKind":"image","builtIn":true},{"type":"seoMetadata","id":"seo","label":"SEO","builtIn":true}]')
       on conflict (id) do update
         set name = excluded.name,
             slug = excluded.slug,
@@ -239,7 +239,7 @@ export const sqliteMigrations: Migration[] = [
 
       insert into data_tables (id, name, slug, kind, route_base, singular_label, plural_label, primary_field_id, system, fields_json)
       values ('pages', 'Pages', 'pages', 'page', '', 'Page', 'Pages', 'title', 1,
-        '[{"type":"text","id":"title","label":"Title","required":true,"builtIn":true},{"type":"text","id":"slug","label":"Slug","required":true,"builtIn":true},{"type":"pageTree","id":"body","label":"Body","required":true,"builtIn":true},{"type":"text","id":"seoTitle","label":"SEO title","builtIn":true},{"type":"longText","id":"seoDescription","label":"SEO description","builtIn":true},{"type":"boolean","id":"templateEnabled","label":"Template","builtIn":true},{"type":"longText","id":"templateTarget","label":"Template target","builtIn":true},{"type":"number","id":"templatePriority","label":"Template priority","integer":true,"builtIn":true}]')
+        '[{"type":"text","id":"title","label":"Title","required":true,"builtIn":true},{"type":"text","id":"slug","label":"Slug","required":true,"builtIn":true},{"type":"pageTree","id":"body","label":"Body","required":true,"builtIn":true},{"type":"seoMetadata","id":"seo","label":"SEO","builtIn":true},{"type":"boolean","id":"templateEnabled","label":"Template","builtIn":true},{"type":"longText","id":"templateTarget","label":"Template target","builtIn":true},{"type":"number","id":"templatePriority","label":"Template priority","integer":true,"builtIn":true}]')
       on conflict (id) do update
         set name = excluded.name,
             slug = excluded.slug,
diff --git a/src/__tests__/architecture/data-tables-system-flag.test.ts b/src/__tests__/architecture/data-tables-system-flag.test.ts
index a728d51b0..07c68e101 100644
--- a/src/__tests__/architecture/data-tables-system-flag.test.ts
+++ b/src/__tests__/architecture/data-tables-system-flag.test.ts
@@ -75,8 +75,7 @@ describe('data_tables system seeds — four tables present after fresh boot', ()
     expect(builtInIds).toContain('slug')
     expect(builtInIds).toContain('body')
     expect(builtInIds).toContain('featuredMedia')
-    expect(builtInIds).toContain('seoTitle')
-    expect(builtInIds).toContain('seoDescription')
+    expect(builtInIds).toContain('seo')
   })
 
   test('pages fields_json parses and contains expected builtIn field ids', () => {
@@ -88,8 +87,7 @@ describe('data_tables system seeds — four tables present after fresh boot', ()
     expect(builtInIds).toContain('title')
     expect(builtInIds).toContain('slug')
     expect(builtInIds).toContain('body')
-    expect(builtInIds).toContain('seoTitle')
-    expect(builtInIds).toContain('seoDescription')
+    expect(builtInIds).toContain('seo')
     expect(builtInIds).toContain('templateEnabled')
     expect(builtInIds).toContain('templateTarget')
     expect(builtInIds).toContain('templatePriority')
diff --git a/src/__tests__/data/contentAdmin.test.tsx b/src/__tests__/data/contentAdmin.test.tsx
index ad5a366f6..bd5be7b5f 100644
--- a/src/__tests__/data/contentAdmin.test.tsx
+++ b/src/__tests__/data/contentAdmin.test.tsx
@@ -49,8 +49,7 @@ const allBuiltInFields = [
   { type: 'text', id: 'slug', label: 'Slug', required: true, builtIn: true },
   { type: 'richText', id: 'body', label: 'Body', format: 'markdown', builtIn: true },
   { type: 'media', id: 'featuredMedia', label: 'Featured media', mediaKind: 'image', builtIn: true },
-  { type: 'text', id: 'seoTitle', label: 'SEO title', builtIn: true },
-  { type: 'longText', id: 'seoDescription', label: 'SEO description', builtIn: true },
+  { type: 'seoMetadata', id: 'seo', label: 'SEO', builtIn: true },
 ]
 
 const titleOnlyFields = [
@@ -121,8 +120,7 @@ function makeRow(
     slug: 'untitled',
     body: '',
     featuredMedia: null,
-    seoTitle: '',
-    seoDescription: '',
+    seo: {},
     ...cells,
   }
   return {
@@ -337,7 +335,7 @@ beforeEach(() => {
     if (url === '/admin/api/cms/data/rows/entry_1/publish' && init?.method === 'POST') {
       return json({
         row: {
-          ...makeRow('entry_1', 'posts', { title: 'My first post', slug: 'untitled', body: '## Intro', featuredMedia: null, seoTitle: '', seoDescription: '' }),
+          ...makeRow('entry_1', 'posts', { title: 'My first post', slug: 'untitled', body: '## Intro', featuredMedia: null, seo: {} }),
           status: 'published',
           updatedAt: '2026-05-01T10:02:00.000Z',
           publishedAt: '2026-05-01T10:02:00.000Z',
@@ -349,7 +347,7 @@ beforeEach(() => {
       const body = JSON.parse(String(init.body))
       return json({
         row: {
-          ...makeRow('entry_1', 'posts', { title: 'My first post', slug: 'updated-slug', body: '', featuredMedia: imageAsset.id, seoTitle: '', seoDescription: '' }),
+          ...makeRow('entry_1', 'posts', { title: 'My first post', slug: 'updated-slug', body: '', featuredMedia: imageAsset.id, seo: {} }),
           status: body.status,
           updatedAt: '2026-05-01T10:03:00.000Z',
         },
@@ -627,8 +625,7 @@ describe('ContentPage', () => {
             slug: 'authored-post',
             body: 'Body',
             featuredMedia: null,
-            seoTitle: '',
-            seoDescription: '',
+            seo: {},
           }, {
             authorUserId: editorAuthor.id,
             author: editorAuthor,
@@ -643,8 +640,7 @@ describe('ContentPage', () => {
             slug: 'authored-post',
             body: 'Body',
             featuredMedia: null,
-            seoTitle: '',
-            seoDescription: '',
+            seo: {},
           }, {
             authorUserId: adminAuthor.id,
             author: adminAuthor,
@@ -771,8 +767,7 @@ describe('ContentPage', () => {
         slug: 'untitled',
         body: '',
         featuredMedia: null,
-        seoTitle: '',
-        seoDescription: '',
+        seo: {},
       },
     }))
     expect(calls.some((call) =>
@@ -919,8 +914,7 @@ describe('ContentPage', () => {
             slug: 'portable-lamp',
             body: 'A compact lamp',
             featuredMedia: imageAsset.id,
-            seoTitle: 'SEO lamp',
-            seoDescription: 'Lamp description',
+            seo: { title: 'SEO lamp', description: 'Lamp description' },
           }, { updatedAt: '2026-05-01T10:01:00.000Z' })],
         })
       }
@@ -932,8 +926,7 @@ describe('ContentPage', () => {
             slug: 'portable-lamp',
             body: 'A compact lamp',
             featuredMedia: imageAsset.id,
-            seoTitle: 'SEO lamp',
-            seoDescription: 'Lamp description',
+            seo: { title: 'SEO lamp', description: 'Lamp description' },
           }, { updatedAt: '2026-05-01T10:05:00.000Z' }),
         })
       }
@@ -945,8 +938,7 @@ describe('ContentPage', () => {
             slug: 'portable-lamp',
             body: 'A compact lamp',
             featuredMedia: imageAsset.id,
-            seoTitle: 'SEO lamp',
-            seoDescription: 'Lamp description',
+            seo: { title: 'SEO lamp', description: 'Lamp description' },
           }, { updatedAt: '2026-05-01T10:05:00.000Z' })],
         })
       }
@@ -1005,8 +997,8 @@ describe('ContentPage', () => {
       if (url === '/admin/api/cms/data/tables/posts/rows' && init?.method === 'GET') {
         return json({
           rows: [
-            makeRow('entry_1', 'posts', { title: 'Summer sale', slug: 'summer-sale', body: 'Sale copy', featuredMedia: null, seoTitle: '', seoDescription: '' }, { updatedAt: '2026-05-01T10:01:00.000Z' }),
-            makeRow('entry_2', 'posts', { title: 'Published story', slug: 'published-story', body: 'Published copy', featuredMedia: null, seoTitle: '', seoDescription: '' }, { status: 'published', updatedAt: '2026-05-01T10:02:00.000Z', publishedAt: '2026-05-01T10:02:00.000Z' }),
+            makeRow('entry_1', 'posts', { title: 'Summer sale', slug: 'summer-sale', body: 'Sale copy', featuredMedia: null, seo: {} }, { updatedAt: '2026-05-01T10:01:00.000Z' }),
+            makeRow('entry_2', 'posts', { title: 'Published story', slug: 'published-story', body: 'Published copy', featuredMedia: null, seo: {} }, { status: 'published', updatedAt: '2026-05-01T10:02:00.000Z', publishedAt: '2026-05-01T10:02:00.000Z' }),
           ],
         })
       }
@@ -1027,20 +1019,20 @@ describe('ContentPage', () => {
 
       if (url === '/admin/api/cms/data/rows/entry_1/publish' && init?.method === 'POST') {
         return json({
-          row: makeRow('entry_1', 'posts', { title: 'Summer sale', slug: 'summer-sale', body: 'Sale copy', featuredMedia: null, seoTitle: '', seoDescription: '' }, { status: 'published', updatedAt: '2026-05-01T10:03:00.000Z', publishedAt: '2026-05-01T10:03:00.000Z' }),
+          row: makeRow('entry_1', 'posts', { title: 'Summer sale', slug: 'summer-sale', body: 'Sale copy', featuredMedia: null, seo: {} }, { status: 'published', updatedAt: '2026-05-01T10:03:00.000Z', publishedAt: '2026-05-01T10:03:00.000Z' }),
         })
       }
 
       if (url === '/admin/api/cms/data/rows/entry_2/status' && init?.method === 'PATCH') {
         const body = JSON.parse(String(init.body))
         return json({
-          row: makeRow('entry_2', 'posts', { title: 'Published story', slug: 'published-story', body: 'Published copy', featuredMedia: null, seoTitle: '', seoDescription: '' }, { status: body.status, updatedAt: '2026-05-01T10:04:00.000Z' }),
+          row: makeRow('entry_2', 'posts', { title: 'Published story', slug: 'published-story', body: 'Published copy', featuredMedia: null, seo: {} }, { status: body.status, updatedAt: '2026-05-01T10:04:00.000Z' }),
         })
       }
 
       if (url === '/admin/api/cms/data/rows/entry_1' && init?.method === 'DELETE') {
         return json({
-          row: makeRow('entry_1', 'posts', { title: 'Winter sale', slug: 'winter-sale', body: 'Sale copy', featuredMedia: null, seoTitle: '', seoDescription: '' }, { updatedAt: '2026-05-01T10:06:00.000Z', deletedAt: '2026-05-01T10:06:00.000Z' }),
+          row: makeRow('entry_1', 'posts', { title: 'Winter sale', slug: 'winter-sale', body: 'Sale copy', featuredMedia: null, seo: {} }, { updatedAt: '2026-05-01T10:06:00.000Z', deletedAt: '2026-05-01T10:06:00.000Z' }),
         })
       }
 
@@ -1129,8 +1121,7 @@ describe('ContentPage', () => {
           slug: 'winter-sale',
           body: 'Sale copy',
           featuredMedia: null,
-          seoTitle: '',
-          seoDescription: '',
+          seo: {},
         },
       })
     )).toBe(true)
@@ -1291,8 +1282,7 @@ describe('ContentPage', () => {
         slug: 'untitled',
         body: '![hero.png](/uploads/hero.png)',
         featuredMedia: null,
-        seoTitle: '',
-        seoDescription: '',
+        seo: {},
       },
     }))
   })
@@ -1346,8 +1336,7 @@ describe('ContentPage', () => {
         slug: 'updated-slug',
         body: '',
         featuredMedia: imageAsset.id,
-        seoTitle: '',
-        seoDescription: '',
+        seo: {},
       },
     }))
     expect(calls.some((call) =>
@@ -1368,8 +1357,7 @@ describe('ContentPage', () => {
             slug: 'first-post',
             body: '',
             featuredMedia: imageAsset.id,
-            seoTitle: '',
-            seoDescription: '',
+            seo: {},
           }, {
             status: 'published',
             updatedAt: '2026-05-01T10:01:00.000Z',
diff --git a/src/admin/pages/content/ContentPage.tsx b/src/admin/pages/content/ContentPage.tsx
index 669548920..cbca58121 100644
--- a/src/admin/pages/content/ContentPage.tsx
+++ b/src/admin/pages/content/ContentPage.tsx
@@ -5,6 +5,7 @@ import {
 } from '@site/layout/panelLayoutStorage'
 import { useAdminUi } from '@admin/state/adminUi'
 import { readTitleCell } from '@core/data/cells'
+import { draftSeoCell } from './hooks/useContentEntryDraft'
 import type {
   DataTable,
   DataRow,
@@ -244,8 +245,7 @@ export function ContentPage() {
               ...entry.cells,
               body: draft.body,
               featuredMedia: draft.featuredMediaId,
-              seoTitle: draft.seoTitle,
-              seoDescription: draft.seoDescription,
+              seo: draftSeoCell(entry.cells, draft.seoTitle, draft.seoDescription),
             },
           }
         : entry
@@ -290,8 +290,7 @@ export function ContentPage() {
               ...entry.cells,
               body: draft.body,
               featuredMedia: draft.featuredMediaId,
-              seoTitle: draft.seoTitle,
-              seoDescription: draft.seoDescription,
+              seo: draftSeoCell(entry.cells, draft.seoTitle, draft.seoDescription),
               title: draft.title || readTitleCell(entry.cells),
             },
           }
diff --git a/src/admin/pages/content/agent/ContentAgentMount.tsx b/src/admin/pages/content/agent/ContentAgentMount.tsx
index 4b6fa7c0c..b1a1224bf 100644
--- a/src/admin/pages/content/agent/ContentAgentMount.tsx
+++ b/src/admin/pages/content/agent/ContentAgentMount.tsx
@@ -295,11 +295,15 @@ function applyFieldsToDraft(
       case 'body':
         if (typeof raw === 'string') draft.setBody(raw)
         break
-      case 'seoTitle':
-        if (typeof raw === 'string') draft.setSeoTitle(raw)
-        break
-      case 'seoDescription':
-        if (typeof raw === 'string') draft.setSeoDescription(raw)
+      case 'seo':
+        // Structured SEO object — the draft hook merges title/description
+        // into `cells.seo` on save; other SEO fields are owned by the SEO
+        // workspace and not editable through the content agent.
+        if (raw && typeof raw === 'object' && !Array.isArray(raw)) {
+          const seo = raw as { title?: unknown; description?: unknown }
+          if (typeof seo.title === 'string') draft.setSeoTitle(seo.title)
+          if (typeof seo.description === 'string') draft.setSeoDescription(seo.description)
+        }
         break
       case 'featuredMedia':
         if (raw === null) draft.setFeaturedMediaId(null)
@@ -315,8 +319,8 @@ function applyFieldsToDraft(
         // different field id rather than silently dropping the value.
         throw new Error(
           `Field "${key}" is not editable via the agent yet. ` +
-          'Only built-in fields (title, slug, body, featuredMedia, ' +
-          'seoTitle, seoDescription) are supported in this version.',
+          'Only built-in fields (title, slug, body, featuredMedia, seo) ' +
+          'are supported in this version.',
         )
     }
   }
diff --git a/src/admin/pages/content/components/ContentCollectionCreateDialog/ContentCollectionCreateDialog.tsx b/src/admin/pages/content/components/ContentCollectionCreateDialog/ContentCollectionCreateDialog.tsx
index dd99f8c37..0e48c3737 100644
--- a/src/admin/pages/content/components/ContentCollectionCreateDialog/ContentCollectionCreateDialog.tsx
+++ b/src/admin/pages/content/components/ContentCollectionCreateDialog/ContentCollectionCreateDialog.tsx
@@ -7,8 +7,7 @@ import { buildPostTypeDefaultFields } from '@core/data/fields'
 import {
   POST_TYPE_FIELD_BODY,
   POST_TYPE_FIELD_FEATURED_MEDIA,
-  POST_TYPE_FIELD_SEO_TITLE,
-  POST_TYPE_FIELD_SEO_DESCRIPTION,
+  POST_TYPE_FIELD_SEO,
   type CreateDataTableInput,
 } from '@core/data/schemas'
 import dialogStyles from '../../../../shared/dialogs/SiteCreateDialog/SiteCreateDialog.module.css'
@@ -93,7 +92,7 @@ export function ContentCollectionCreateDialog({
         fields: buildPostTypeDefaultFields().filter((field) => {
           if (field.id === POST_TYPE_FIELD_BODY) return bodyField
           if (field.id === POST_TYPE_FIELD_FEATURED_MEDIA) return featuredMediaField
-          if (field.id === POST_TYPE_FIELD_SEO_TITLE || field.id === POST_TYPE_FIELD_SEO_DESCRIPTION) return seoField
+          if (field.id === POST_TYPE_FIELD_SEO) return seoField
           return true
         }),
       })
diff --git a/src/admin/pages/content/components/ContentCollectionSettingsDialog/ContentCollectionSettingsDialog.tsx b/src/admin/pages/content/components/ContentCollectionSettingsDialog/ContentCollectionSettingsDialog.tsx
index 156619f80..2cb30a7fa 100644
--- a/src/admin/pages/content/components/ContentCollectionSettingsDialog/ContentCollectionSettingsDialog.tsx
+++ b/src/admin/pages/content/components/ContentCollectionSettingsDialog/ContentCollectionSettingsDialog.tsx
@@ -3,8 +3,7 @@ import { buildPostTypeDefaultFields, dataTableHasField } from '@core/data/fields
 import {
   POST_TYPE_FIELD_BODY,
   POST_TYPE_FIELD_FEATURED_MEDIA,
-  POST_TYPE_FIELD_SEO_TITLE,
-  POST_TYPE_FIELD_SEO_DESCRIPTION,
+  POST_TYPE_FIELD_SEO,
   type DataTable,
   type UpdateDataTableInput,
 } from '@core/data/schemas'
@@ -46,7 +45,7 @@ export function ContentCollectionSettingsDialog({
   const [pluralLabel, setPluralLabel] = useState(collection.pluralLabel)
   const [bodyField, setBodyField] = useState(dataTableHasField(collection, POST_TYPE_FIELD_BODY))
   const [featuredMediaField, setFeaturedMediaField] = useState(dataTableHasField(collection, POST_TYPE_FIELD_FEATURED_MEDIA))
-  const [seoField, setSeoField] = useState(dataTableHasField(collection, POST_TYPE_FIELD_SEO_TITLE))
+  const [seoField, setSeoField] = useState(dataTableHasField(collection, POST_TYPE_FIELD_SEO))
   const [submitError, setSubmitError] = useState<string | null>(null)
   const inputRef = useRef<HTMLInputElement>(null)
   const nameId = useId()
@@ -80,7 +79,7 @@ export function ContentCollectionSettingsDialog({
       const nextFields = buildPostTypeDefaultFields().filter((field) => {
         if (field.id === POST_TYPE_FIELD_BODY) return bodyField
         if (field.id === POST_TYPE_FIELD_FEATURED_MEDIA) return featuredMediaField
-        if (field.id === POST_TYPE_FIELD_SEO_TITLE || field.id === POST_TYPE_FIELD_SEO_DESCRIPTION) return seoField
+        if (field.id === POST_TYPE_FIELD_SEO) return seoField
         return true
       })
       await onSave({
diff --git a/src/admin/pages/content/components/ContentSettingsPanel/ContentSettingsPanel.tsx b/src/admin/pages/content/components/ContentSettingsPanel/ContentSettingsPanel.tsx
index 03a8f55ee..9bc627185 100644
--- a/src/admin/pages/content/components/ContentSettingsPanel/ContentSettingsPanel.tsx
+++ b/src/admin/pages/content/components/ContentSettingsPanel/ContentSettingsPanel.tsx
@@ -9,7 +9,7 @@ import { useEditorStore } from '@site/store/store'
 import { dataTableHasField } from '@core/data/fields'
 import {
   POST_TYPE_FIELD_FEATURED_MEDIA,
-  POST_TYPE_FIELD_SEO_TITLE,
+  POST_TYPE_FIELD_SEO,
   type DataTable,
   type DataRow,
   type DataRowStatus,
@@ -105,7 +105,7 @@ export function ContentSettingsPanel({
   onEditFeaturedMedia,
 }: ContentSettingsPanelProps) {
   const setPropertiesPanel = useEditorStore((s) => s.setPropertiesPanel)
-  const seoEnabled = selectedCollection ? dataTableHasField(selectedCollection, POST_TYPE_FIELD_SEO_TITLE) : false
+  const seoEnabled = selectedCollection ? dataTableHasField(selectedCollection, POST_TYPE_FIELD_SEO) : false
   const featuredMediaEnabled = selectedCollection ? dataTableHasField(selectedCollection, POST_TYPE_FIELD_FEATURED_MEDIA) : false
   const authorRoleLabel = selectedEntry ? contentAuthorRoleLabel(selectedEntry) : null
   const selectedAuthor = selectedEntry ? contentAuthor(selectedEntry) : null
diff --git a/src/admin/pages/content/hooks/useContentEntryDraft.ts b/src/admin/pages/content/hooks/useContentEntryDraft.ts
index 358bac8c0..9ee1b7d52 100644
--- a/src/admin/pages/content/hooks/useContentEntryDraft.ts
+++ b/src/admin/pages/content/hooks/useContentEntryDraft.ts
@@ -8,16 +8,38 @@ import type { DataRow, DataRowStatus } from '@core/data/schemas'
 import {
   readBodyCell,
   readFeaturedMediaCell,
-  readSeoDescriptionCell,
-  readSeoTitleCell,
+  readSeoCell,
   readSlugCell,
   readTitleCell,
 } from '@core/data/cells'
 import { slugFromTitle } from '@core/utils/slug'
+import type { SeoMetadata } from '@core/seo'
 import { getErrorMessage } from '@core/utils/errorMessage'
 
 export type SaveMessage = 'idle' | 'saving' | 'saved' | 'publishing' | 'published' | 'error'
 
+/**
+ * Merge the content panel's SEO title/description draft strings into the
+ * row's existing structured `seo` cell. The SEO workspace owns the other
+ * fields (OG/X/canonical/noindex) — they must survive a content-panel save
+ * untouched. Empty draft strings remove the corresponding key.
+ */
+export function draftSeoCell(
+  cells: DataRow['cells'],
+  seoTitle: string,
+  seoDescription: string,
+): SeoMetadata {
+  const existing = readSeoCell(cells) ?? {}
+  const next: SeoMetadata = { ...existing }
+  const title = seoTitle.trim()
+  const description = seoDescription.trim()
+  if (title === '') delete next.title
+  else next.title = title
+  if (description === '') delete next.description
+  else next.description = description
+  return next
+}
+
 interface UseContentEntryDraftOptions {
   selectedEntry: DataRow | null
   updateSelectedEntry: (entry: DataRow) => void
@@ -51,8 +73,8 @@ export function useContentEntryDraft({
   const applySelectedEntry = useCallback((entry: DataRow | null) => {
     setTitle(entry ? readTitleCell(entry.cells) : '')
     setSlug(entry ? readSlugCell(entry.cells) : '')
-    setSeoTitle(entry ? readSeoTitleCell(entry.cells) : '')
-    setSeoDescription(entry ? readSeoDescriptionCell(entry.cells) : '')
+    setSeoTitle(entry ? (readSeoCell(entry.cells)?.title ?? '') : '')
+    setSeoDescription(entry ? (readSeoCell(entry.cells)?.description ?? '') : '')
     setFeaturedMediaId(entry ? readFeaturedMediaCell(entry.cells) : null)
     setBody(entry ? readBodyCell(entry.cells) : '')
     setSaveMessage('idle')
@@ -67,8 +89,8 @@ export function useContentEntryDraft({
   const applyEntryFields = (entry: DataRow) => {
     setTitle(readTitleCell(entry.cells))
     setSlug(readSlugCell(entry.cells))
-    setSeoTitle(readSeoTitleCell(entry.cells))
-    setSeoDescription(readSeoDescriptionCell(entry.cells))
+    setSeoTitle(readSeoCell(entry.cells)?.title ?? '')
+    setSeoDescription(readSeoCell(entry.cells)?.description ?? '')
     setFeaturedMediaId(readFeaturedMediaCell(entry.cells))
   }
 
@@ -76,8 +98,8 @@ export function useContentEntryDraft({
     if (!selectedEntry) return false
     return title !== readTitleCell(selectedEntry.cells) ||
       slug !== readSlugCell(selectedEntry.cells) ||
-      seoTitle !== readSeoTitleCell(selectedEntry.cells) ||
-      seoDescription !== readSeoDescriptionCell(selectedEntry.cells) ||
+      seoTitle !== (readSeoCell(selectedEntry.cells)?.title ?? '') ||
+      seoDescription !== (readSeoCell(selectedEntry.cells)?.description ?? '') ||
       featuredMediaId !== readFeaturedMediaCell(selectedEntry.cells) ||
       body !== readBodyCell(selectedEntry.cells)
   })()
@@ -93,8 +115,7 @@ export function useContentEntryDraft({
         slug: nextSlug,
         body,
         featuredMedia: featuredMediaId,
-        seoTitle: seoTitle.trim(),
-        seoDescription: seoDescription.trim(),
+        seo: draftSeoCell(selectedEntry.cells, seoTitle, seoDescription),
       },
     })
     updateSelectedEntry(row)
diff --git a/src/admin/pages/content/hooks/useContentWorkspace.ts b/src/admin/pages/content/hooks/useContentWorkspace.ts
index b6a7a52de..b962a9a43 100644
--- a/src/admin/pages/content/hooks/useContentWorkspace.ts
+++ b/src/admin/pages/content/hooks/useContentWorkspace.ts
@@ -25,8 +25,6 @@ import type {
 import {
   readBodyCell,
   readFeaturedMediaCell,
-  readSeoDescriptionCell,
-  readSeoTitleCell,
 } from '@core/data/cells'
 import { buildDuplicateRowCells } from '@core/data/duplicateRow'
 import { updateRowList } from '@content/utils/contentEntryUtils'
@@ -329,8 +327,6 @@ export function useContentWorkspace({
         slug: input.slug,
         body: readBodyCell(row.cells),
         featuredMedia: readFeaturedMediaCell(row.cells),
-        seoTitle: readSeoTitleCell(row.cells),
-        seoDescription: readSeoDescriptionCell(row.cells),
       },
     })
     setEntries((current) => updateRowList(current, updatedRow))
diff --git a/src/admin/pages/data/components/DataGrid/cells/CellDisplayRenderer.tsx b/src/admin/pages/data/components/DataGrid/cells/CellDisplayRenderer.tsx
index 7a00d14f6..ebea705e1 100644
--- a/src/admin/pages/data/components/DataGrid/cells/CellDisplayRenderer.tsx
+++ b/src/admin/pages/data/components/DataGrid/cells/CellDisplayRenderer.tsx
@@ -17,6 +17,7 @@ import {
   readBooleanCell,
   readFieldSchemaCell,
   readNodeTreeCell,
+  readSeoCell,
   readNumberCell,
   readStringArrayCell,
   readStringCell,
@@ -436,6 +437,11 @@ export function CellDisplayRenderer({
       const label = params.length === 1 ? '1 param' : `${params.length} params`
       return <span className={styles.text}>{label}</span>
     }
+    case 'seoMetadata': {
+      const seo = readSeoCell(cells)
+      if (!seo || Object.keys(seo).length === 0) return <Empty />
+      return <span className={styles.text}>{seo.title ?? 'SEO set'}</span>
+    }
     default: {
       const _exhaustive: never = field
       void _exhaustive
diff --git a/src/admin/pages/data/components/DataGrid/cells/CellEditorRenderer.tsx b/src/admin/pages/data/components/DataGrid/cells/CellEditorRenderer.tsx
index 62fb4d319..8d99b9235 100644
--- a/src/admin/pages/data/components/DataGrid/cells/CellEditorRenderer.tsx
+++ b/src/admin/pages/data/components/DataGrid/cells/CellEditorRenderer.tsx
@@ -94,6 +94,11 @@ export function CellEditorRenderer({
     case 'fieldSchema':
       return <FieldSchemaCell field={field} {...rest} onOpenFieldEditor={onOpenFieldEditor} />
 
+    case 'seoMetadata':
+      // Structured SEO objects are edited in the SEO workspace
+      // (/admin/tools/seo), not inline in the grid.
+      return <span>Edited in the SEO workspace</span>
+
     default: {
       // Exhaustive check: TypeScript will error here if a new field type
       // is added to the discriminated union without a case above.
diff --git a/src/admin/pages/data/components/DataInspector/fieldEditState.ts b/src/admin/pages/data/components/DataInspector/fieldEditState.ts
index e4ecc134f..cab3b7916 100644
--- a/src/admin/pages/data/components/DataInspector/fieldEditState.ts
+++ b/src/admin/pages/data/components/DataInspector/fieldEditState.ts
@@ -199,6 +199,8 @@ export function applyEditState(
       return { type: 'pageTree', ...common }
     case 'fieldSchema':
       return { type: 'fieldSchema', ...common }
+    case 'seoMetadata':
+      return { type: 'seoMetadata', ...common }
     default: {
       const _exhaustive: never = field
       void _exhaustive
diff --git a/src/admin/pages/data/components/DataInspector/fieldGuards.ts b/src/admin/pages/data/components/DataInspector/fieldGuards.ts
index 20b3a1f7a..6bbeb8cf6 100644
--- a/src/admin/pages/data/components/DataInspector/fieldGuards.ts
+++ b/src/admin/pages/data/components/DataInspector/fieldGuards.ts
@@ -4,7 +4,7 @@
  *
  * PostType field guards:
  *   - Mandatory built-ins (title, slug): locked — no edit/delete.
- *   - Optional built-ins (body, featuredMedia, seoTitle, seoDescription):
+ *   - Optional built-ins (body, featuredMedia, seo):
  *     deletable; editable for description/required only.
  *   - Custom non-built-in fields: fully editable and deletable.
  */
@@ -32,6 +32,7 @@ export const FIELD_TYPE_LABELS: Record<DataFieldType, string> = {
   relation: 'Relation',
   pageTree: 'Page tree',
   fieldSchema: 'Field schema',
+  seoMetadata: 'SEO metadata',
 }
 
 export function isMandatoryField(fieldId: string): boolean {
diff --git a/src/admin/pages/data/utils/fieldDefaults.ts b/src/admin/pages/data/utils/fieldDefaults.ts
index 5be2ca7c0..eb49ef23f 100644
--- a/src/admin/pages/data/utils/fieldDefaults.ts
+++ b/src/admin/pages/data/utils/fieldDefaults.ts
@@ -46,6 +46,9 @@ export function emptyCellValue(field: DataField): unknown {
     case 'fieldSchema':
       return []
 
+    case 'seoMetadata':
+      return {}
+
     default: {
       const _exhaustive: never = field
       void _exhaustive
diff --git a/src/admin/pages/data/utils/fieldIcons.ts b/src/admin/pages/data/utils/fieldIcons.ts
index d61e651a4..c8685ec0c 100644
--- a/src/admin/pages/data/utils/fieldIcons.ts
+++ b/src/admin/pages/data/utils/fieldIcons.ts
@@ -14,6 +14,7 @@ import { ImageSolidIcon } from 'pixel-art-icons/icons/image-solid'
 import { LinkIcon } from 'pixel-art-icons/icons/link'
 import { LayoutSolidIcon } from 'pixel-art-icons/icons/layout-solid'
 import { BracesIcon } from 'pixel-art-icons/icons/braces'
+import { SearchSolidIcon } from 'pixel-art-icons/icons/search-solid'
 
 const FIELD_ICONS: Record<DataFieldType, IconComponent> = {
   text: TextStartTIcon,
@@ -32,6 +33,7 @@ const FIELD_ICONS: Record<DataFieldType, IconComponent> = {
   // Structural field types: visual page-node tree and component parameter schema.
   pageTree: LayoutSolidIcon,
   fieldSchema: BracesIcon,
+  seoMetadata: SearchSolidIcon,
 }
 
 export function getFieldIcon(type: DataFieldType): IconComponent {
diff --git a/src/admin/pages/site/property-controls/DynamicBindingControl/BindingPickerPopover.tsx b/src/admin/pages/site/property-controls/DynamicBindingControl/BindingPickerPopover.tsx
index 71b8649c4..75b2c7ecd 100644
--- a/src/admin/pages/site/property-controls/DynamicBindingControl/BindingPickerPopover.tsx
+++ b/src/admin/pages/site/property-controls/DynamicBindingControl/BindingPickerPopover.tsx
@@ -82,8 +82,6 @@ const POST_TYPE_ONLY_LOOP_FIELDS = new Set([
   'body',
   'featuredMedia',
   'firstImage',
-  'seoTitle',
-  'seoDescription',
 ])
 
 // ---------------------------------------------------------------------------
diff --git a/src/admin/pages/site/property-controls/bindingCompatibility.ts b/src/admin/pages/site/property-controls/bindingCompatibility.ts
index 0721ebc40..14a7bdb9a 100644
--- a/src/admin/pages/site/property-controls/bindingCompatibility.ts
+++ b/src/admin/pages/site/property-controls/bindingCompatibility.ts
@@ -29,8 +29,9 @@ export type DynamicBindingMode = 'token' | 'structured'
  *   TypeBox validation will coerce unknown dynamic values back to defaults.
  * - `color` has no binding mode until data has a first-class color field type.
  * - `group` has no meaningful scalar binding target.
- * - `pageTree` and `fieldSchema` are structural cell types that hold whole
- *   documents (a page-node tree and a DataField[] array). They are not
+ * - `pageTree`, `fieldSchema`, and `seoMetadata` are structural cell types
+ *   that hold whole documents (a page-node tree, a DataField[] array, an SEO
+ *   object). They are not
  *   bindable to any property control — page authors cannot wire a page tree
  *   or a field-schema array directly to a node prop. They appear in `group`
  *   solely to satisfy the binding-compatibility-coverage architecture test,
@@ -58,7 +59,7 @@ export const BINDING_COMPATIBILITY: Record<PropertyControlKind, readonly DataFie
   // Structural (document-level) types: not scalar-bindable, listed here for
   // coverage-test completeness only — the picker excludes them from the
   // binding catalog via buildMetaFields in src/core/data/fields.ts.
-  group:    ['pageTree', 'fieldSchema'],
+  group:    ['pageTree', 'fieldSchema', 'seoMetadata'],
 }
 
 /**
diff --git a/src/core/data/cells.ts b/src/core/data/cells.ts
index a97e8c67a..2397ca7ad 100644
--- a/src/core/data/cells.ts
+++ b/src/core/data/cells.ts
@@ -9,6 +9,7 @@
 
 import { NodeTreeSchema, type NodeTree } from '@core/page-tree'
 import type { BaseNode } from '@core/page-tree'
+import { parseSeoMetadata, type SeoMetadata } from '@core/seo'
 import { DataFieldSchema, type DataField, type DataRowCells, type DataTable } from './schemas'
 import { dataTableHasField } from './fields'
 import { slugFromTitle } from '@core/utils/slug'
@@ -72,12 +73,13 @@ export function readFeaturedMediaCell(cells: DataRowCells): string | null {
   return readNullableStringCell(cells, 'featuredMedia')
 }
 
-export function readSeoTitleCell(cells: DataRowCells): string {
-  return readStringCell(cells, 'seoTitle')
-}
-
-export function readSeoDescriptionCell(cells: DataRowCells): string {
-  return readStringCell(cells, 'seoDescription')
+/**
+ * Read the structured `seo` cell (built-in `seoMetadata` field). Returns
+ * `undefined` when the cell is missing or malformed — a corrupt SEO object
+ * must never block loading the row.
+ */
+export function readSeoCell(cells: DataRowCells): SeoMetadata | undefined {
+  return parseSeoMetadata(cells.seo)
 }
 
 /**
diff --git a/src/core/data/fields.ts b/src/core/data/fields.ts
index e9e6aa7bf..0cef75f08 100644
--- a/src/core/data/fields.ts
+++ b/src/core/data/fields.ts
@@ -17,8 +17,7 @@ import {
   DataFieldSchema,
   POST_TYPE_FIELD_BODY,
   POST_TYPE_FIELD_FEATURED_MEDIA,
-  POST_TYPE_FIELD_SEO_DESCRIPTION,
-  POST_TYPE_FIELD_SEO_TITLE,
+  POST_TYPE_FIELD_SEO,
   POST_TYPE_FIELD_SLUG,
   POST_TYPE_FIELD_TITLE,
   POST_TYPE_MANDATORY_FIELD_IDS,
@@ -83,10 +82,11 @@ function buildMetaFields(
       }
       if (field.allowMultiple !== undefined) entry.allowMultiple = field.allowMultiple
       result.push(entry)
-    } else if (field.type === 'pageTree' || field.type === 'fieldSchema') {
+    } else if (field.type === 'pageTree' || field.type === 'fieldSchema' || field.type === 'seoMetadata') {
       // Structural types — not part of the instatic binding catalog.
-      // pageTree and fieldSchema cells hold whole documents (tree/field array),
-      // not scalar values that can be bound to a property control.
+      // pageTree / fieldSchema / seoMetadata cells hold whole documents
+      // (tree / field array / SEO object), not scalar values that can be
+      // bound to a property control.
       continue
     } else {
       result.push({ id: field.id, label: field.label, type: field.type })
@@ -152,15 +152,9 @@ export function buildPostTypeDefaultFields(): DataField[] {
       builtIn: true,
     },
     {
-      type: 'text',
-      id: POST_TYPE_FIELD_SEO_TITLE,
-      label: 'SEO title',
-      builtIn: true,
-    },
-    {
-      type: 'longText',
-      id: POST_TYPE_FIELD_SEO_DESCRIPTION,
-      label: 'SEO description',
+      type: 'seoMetadata',
+      id: POST_TYPE_FIELD_SEO,
+      label: 'SEO',
       builtIn: true,
     },
   ]
diff --git a/src/core/data/pageFromRow.ts b/src/core/data/pageFromRow.ts
index aff3b658a..53a6c959d 100644
--- a/src/core/data/pageFromRow.ts
+++ b/src/core/data/pageFromRow.ts
@@ -11,6 +11,7 @@
  *   cells.templateEnabled    → page.template.enabled
  *   cells.templateTarget     → page.template.target (stored as JSON object)
  *   cells.templatePriority   → page.template.priority
+ *   cells.seo                → page.seo (structured SeoMetadata)
  *
  * Ownership is mapped between DataRow user-id columns and Page optional fields:
  *   row.authorUserId        → page.ownerUserId
@@ -20,7 +21,8 @@
 
 import type { Page, PageNode, PageTemplateConfig } from '@core/page-tree'
 import { parsePageTemplate } from '@core/page-tree'
-import type { DataRow, DataRowCells } from '@core/data/schemas'
+import { parseSeoMetadata } from '@core/seo'
+import type { DataRow, DataRowCells } from './schemas'
 
 // ---------------------------------------------------------------------------
 // DataRow → Page
@@ -55,6 +57,7 @@ export function pageFromRow(row: DataRow): Page {
 
   // Template reconstruction
   const template = readTemplateFromCells(cells)
+  const seo = parseSeoMetadata(cells.seo)
 
   return {
     id: row.id,
@@ -63,6 +66,7 @@ export function pageFromRow(row: DataRow): Page {
     nodes,
     rootNodeId,
     ...(template !== null ? { template } : {}),
+    ...(seo !== undefined ? { seo } : {}),
     ownerUserId: row.authorUserId ?? null,
     createdByUserId: row.createdByUserId ?? null,
     updatedByUserId: row.updatedByUserId ?? null,
@@ -105,5 +109,9 @@ export function pageToCells(page: Page): DataRowCells {
     cells.templatePriority = page.template.priority
   }
 
+  if (page.seo) {
+    cells.seo = page.seo
+  }
+
   return cells
 }
diff --git a/src/core/data/schemas.ts b/src/core/data/schemas.ts
index d9b1a0896..5eb806362 100644
--- a/src/core/data/schemas.ts
+++ b/src/core/data/schemas.ts
@@ -9,7 +9,7 @@
  *
  *   - `kind: 'postType'` — authored through the Content admin page. Has
  *     reserved built-in fields (`title`, `slug`, `body`, `featuredMedia`,
- *     `seoTitle`, `seoDescription`) and a draft / published / unpublished
+ *     `seo`) and a draft / published / unpublished
  *     workflow with versions.
  *   - `kind: 'data'` — authored through the Data admin page (grid). No
  *     built-ins, no version workflow.
@@ -222,6 +222,17 @@ const FieldSchemaFieldSchema = Type.Object({
   ...FieldCommonProps,
 })
 
+/**
+ * SeoMetadata field — stores the structured SEO object (`SeoMetadata` from
+ * `@core/seo`) in the cell. Built-in only: shipped as the `seo` field on
+ * `page` and `postType` tables, never offered as a user-created custom field
+ * type. Its editing surface is the SEO workspace (`/admin/tools/seo`).
+ */
+const SeoMetadataFieldSchema = Type.Object({
+  type: Type.Literal('seoMetadata'),
+  ...FieldCommonProps,
+})
+
 export const DataFieldSchema = Type.Union([
   TextFieldSchema,
   LongTextFieldSchema,
@@ -238,6 +249,7 @@ export const DataFieldSchema = Type.Union([
   RelationFieldSchema,
   PageTreeFieldSchema,
   FieldSchemaFieldSchema,
+  SeoMetadataFieldSchema,
 ])
 
 export type DataField = Static<typeof DataFieldSchema>
@@ -266,6 +278,7 @@ export const DATA_FIELD_TYPES = [
   'relation',
   'pageTree',
   'fieldSchema',
+  'seoMetadata',
 ] as const
 
 export type DataFieldType = (typeof DATA_FIELD_TYPES)[number]
@@ -470,7 +483,7 @@ export type DataRowRedirect = Static<typeof DataRowRedirectSchema>
 // Tables with `kind: 'postType'` always start with these field ids. The
 // Content authoring UI reads/writes these specific keys in `cells_json`.
 // Users CAN remove most of them per-table (e.g. a Quotes post type can
-// drop `body`, `featuredMedia`, `seoTitle`, `seoDescription`) — but
+// drop `body`, `featuredMedia`, `seo`) — but
 // `title` and `slug` are mandatory for any post-type table.
 // ---------------------------------------------------------------------------
 
@@ -478,8 +491,7 @@ export const POST_TYPE_FIELD_TITLE = 'title'
 export const POST_TYPE_FIELD_SLUG = 'slug'
 export const POST_TYPE_FIELD_BODY = 'body'
 export const POST_TYPE_FIELD_FEATURED_MEDIA = 'featuredMedia'
-export const POST_TYPE_FIELD_SEO_TITLE = 'seoTitle'
-export const POST_TYPE_FIELD_SEO_DESCRIPTION = 'seoDescription'
+export const POST_TYPE_FIELD_SEO = 'seo'
 
 export const POST_TYPE_MANDATORY_FIELD_IDS = [
   POST_TYPE_FIELD_TITLE,
@@ -489,8 +501,7 @@ export const POST_TYPE_MANDATORY_FIELD_IDS = [
 export const POST_TYPE_OPTIONAL_BUILTIN_FIELD_IDS = [
   POST_TYPE_FIELD_BODY,
   POST_TYPE_FIELD_FEATURED_MEDIA,
-  POST_TYPE_FIELD_SEO_TITLE,
-  POST_TYPE_FIELD_SEO_DESCRIPTION,
+  POST_TYPE_FIELD_SEO,
 ] as const
 
 // ---------------------------------------------------------------------------
diff --git a/src/core/forms/validation.ts b/src/core/forms/validation.ts
index 06f63b86b..30e5fce24 100644
--- a/src/core/forms/validation.ts
+++ b/src/core/forms/validation.ts
@@ -144,6 +144,7 @@ function coerceFieldValue(field: DataField, value: unknown): CoerceResult {
       return { ok: true, value: String(value) }
     case 'pageTree':
     case 'fieldSchema':
+    case 'seoMetadata':
       return { ok: false, code: 'unsupported_field', message: 'This field cannot be submitted by a form.' }
   }
 }
diff --git a/src/core/loops/sources/dataRows.ts b/src/core/loops/sources/dataRows.ts
index 9f2d4a957..af12cb570 100644
--- a/src/core/loops/sources/dataRows.ts
+++ b/src/core/loops/sources/dataRows.ts
@@ -871,8 +871,6 @@ export const DataRowsSource: LoopEntitySource = {
     { id: 'body', label: 'Body (post-type, markdown)', format: 'html' },
     { id: 'featuredMedia', label: 'Featured media (post-type)', format: 'media' },
     { id: 'firstImage', label: 'First inline image', format: 'media' },
-    { id: 'seoTitle', label: 'SEO title (post-type)' },
-    { id: 'seoDescription', label: 'SEO description (post-type)' },
     { id: 'permalink', label: 'Permalink', format: 'url' },
     { id: 'publishedAt', label: 'Published date' },
     { id: 'publishedByName', label: 'Published by' },
diff --git a/src/core/page-tree/page.ts b/src/core/page-tree/page.ts
index 2c14479e0..794b6809b 100644
--- a/src/core/page-tree/page.ts
+++ b/src/core/page-tree/page.ts
@@ -18,6 +18,7 @@
  */
 
 import { Type, type Static } from '@core/utils/typeboxHelpers'
+import { SeoMetadataSchema, parseSeoMetadata } from '@core/seo'
 import { NodeTreeSchema } from './treeSchema'
 import { PageNodeSchema, type PageNode, parsePageNode } from './pageNode'
 import { PageTemplateConfigSchema, parsePageTemplate } from './pageTemplate'
@@ -48,6 +49,12 @@ export const PageSchema = Type.Object({
    * Silently dropped if invalid — handled in parsePage.
    */
   template: Type.Optional(PageTemplateConfigSchema),
+  /**
+   * Structured SEO metadata (from `cells_json.seo`). Missing means no
+   * per-page overrides — the publisher falls back to site defaults.
+   * Silently dropped if invalid — handled in parsePage.
+   */
+  seo: Type.Optional(SeoMetadataSchema),
 })
 
 export type Page = Static<typeof PageSchema>
@@ -92,6 +99,7 @@ export function parsePage(raw: unknown, pageIndex: number): Page {
   reindexNodeParents(nodes)
 
   const template = parsePageTemplate(r.template)
+  const seo = parseSeoMetadata(r.seo)
 
   return {
     id: r.id,
@@ -107,5 +115,6 @@ export function parsePage(raw: unknown, pageIndex: number): Page {
     nodes,
     rootNodeId: r.rootNodeId,
     ...(template !== null ? { template } : {}),
+    ...(seo !== undefined ? { seo } : {}),
   }
 }
diff --git a/src/core/page-tree/siteSettings.ts b/src/core/page-tree/siteSettings.ts
index ac01486bf..7e7ed5aa9 100644
--- a/src/core/page-tree/siteSettings.ts
+++ b/src/core/page-tree/siteSettings.ts
@@ -28,6 +28,7 @@ import { Type, type Static } from '@core/utils/typeboxHelpers'
 import { compiledCheck } from '@core/utils/typeboxCompiler'
 import { FrameworkSettingsSchema } from '@core/framework-schema'
 import { SiteFontsSettingsSchema, parseSiteFontsSettings } from '@core/fonts'
+import { SiteSeoSettingsSchema, parseSiteSeoSettings } from '@core/seo'
 
 // ---------------------------------------------------------------------------
 // SiteSettingsSchema
@@ -42,6 +43,8 @@ export const SiteSettingsSchema = Type.Object({
   framework: Type.Optional(FrameworkSettingsSchema),
   /** Library of installed fonts — absent when no fonts added. */
   fonts: Type.Optional(SiteFontsSettingsSchema),
+  /** Site-wide SEO defaults — absent means none configured. */
+  seo: Type.Optional(SiteSeoSettingsSchema),
   /** Keyboard shortcut overrides — defaults to {} — handled in parseSiteSettings. */
   shortcuts: Type.Record(Type.String(), Type.String()),
 })
@@ -86,6 +89,8 @@ export function parseSiteSettings(raw: unknown): SiteSettings {
 
   const fonts = r.fonts != null ? parseSiteFontsSettings(r.fonts) : undefined
 
+  const seo = parseSiteSeoSettings(r.seo)
+
   return {
     ...(typeof r.metaTitle === 'string' ? { metaTitle: r.metaTitle } : {}),
     ...(typeof r.metaDescription === 'string' ? { metaDescription: r.metaDescription } : {}),
@@ -93,6 +98,7 @@ export function parseSiteSettings(raw: unknown): SiteSettings {
     ...(typeof r.language === 'string' ? { language: r.language } : {}),
     framework,
     fonts,
+    seo,
     shortcuts,
   }
 }
diff --git a/src/core/plugin-sdk/types/serverApi.ts b/src/core/plugin-sdk/types/serverApi.ts
index a7a8b9979..8ff550d23 100644
--- a/src/core/plugin-sdk/types/serverApi.ts
+++ b/src/core/plugin-sdk/types/serverApi.ts
@@ -132,7 +132,7 @@ export interface ServerPluginApi {
      *
      *   const pages = api.cms.content.table('pages')
      *   await pages.list({ status: 'published' })
-     *   await pages.update(id, { cells: { seoTitle: '…' } })
+     *   await pages.update(id, { cells: { seo: { title: '…' } } })
      *
      * Schema introspection lives in `content.tables`; tree mutations on
      * `pageTree`-typed fields go through `content.tree(entryId, fieldId)`
diff --git a/src/core/seo/__tests__/jsonLd.test.ts b/src/core/seo/__tests__/jsonLd.test.ts
index d5beda730..d3390abbe 100644
--- a/src/core/seo/__tests__/jsonLd.test.ts
+++ b/src/core/seo/__tests__/jsonLd.test.ts
@@ -106,12 +106,12 @@ describe('buildJsonLdEntities', () => {
 
 describe('serializeJsonLd', () => {
   test('escapes script terminators and comment openers', () => {
-    const out = serializeJsonLd({ name: 'x</script><script>alert(1)</script>', note: '<!-- hi' })
+    const out = serializeJsonLd({ name: 'x</script><script>x()</script>', note: '<!-- hi' })
     expect(out).not.toContain('</script')
     expect(out).not.toContain('<!--')
     // Round-trips back to the original values
     const parsed = JSON.parse(out) as { name: string; note: string }
-    expect(parsed.name).toBe('x</script><script>alert(1)</script>')
+    expect(parsed.name).toBe('x</script><script>x()</script>')
     expect(parsed.note).toBe('<!-- hi')
   })
 })
diff --git a/src/core/seo/__tests__/resolve.test.ts b/src/core/seo/__tests__/resolve.test.ts
index 71689ecff..8f25c9635 100644
--- a/src/core/seo/__tests__/resolve.test.ts
+++ b/src/core/seo/__tests__/resolve.test.ts
@@ -90,7 +90,7 @@ describe('resolveSeoMetadata — canonical / absolute URLs', () => {
       resolveSeoMetadata({
         ...BASE,
         // eslint-disable-next-line no-script-url
-        target: { canonicalUrl: 'javascript:alert(1)' },
+        target: { canonicalUrl: 'javascript:void(0)' },
         origin: 'https://acme.com',
       }).canonicalUrl,
     ).toBe('https://acme.com/about')
@@ -163,7 +163,7 @@ describe('url helpers', () => {
     expect(isSafeCanonicalUrl('https://a.com/x')).toBe(true)
     expect(isSafeCanonicalUrl('http://a.com')).toBe(true)
     // eslint-disable-next-line no-script-url
-    expect(isSafeCanonicalUrl('javascript:alert(1)')).toBe(false)
+    expect(isSafeCanonicalUrl('javascript:void(0)')).toBe(false)
     expect(isSafeCanonicalUrl('/relative')).toBe(false)
   })
 
diff --git a/src/core/templates/templatePreviewData.ts b/src/core/templates/templatePreviewData.ts
index 262cff5f7..e1a6a9677 100644
--- a/src/core/templates/templatePreviewData.ts
+++ b/src/core/templates/templatePreviewData.ts
@@ -18,8 +18,6 @@ import type { DataTable, DataField, DataRowCells } from '@core/data/schemas'
 import {
   POST_TYPE_FIELD_BODY,
   POST_TYPE_FIELD_FEATURED_MEDIA,
-  POST_TYPE_FIELD_SEO_DESCRIPTION,
-  POST_TYPE_FIELD_SEO_TITLE,
   POST_TYPE_FIELD_SLUG,
   POST_TYPE_FIELD_TITLE,
 } from '@core/data/schemas'
@@ -43,9 +41,6 @@ import { normalizeRouteBase } from './templateMatching'
 const POST_TYPE_PREVIEW_VALUE_BY_FIELD_ID: Record<string, string> = {
   [POST_TYPE_FIELD_TITLE]: 'Example Post Title',
   [POST_TYPE_FIELD_SLUG]: 'example-post-title',
-  [POST_TYPE_FIELD_SEO_TITLE]: 'Example Post — Site Name',
-  [POST_TYPE_FIELD_SEO_DESCRIPTION]:
-    'A short description of this example post for search engines.',
   [POST_TYPE_FIELD_BODY]:
     '## Example heading\n\nLorem ipsum dolor sit amet, consectetur adipiscing elit. Pellentesque at porta est.',
 }
@@ -86,6 +81,10 @@ function previewValueForField(field: DataField): unknown {
     // Preview data generation has no meaningful value to produce for them.
     case 'pageTree': return null
     case 'fieldSchema': return []
+    case 'seoMetadata': return {
+      title: 'Example Post — Site Name',
+      description: 'A short description of this example post for search engines.',
+    }
     default: {
       // Exhaustive check: TypeScript will error here if a new field type
       // is added to the discriminated union without a case above.

From 8b24cf518d9812cfd16a5e2c6f2c2d24bf7e3dcd Mon Sep 17 00:00:00 2001
From: DavidBabinec <hello@davidbabinec.com>
Date: Fri, 12 Jun 2026 12:49:15 +0200
Subject: [PATCH 03/26] feat(seo): publisher metadata, JSON-LD, robots.txt and
 sitemap.xml

Publisher head is now driven by the resolved SEO payload (new
src/core/publisher/seoHead.ts): title/description/canonical/noindex,
OG (incl. og:locale, og:url, og:site_name, article times), X cards, and
JSON-LD scripts. Server renderer resolves page/row SEO with the configured
public origin and entry-template patterns; previews share the same
resolver via publishPage's fallback. Legacy site metaTitle/metaDescription
removed in favour of site.settings.seo. First-party GET /robots.txt (with
AI-crawler group toggles) and GET /sitemap.xml (publishVersion-cached)
dispatch before public rendering.

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
---
 server/auth/security.ts                       |  11 +
 server/handlers/cms/siteDiff.ts               |   7 +-
 server/publish/publicRenderer.ts              | 100 ++++++++-
 server/publish/seoEndpoints.ts                | 169 +++++++++++++++
 server/repositories/data/publish.ts           |  50 +++++
 server/router.ts                              |  21 ++
 src/__tests__/persistence.test.ts             |   4 +-
 .../persistence/roundTripFixture.json         |   6 +-
 src/__tests__/publisher/render.test.ts        |  41 +++-
 .../server/capabilityRouteMatrix.test.ts      |   6 +-
 .../server/cmsSitePersistence.test.ts         |   6 +-
 .../server/dynamicIslandsPlugin.test.ts       |   2 +-
 src/__tests__/server/holeRouteHandler.test.ts |   2 +-
 src/__tests__/server/moduleJsRoute.test.ts    |   2 +-
 src/__tests__/server/publicRendering.test.ts  |   5 +-
 .../server/publicRouterCache.test.ts          |   2 +-
 .../server/publishRebakeTemplate.test.ts      |   2 +-
 .../server/publishStaticArtefact.test.ts      |   1 -
 src/__tests__/server/seoEndpoints.test.ts     | 198 ++++++++++++++++++
 .../Settings/sections/GeneralSection.tsx      |  35 +---
 src/core/page-tree/siteSettings.ts            |   4 -
 src/core/publisher/index.ts                   |   2 +-
 src/core/publisher/render.ts                  |  61 ++----
 src/core/publisher/seoHead.ts                 | 159 ++++++++++++++
 24 files changed, 780 insertions(+), 116 deletions(-)
 create mode 100644 server/publish/seoEndpoints.ts
 create mode 100644 src/__tests__/server/seoEndpoints.test.ts
 create mode 100644 src/core/publisher/seoHead.ts

diff --git a/server/auth/security.ts b/server/auth/security.ts
index dea2bdd1f..6f33ddcb8 100644
--- a/server/auth/security.ts
+++ b/server/auth/security.ts
@@ -94,6 +94,17 @@ export function expectedOrigin(req: Request): string {
   return `${proto}://${host}`
 }
 
+/**
+ * The canonical configured public origin (`publicOrigins[0]`), or null when
+ * none is configured. SEO consumers (canonical URLs, og:url, sitemap <loc>,
+ * JSON-LD) use this: published static HTML must NEVER bake a guessed host,
+ * so callers that bake artefacts omit absolute URLs when this is null, while
+ * the dynamic robots/sitemap endpoints fall back to the request origin.
+ */
+export function canonicalPublicOrigin(): string | null {
+  return publicOrigins[0] ?? null
+}
+
 /** True when the canonical configured public origin uses https. */
 export function publicOriginIsHttps(): boolean {
   const configured = publicOrigins[0]
diff --git a/server/handlers/cms/siteDiff.ts b/server/handlers/cms/siteDiff.ts
index 434995600..154d50dbb 100644
--- a/server/handlers/cms/siteDiff.ts
+++ b/server/handlers/cms/siteDiff.ts
@@ -10,7 +10,7 @@
  *   structure — adding / removing / reordering breakpoints, managing files,
  *               toggling fileTypes, modifying packageJson/runtime,
  *               changing site id / name.
- *   content   — settings.metaTitle / settings.metaDescription (authored text
+ *   content   — settings.seo (authored site-wide SEO copy
  *               the "client / copy editor" persona owns).
  *   style     — classes registry contents, settings.framework, settings.fonts,
  *               file contents.
@@ -114,7 +114,7 @@ export function validateSiteWriteDiff(
   }
 
   // Settings — split into chromatic-style fields (framework/fonts) and
-  // structural fields (metaTitle/metaDescription/favicon/language/shortcuts).
+  // content (seo) and structural fields (favicon/language/shortcuts).
   diffSettings(ctx, previous.settings, next.settings)
 
   // breakpoints — adding / removing / reordering is style infra.
@@ -162,8 +162,7 @@ function diffSettings(
 
   // Content fields — site-wide SEO copy that the copy-editor persona owns.
   const contentKeys: Array<keyof SiteShell['settings']> = [
-    'metaTitle',
-    'metaDescription',
+    'seo',
   ]
   for (const key of contentKeys) {
     if (!deepEqual(prev[key], next[key])) {
diff --git a/server/publish/publicRenderer.ts b/server/publish/publicRenderer.ts
index 58c3256f9..02cebe05f 100644
--- a/server/publish/publicRenderer.ts
+++ b/server/publish/publicRenderer.ts
@@ -1,8 +1,12 @@
 import '../../src/modules/base'
 import '@core/loops/sources'
 import { registry } from '@core/module-engine'
-import { publishPage } from '@core/publisher'
-import { buildRouteFrame } from '@core/templates/contextFrames'
+import { publishPage, type PublishedSeo } from '@core/publisher'
+import { buildPageFrame, buildRouteFrame, buildSiteFrame } from '@core/templates/contextFrames'
+import { interpolateTokens } from '@core/templates/tokenInterpolation'
+import { readSeoCell, readTitleCell } from '@core/data/cells'
+import { resolveSeoMetadata, buildJsonLdEntities } from '@core/seo'
+import { canonicalPublicOrigin } from '../auth/security'
 import { buildPublishedSiteCssBundle } from './siteCssBundle'
 import { buildPublishedSiteModuleJsMap } from './moduleJsBundle'
 import { resolveTemplateChain, composeTemplateChain } from '@core/templates'
@@ -10,7 +14,7 @@ import type { TemplateRenderDataContext } from '@core/templates/dynamicBindings'
 import { prefetchLoopData, publishedDataRowToLoopItem } from './loopPrefetch'
 import { prefetchMediaAssets } from './mediaPrefetch'
 import { getPublishVersion } from './publishState'
-import type { Page } from '@core/page-tree'
+import type { Page, SiteDocument } from '@core/page-tree'
 import type { SiteCssBundle } from '@core/publisher'
 import type { PublishedDataRow } from '@core/data/schemas'
 import type { DbClient } from '../db/client'
@@ -77,6 +81,86 @@ export interface RenderPublishedSnapshotContext {
   publishVersion?: number
 }
 
+/**
+ * Resolve the SEO payload for a published PAGE route. The configured public
+ * origin (when present) yields absolute canonical/og:url values that are
+ * safe to bake into static artefacts; with no origin configured those tags
+ * are omitted rather than guessed.
+ */
+function buildPageRenderSeo(page: Page, site: SiteDocument): PublishedSeo {
+  const origin = canonicalPublicOrigin() ?? undefined
+  const pageFrame = buildPageFrame(page)
+  const context: TemplateRenderDataContext = {
+    entryStack: [],
+    page: pageFrame,
+    site: buildSiteFrame(site),
+    route: buildRouteFrame(pageFrame.permalink),
+  }
+  const resolved = resolveSeoMetadata({
+    target: page.seo,
+    siteSeo: site.settings.seo,
+    siteName: site.name,
+    baseTitle: page.title,
+    routeKind: 'page',
+    routePath: pageFrame.permalink,
+    origin,
+    language: site.settings.language,
+    interpolate: (pattern) => interpolateTokens(pattern, context),
+  })
+  const jsonLd = buildJsonLdEntities(resolved, {
+    kind: 'page',
+    routePath: pageFrame.permalink,
+    origin,
+    siteName: site.name,
+    organization: site.settings.seo?.organization,
+  })
+  return { resolved, jsonLd }
+}
+
+/**
+ * Resolve the SEO payload for a published ROW route. The row's own
+ * `cells.seo` wins; the entry template's `seo` (innermost chain element —
+ * broadest → narrowest ordering) provides token-bearing title/description
+ * patterns; site defaults close the chain. `article:*_time` comes from the
+ * active version's publish timestamp.
+ */
+function buildRowRenderSeo(
+  row: PublishedDataRow,
+  site: SiteDocument,
+  entryTemplate: Page | undefined,
+  templateContext: TemplateRenderDataContext,
+): PublishedSeo {
+  const origin = canonicalPublicOrigin() ?? undefined
+  const routePath = `${row.tableRouteBase}/${row.slug}`
+  const context: TemplateRenderDataContext = {
+    ...templateContext,
+    site: templateContext.site ?? buildSiteFrame(site),
+    route: templateContext.route ?? buildRouteFrame(routePath),
+  }
+  const resolved = resolveSeoMetadata({
+    target: readSeoCell(row.cells),
+    templateSeo: entryTemplate?.seo,
+    siteSeo: site.settings.seo,
+    siteName: site.name,
+    baseTitle: readTitleCell(row.cells),
+    routeKind: 'row',
+    routePath,
+    origin,
+    language: site.settings.language,
+    publishedAt: row.publishedAt,
+    updatedAt: row.publishedAt,
+    interpolate: (pattern) => interpolateTokens(pattern, context),
+  })
+  const jsonLd = buildJsonLdEntities(resolved, {
+    kind: 'row',
+    routePath,
+    origin,
+    siteName: site.name,
+    organization: site.settings.seo?.organization,
+  })
+  return { resolved, jsonLd }
+}
+
 /**
  * Shared render tail for both public paths. Given an already-resolved,
  * composed `merged` tree and its seed `templateContext`, this owns the
@@ -90,6 +174,7 @@ async function renderMergedTemplate(
   snapshot: PublishedPageSnapshot,
   templateContext: TemplateRenderDataContext | undefined,
   ctx: RenderPublishedSnapshotContext,
+  seo: PublishedSeo,
 ): Promise<{ html: string; jsModuleIds: string[]; publishVersion: number; cssBundle: SiteCssBundle }> {
   const publishVersion = ctx.publishVersion ?? getPublishVersion()
   const cssBundle = buildPublishedSiteCssBundle(snapshot.site, registry, merged, publishVersion)
@@ -100,6 +185,7 @@ async function renderMergedTemplate(
   ])
   const published = publishPage(merged, snapshot.site, registry, {
     templateContext,
+    seo,
     runtimeAssets: snapshot.runtimeAssets,
     runtimePackageImportmap: snapshot.runtimePackageImportmap,
     cssEmission: 'external',
@@ -137,7 +223,8 @@ export async function renderPublishedSnapshot(
     ? { entryStack: [], route: buildRouteFrame(ctx.url.toString()) }
     : undefined
 
-  const rendered = await renderMergedTemplate(merged, snapshot, templateContext, ctx)
+  const seo = buildPageRenderSeo(page, snapshot.site)
+  const rendered = await renderMergedTemplate(merged, snapshot, templateContext, ctx, seo)
   return { ...rendered, pageId: snapshot.pageRowId, slug: page.slug, siteId: snapshot.site.id }
 }
 
@@ -161,6 +248,9 @@ export async function renderPublishedDataRowTemplate(
     ...(ctx.url ? { route: buildRouteFrame(ctx.url.toString()) } : {}),
   }
 
-  const rendered = await renderMergedTemplate(merged, snapshot, templateContext, ctx)
+  // The entry template is the narrowest chain element (broadest → narrowest).
+  const entryTemplate = chain.at(-1)
+  const seo = buildRowRenderSeo(row, snapshot.site, entryTemplate, templateContext)
+  const rendered = await renderMergedTemplate(merged, snapshot, templateContext, ctx, seo)
   return { ...rendered, pageId: merged.id, slug: merged.slug, siteId: snapshot.site.id }
 }
diff --git a/server/publish/seoEndpoints.ts b/server/publish/seoEndpoints.ts
new file mode 100644
index 000000000..3bd89d844
--- /dev/null
+++ b/server/publish/seoEndpoints.ts
@@ -0,0 +1,169 @@
+/**
+ * First-party `GET /robots.txt` and `GET /sitemap.xml`.
+ *
+ * Both are generated from the PUBLISHED snapshot (SEO follows the publish
+ * lifecycle — draft edits appear after the next publish) and cached keyed by
+ * `publishVersion`, the same invalidation discipline as the Layer B render
+ * cache: first request after a publish regenerates, `bumpPublishVersion()`
+ * turns the cached body stale.
+ *
+ * Origin resolution: the configured canonical public origin wins; these
+ * endpoints are dynamic (never baked to disk), so with nothing configured
+ * they fall back to the request origin. Because the body embeds the origin,
+ * the cache only serves a hit when the origin matches the cached one.
+ *
+ * Dispatched by `server/router.ts` BEFORE static assets and public page
+ * rendering — `/robots.txt` must never fall through to an HTML response.
+ */
+
+import type { DbClient } from '../db/client'
+import { isTemplatePage } from '@core/templates'
+import {
+  generateRobotsTxt,
+  parseSeoMetadata,
+  absoluteUrl,
+  type SiteSeoSettings,
+} from '@core/seo'
+import { canonicalPublicOrigin } from '../auth/security'
+import { listPublishedRowsForSitemap } from '../repositories/data/publish'
+import { getLatestSnapshotForVersion } from './publishedSnapshotCache'
+import { getPublishVersion } from './publishState'
+
+// ---------------------------------------------------------------------------
+// publishVersion-keyed cache
+// ---------------------------------------------------------------------------
+
+interface CachedSeoFile {
+  version: number
+  origin: string
+  body: string
+}
+
+let robotsCache: CachedSeoFile | null = null
+let sitemapCache: CachedSeoFile | null = null
+
+/** Test seam — drop both cached bodies. */
+export function resetSeoEndpointCachesForTests(): void {
+  robotsCache = null
+  sitemapCache = null
+}
+
+function escapeXml(value: string): string {
+  return value
+    .replaceAll('&', '&amp;')
+    .replaceAll('<', '&lt;')
+    .replaceAll('>', '&gt;')
+    .replaceAll('"', '&quot;')
+    .replaceAll("'", '&apos;')
+}
+
+/**
+ * Resolve the origin these files embed: configured canonical origin first,
+ * request origin as the dynamic-endpoint fallback.
+ */
+function resolveOrigin(url: URL): string {
+  return canonicalPublicOrigin() ?? url.origin
+}
+
+async function publishedSeoSettings(db: DbClient): Promise<SiteSeoSettings | undefined> {
+  const snapshot = await getLatestSnapshotForVersion(db, getPublishVersion())
+  return snapshot?.site.settings.seo
+}
+
+// ---------------------------------------------------------------------------
+// robots.txt
+// ---------------------------------------------------------------------------
+
+export async function serveRobotsTxt(db: DbClient, url: URL): Promise<Response> {
+  const version = getPublishVersion()
+  const origin = resolveOrigin(url)
+
+  if (!robotsCache || robotsCache.version !== version || robotsCache.origin !== origin) {
+    const seo = await publishedSeoSettings(db)
+    const body = generateRobotsTxt({
+      robots: seo?.robots,
+      sitemapEnabled: seo?.sitemap?.enabled !== false,
+      origin,
+    })
+    robotsCache = { version, origin, body }
+  }
+
+  return new Response(robotsCache.body, {
+    headers: { 'content-type': 'text/plain; charset=utf-8' },
+  })
+}
+
+// ---------------------------------------------------------------------------
+// sitemap.xml
+// ---------------------------------------------------------------------------
+
+interface SitemapEntry {
+  loc: string
+  lastmod?: string
+}
+
+async function collectSitemapEntries(db: DbClient, origin: string): Promise<SitemapEntry[]> {
+  const snapshot = await getLatestSnapshotForVersion(db, getPublishVersion())
+  if (!snapshot) return []
+
+  const seo = snapshot.site.settings.seo
+  const excluded = new Set(seo?.sitemap?.excludedTargets ?? [])
+  const entries: SitemapEntry[] = []
+
+  // Published routable pages — templates are never directly routable, and
+  // noindex pages exclude themselves.
+  for (const page of snapshot.site.pages) {
+    if (isTemplatePage(page)) continue
+    if (page.seo?.noindex === true) continue
+    if (excluded.has(`page:${page.id}`)) continue
+    const slug = page.slug.replace(/^\/+/, '')
+    const routePath = slug === 'index' || slug === '' ? '/' : `/${slug}`
+    entries.push({ loc: absoluteUrl(origin, routePath) })
+  }
+
+  // Published post-type rows with route bases.
+  const rows = await listPublishedRowsForSitemap(db)
+  for (const row of rows) {
+    const rowSeo = parseSeoMetadata(row.cells.seo)
+    if (rowSeo?.noindex === true) continue
+    if (excluded.has(`row:${row.rowId}`)) continue
+    entries.push({
+      loc: absoluteUrl(origin, `${row.tableRouteBase}/${row.rowSlug}`),
+      lastmod: row.publishedAt,
+    })
+  }
+
+  return entries
+}
+
+export async function serveSitemapXml(db: DbClient, url: URL): Promise<Response> {
+  const version = getPublishVersion()
+  const origin = resolveOrigin(url)
+
+  const seo = await publishedSeoSettings(db)
+  if (seo?.sitemap?.enabled === false) {
+    return new Response('Not found', {
+      status: 404,
+      headers: { 'content-type': 'text/plain; charset=utf-8' },
+    })
+  }
+
+  if (!sitemapCache || sitemapCache.version !== version || sitemapCache.origin !== origin) {
+    const entries = await collectSitemapEntries(db, origin)
+    const urls = entries
+      .map((entry) => {
+        const lastmod = entry.lastmod ? `\n    <lastmod>${escapeXml(entry.lastmod)}</lastmod>` : ''
+        return `  <url>\n    <loc>${escapeXml(entry.loc)}</loc>${lastmod}\n  </url>`
+      })
+      .join('\n')
+    const body =
+      '<?xml version="1.0" encoding="UTF-8"?>\n' +
+      '<urlset xmlns="http://www.sitemaps.org/schemas/sitemap/0.9">\n' +
+      `${urls}${urls ? '\n' : ''}</urlset>\n`
+    sitemapCache = { version, origin, body }
+  }
+
+  return new Response(sitemapCache.body, {
+    headers: { 'content-type': 'application/xml; charset=utf-8' },
+  })
+}
diff --git a/server/repositories/data/publish.ts b/server/repositories/data/publish.ts
index a695aa261..115d900df 100644
--- a/server/repositories/data/publish.ts
+++ b/server/repositories/data/publish.ts
@@ -16,6 +16,7 @@
  *                                   when the URL belongs to a
  *                                   previously-published slug
  *   listPublishedRowRoutes        — every published row route (for the bake)
+ *   listPublishedRowsForSitemap   — row routes + cells/publish time (sitemap)
  *   getRowTableRouteInfo          — route base + table slug for one row
  *   getRowTableRouteBase          — route base only, ignoring soft deletes
  *
@@ -331,6 +332,55 @@ export async function listPublishedRowRoutes(db: DbClient): Promise<PublishedRow
   }))
 }
 
+export interface PublishedRowSitemapEntry {
+  rowId: string
+  rowSlug: string
+  tableRouteBase: string
+  /** Active published version's cells — read `cells.seo` for noindex. */
+  cells: Record<string, unknown>
+  /** ISO datetime the active version was published — sitemap <lastmod>. */
+  publishedAt: string
+}
+
+/**
+ * Every published, routable data row with the cells and publish timestamp
+ * the sitemap generator needs. Same row set as `listPublishedRowRoutes`,
+ * plus `cells_json` (for the structured `seo.noindex` flag) and the active
+ * version's publish time (for `<lastmod>`).
+ */
+export async function listPublishedRowsForSitemap(
+  db: DbClient,
+): Promise<PublishedRowSitemapEntry[]> {
+  const { rows } = await db<{
+    row_id: string
+    row_slug: string
+    table_route_base: string
+    cells_json: Record<string, unknown>
+    published_at: string
+  }>`
+    select data_rows.id as row_id,
+           data_row_versions.slug as row_slug,
+           data_tables.route_base as table_route_base,
+           data_row_versions.cells_json,
+           data_row_versions.published_at
+    from data_rows
+    join data_tables on data_tables.id = data_rows.table_id
+    join data_row_versions on data_row_versions.id = data_rows.active_version_id
+    where data_rows.table_id <> 'pages'
+      and data_rows.status = 'published'
+      and data_rows.deleted_at is null
+      and data_tables.deleted_at is null
+    order by data_rows.created_at asc
+  `
+  return rows.map((row) => ({
+    rowId: row.row_id,
+    rowSlug: row.row_slug,
+    tableRouteBase: normalizeRouteBase(row.table_route_base),
+    cells: row.cells_json,
+    publishedAt: row.published_at,
+  }))
+}
+
 /**
  * Resolve a public URL (tableRouteBase + rowSlug) to the active published
  * version of a data row.
diff --git a/server/router.ts b/server/router.ts
index f2653da71..5480156d1 100644
--- a/server/router.ts
+++ b/server/router.ts
@@ -11,6 +11,7 @@ import { handleLoopRequest, isLoopRuntimeAssetPath, serveLoopRuntimeAsset } from
 import { handleHoleRequest, isHoleRuntimeAssetPath, serveHoleRuntimeAsset } from './handlers/cms/hole'
 import { handleModuleJsAssetRequest, isModuleJsAssetPath } from './handlers/cms/moduleJs'
 import { handlePublicFormRequest } from './forms/handler'
+import { serveRobotsTxt, serveSitemapXml } from './publish/seoEndpoints'
 import { isRuntimePackagePath, tryServeRuntimePackage } from './publish/runtime/packageServer'
 import { jsonResponse } from './http'
 import { binaryResponse, toArrayBuffer } from './binary'
@@ -76,6 +77,10 @@ const routes: readonly RouteHandler[] = [
   tryServeRuntimePackageNamespace,
   tryServeSiteCssNamespace,
   tryServeMediaRedirect,
+  // robots.txt + sitemap.xml are first-party generated files. They dispatch
+  // BEFORE static assets and public page rendering so neither path can be
+  // shadowed by an uploaded file or fall through to an HTML response.
+  tryServeSeoFiles,
   tryServeStaticAsset,
   tryServeUpload,
   tryServeAdminApp,
@@ -421,6 +426,22 @@ async function tryServeAdminApp(
  * fast-path (pre-rendered static artefacts via `readArtefact`), then
  * `resolvePublicRoute`, then the live renderer + `applyPublishedHtmlPipeline`.
  */
+/**
+ * First-party robots.txt / sitemap.xml — generated from the published
+ * snapshot with publishVersion-keyed caching (`server/publish/seoEndpoints.ts`).
+ */
+function tryServeSeoFiles(
+  req: Request,
+  runtime: ServerRuntime,
+  url: URL,
+  pathname: string,
+): Promise<Response> | null {
+  if (req.method !== 'GET' && req.method !== 'HEAD') return null
+  if (pathname === '/robots.txt') return serveRobotsTxt(runtime.db, url)
+  if (pathname === '/sitemap.xml') return serveSitemapXml(runtime.db, url)
+  return null
+}
+
 async function tryServePublicRoute(req: Request, runtime: ServerRuntime, url: URL, _pathname: string): Promise<Response | null> {
   if (req.method !== 'GET') return null
   return await renderPublicResolution(runtime.db, url, runtime.uploadsDir)
diff --git a/src/__tests__/persistence.test.ts b/src/__tests__/persistence.test.ts
index 78570807a..ff85c9e9b 100644
--- a/src/__tests__/persistence.test.ts
+++ b/src/__tests__/persistence.test.ts
@@ -112,10 +112,10 @@ describe('validateSite — happy path', () => {
   it('accepts settings with all optional fields', () => {
     const p = validSite()
     p.settings.language = 'fr'
-    p.settings.metaTitle = 'My Site'
+    p.settings.seo = { titlePattern: '{page.title} — My Site' }
     const result = validateSite(p)
     expect(result.settings.language).toBe('fr')
-    expect(result.settings.metaTitle).toBe('My Site')
+    expect(result.settings.seo?.titlePattern).toBe('{page.title} — My Site')
   })
 
   it('fills defaults for missing settings sub-fields', () => {
diff --git a/src/__tests__/persistence/roundTripFixture.json b/src/__tests__/persistence/roundTripFixture.json
index 399ce05b6..c96c8df5a 100644
--- a/src/__tests__/persistence/roundTripFixture.json
+++ b/src/__tests__/persistence/roundTripFixture.json
@@ -204,8 +204,10 @@
     }
   },
   "settings": {
-    "metaTitle": "My Round-Trip Site",
-    "metaDescription": "Testing round-trips",
+    "seo": {
+      "titlePattern": "{page.title} — My Round-Trip Site",
+      "description": "Testing round-trips"
+    },
     "language": "en",
     "shortcuts": { "save": "ctrl+s" },
     "framework": {
diff --git a/src/__tests__/publisher/render.test.ts b/src/__tests__/publisher/render.test.ts
index b01c86c01..fbc7f1352 100644
--- a/src/__tests__/publisher/render.test.ts
+++ b/src/__tests__/publisher/render.test.ts
@@ -1009,25 +1009,50 @@ describe('publishPage', () => {
     expect(html).not.toContain('zustand')
   })
 
-  it('uses site metaTitle for <title> when set', () => {
-    const proj = makeSite({
-      settings: { ...makeSite().settings, metaTitle: 'My Site — Home' },
-    })
+  it('uses the page seo title for <title> when set', () => {
     const page = makePage({ root: { moduleId: 'base.text', props: { text: 'Hi' } } })
-    const { html } = publishPage(page, proj, registry)
+    page.seo = { title: 'My Site — Home', description: 'A fine page.' }
+    const { html } = publishPage(page, makeSite(), registry)
     expect(html).toContain('<title>My Site — Home</title>')
+    expect(html).toContain('<meta name="description" content="A fine page.">')
   })
 
-  it('XSS: escapes metaTitle with special chars', () => {
+  it('interpolates the site title pattern around the page title', () => {
     const proj = makeSite({
       settings: {
         ...makeSite().settings,
-        metaTitle: '<script>alert(1)</script>',
+        seo: { titlePattern: '{page.title} — {site.name}' },
       },
     })
     const page = makePage({ root: { moduleId: 'base.text', props: { text: 'Hi' } } })
     const { html } = publishPage(page, proj, registry)
-    expect(html).not.toContain('<script>')
+    expect(html).toContain(`<title>${page.title} — ${proj.name}</title>`)
+  })
+
+  it('emits OG/X tags and noindex from the seo object', () => {
+    const page = makePage({ root: { moduleId: 'base.text', props: { text: 'Hi' } } })
+    page.seo = {
+      title: 'T',
+      ogImage: '/img.png',
+      ogImageAlt: 'An image',
+      noindex: true,
+    }
+    const { html } = publishPage(page, makeSite(), registry)
+    expect(html).toContain('<meta name="robots" content="noindex">')
+    expect(html).toContain('<meta property="og:title" content="T">')
+    expect(html).toContain('<meta property="og:image" content="/img.png">')
+    expect(html).toContain('<meta property="og:image:alt" content="An image">')
+    expect(html).toContain('<meta name="twitter:card" content="summary_large_image">')
+    // No origin available in the core fallback — absolute URLs must be omitted.
+    expect(html).not.toContain('rel="canonical"')
+    expect(html).not.toContain('og:url')
+  })
+
+  it('XSS: escapes seo title with special chars', () => {
+    const page = makePage({ root: { moduleId: 'base.text', props: { text: 'Hi' } } })
+    page.seo = { title: '<script>alert(1)</script>' }
+    const { html } = publishPage(page, makeSite(), registry)
+    expect(html).not.toContain('<script>alert')
     expect(html).toContain('&lt;script&gt;')
   })
 })
diff --git a/src/__tests__/server/capabilityRouteMatrix.test.ts b/src/__tests__/server/capabilityRouteMatrix.test.ts
index 9635ff267..e52262092 100644
--- a/src/__tests__/server/capabilityRouteMatrix.test.ts
+++ b/src/__tests__/server/capabilityRouteMatrix.test.ts
@@ -61,7 +61,7 @@ describe('capability route matrix', () => {
       const baseShell = await loadSiteShell(harness, ownerCookie)
       const contentEdit: SiteShell = {
         ...baseShell,
-        settings: { ...baseShell.settings, metaTitle: 'Client-owned title' },
+        settings: { ...baseShell.settings, seo: { titlePattern: 'Client-owned title' } },
       }
       const contentAllowed = await harness.cms('/admin/api/cms/site', {
         method: 'PUT',
@@ -108,7 +108,7 @@ describe('capability route matrix', () => {
         json: {
           site: {
             ...afterStyle,
-            settings: { ...afterStyle.settings, metaTitle: 'Style cannot edit copy' },
+            settings: { ...afterStyle.settings, seo: { titlePattern: 'Style cannot edit copy' } },
           },
         },
       })
@@ -129,7 +129,7 @@ describe('capability route matrix', () => {
         json: {
           site: {
             ...afterStructure,
-            settings: { ...afterStructure.settings, metaDescription: 'Structure cannot edit copy' },
+            settings: { ...afterStructure.settings, seo: { description: 'Structure cannot edit copy' } },
           },
         },
       })
diff --git a/src/__tests__/server/cmsSitePersistence.test.ts b/src/__tests__/server/cmsSitePersistence.test.ts
index e75b39af7..6fbc01cdb 100644
--- a/src/__tests__/server/cmsSitePersistence.test.ts
+++ b/src/__tests__/server/cmsSitePersistence.test.ts
@@ -54,7 +54,7 @@ function validShell(overrides: Partial<SiteShell> = {}): SiteShell {
       { id: 'desktop', label: 'Desktop', width: 1440, icon: 'monitor' },
     ],
     settings: {
-      metaTitle: 'Example',
+      seo: { titlePattern: '{page.title} — Example' },
       shortcuts: {},
     },
     styleRules: {
@@ -86,7 +86,7 @@ describe('CMS draft site persistence', () => {
       cmsSiteSchemaVersion: 1,
       site: {
         id: 'project_1',
-        settings: { metaTitle: 'Example' },
+        settings: { seo: { titlePattern: '{page.title} — Example' } },
         styleRules: { class_1: { name: 'Hero' } },
       },
     })
@@ -101,7 +101,7 @@ describe('CMS draft site persistence', () => {
     expect(loaded).toMatchObject({
       id: 'project_1',
       name: 'Example Site',
-      settings: { metaTitle: 'Example' },
+      settings: { seo: { titlePattern: '{page.title} — Example' } },
       styleRules: { class_1: { name: 'Hero' } },
     })
     // Shell does not include pages — pages live in data_rows
diff --git a/src/__tests__/server/dynamicIslandsPlugin.test.ts b/src/__tests__/server/dynamicIslandsPlugin.test.ts
index befe8b099..c4639255e 100644
--- a/src/__tests__/server/dynamicIslandsPlugin.test.ts
+++ b/src/__tests__/server/dynamicIslandsPlugin.test.ts
@@ -147,7 +147,7 @@ function makeSnapshotWithLoop(loopNodeId: string, sourceId: string) {
       files: [],
       visualComponents: [],
       breakpoints: [{ id: 'desktop', label: 'Desktop', width: 1440, icon: 'monitor' }],
-      settings: { metaTitle: 'Test', shortcuts: {} },
+      settings: { shortcuts: {} },
       styleRules: {},
       createdAt: 1000,
       updatedAt: 2000,
diff --git a/src/__tests__/server/holeRouteHandler.test.ts b/src/__tests__/server/holeRouteHandler.test.ts
index b042e7b14..d72be6315 100644
--- a/src/__tests__/server/holeRouteHandler.test.ts
+++ b/src/__tests__/server/holeRouteHandler.test.ts
@@ -66,7 +66,7 @@ function makeSnapshot() {
       files: [],
       visualComponents: [],
       breakpoints: [{ id: 'desktop', label: 'Desktop', width: 1440, icon: 'monitor' }],
-      settings: { metaTitle: 'Test', shortcuts: {} },
+      settings: { shortcuts: {} },
       styleRules: {},
       createdAt: 1000,
       updatedAt: 2000,
diff --git a/src/__tests__/server/moduleJsRoute.test.ts b/src/__tests__/server/moduleJsRoute.test.ts
index 69d57dc29..ad259935e 100644
--- a/src/__tests__/server/moduleJsRoute.test.ts
+++ b/src/__tests__/server/moduleJsRoute.test.ts
@@ -49,7 +49,7 @@ function makeSnapshot() {
       files: [],
       visualComponents: [],
       breakpoints: [{ id: 'desktop', label: 'Desktop', width: 1440, icon: 'monitor' }],
-      settings: { metaTitle: 'Test', shortcuts: {} },
+      settings: { shortcuts: {} },
       styleRules: {},
       createdAt: 1000,
       updatedAt: 2000,
diff --git a/src/__tests__/server/publicRendering.test.ts b/src/__tests__/server/publicRendering.test.ts
index 0a35f8a3b..ff508564b 100644
--- a/src/__tests__/server/publicRendering.test.ts
+++ b/src/__tests__/server/publicRendering.test.ts
@@ -46,7 +46,7 @@ function snapshot(text: string): PublishedPageSnapshot {
         { id: 'desktop', label: 'Desktop', width: 1440, icon: 'monitor' },
       ],
       settings: {
-        metaTitle: 'Public Site',
+        seo: { description: 'Public site description' },
         shortcuts: {},
       },
       styleRules: {},
@@ -119,7 +119,8 @@ describe('public rendering', () => {
 
     expect(html).toContain('<!DOCTYPE html>')
     expect(html).toContain('Visible to public')
-    expect(html).toContain('<title>Public Site</title>')
+    expect(html).toContain('<title>Home</title>')
+    expect(html).toContain('<meta name="description" content="Public site description">')
   })
 
   // Guards the page-wrapper's identity reporting after the shared
diff --git a/src/__tests__/server/publicRouterCache.test.ts b/src/__tests__/server/publicRouterCache.test.ts
index 512a38e9d..c96ae9fce 100644
--- a/src/__tests__/server/publicRouterCache.test.ts
+++ b/src/__tests__/server/publicRouterCache.test.ts
@@ -49,7 +49,7 @@ function makeSnapshot(): PublishedPageSnapshot {
       files: [],
       visualComponents: [],
       breakpoints: [{ id: 'desktop', label: 'Desktop', width: 1440, icon: 'monitor' }],
-      settings: { metaTitle: 'Test Site', shortcuts: {} },
+      settings: { shortcuts: {} },
       styleRules: {},
       createdAt: 1000,
       updatedAt: 2000,
diff --git a/src/__tests__/server/publishRebakeTemplate.test.ts b/src/__tests__/server/publishRebakeTemplate.test.ts
index 11d6e182f..744d10728 100644
--- a/src/__tests__/server/publishRebakeTemplate.test.ts
+++ b/src/__tests__/server/publishRebakeTemplate.test.ts
@@ -58,7 +58,7 @@ function buildFakeDb(layout: Page, about: Page) {
       return {
         rows: [{
           id: 'proj-1', name: 'Test Site',
-          settings_json: { metaTitle: 'Test Site', shortcuts: {} },
+          settings_json: { shortcuts: {} },
           files_json: [], classes_json: {},
           breakpoints_json: [{ id: 'desktop', label: 'Desktop', width: 1440, icon: 'monitor' }],
           runtime_json: { dependencyLock: { version: 1, packages: {}, updatedAt: 0 }, scripts: {} },
diff --git a/src/__tests__/server/publishStaticArtefact.test.ts b/src/__tests__/server/publishStaticArtefact.test.ts
index 0043753ff..df952b79f 100644
--- a/src/__tests__/server/publishStaticArtefact.test.ts
+++ b/src/__tests__/server/publishStaticArtefact.test.ts
@@ -112,7 +112,6 @@ function buildFakeDb(
           id: 'proj-1',
           name: 'Test Site',
           settings_json: {
-            metaTitle: 'Test Site',
             shortcuts: {},
           },
           files_json: [],
diff --git a/src/__tests__/server/seoEndpoints.test.ts b/src/__tests__/server/seoEndpoints.test.ts
new file mode 100644
index 000000000..2bd5e6077
--- /dev/null
+++ b/src/__tests__/server/seoEndpoints.test.ts
@@ -0,0 +1,198 @@
+/**
+ * First-party robots.txt + sitemap.xml endpoint tests.
+ *
+ * Uses a fake DbClient that serves a published snapshot (pages incl. a
+ * template page and a noindex page) plus published rows for the sitemap
+ * query. Verifies content types, AI-crawler toggles, noindex/template
+ * exclusion, publishVersion-keyed caching, and the request-origin fallback.
+ */
+import { beforeEach, describe, expect, it } from 'bun:test'
+import type { DbClient, DbResult } from '../../../server/db'
+import {
+  serveRobotsTxt,
+  serveSitemapXml,
+  resetSeoEndpointCachesForTests,
+} from '../../../server/publish/seoEndpoints'
+import { bumpPublishVersion } from '../../../server/publish/publishState'
+import type { SiteSeoSettings } from '@core/seo'
+
+function makeSiteJson(seo: SiteSeoSettings | undefined) {
+  return {
+    id: 'site_1',
+    name: 'Test Site',
+    pages: [
+      {
+        id: 'page_home',
+        title: 'Home',
+        slug: 'index',
+        rootNodeId: 'root',
+        nodes: { root: { id: 'root', moduleId: 'base.body', props: {}, children: [] } },
+      },
+      {
+        id: 'page_about',
+        title: 'About',
+        slug: 'about',
+        rootNodeId: 'root',
+        nodes: { root: { id: 'root', moduleId: 'base.body', props: {}, children: [] } },
+      },
+      {
+        id: 'page_secret',
+        title: 'Secret',
+        slug: 'secret',
+        rootNodeId: 'root',
+        nodes: { root: { id: 'root', moduleId: 'base.body', props: {}, children: [] } },
+        seo: { noindex: true },
+      },
+      {
+        id: 'page_template',
+        title: 'Post template',
+        slug: 'post-template',
+        rootNodeId: 'root',
+        nodes: { root: { id: 'root', moduleId: 'base.body', props: {}, children: [] } },
+        template: { enabled: true, target: { kind: 'postTypes', tableSlugs: ['posts'] }, priority: 0 },
+      },
+    ],
+    files: [],
+    visualComponents: [],
+    breakpoints: [{ id: 'desktop', label: 'Desktop', width: 1440, icon: 'monitor' }],
+    settings: { shortcuts: {}, ...(seo ? { seo } : {}) },
+    styleRules: {},
+    createdAt: 1000,
+    updatedAt: 2000,
+  }
+}
+
+interface FakeRow {
+  row_id: string
+  row_slug: string
+  table_route_base: string
+  cells_json: Record<string, unknown>
+  published_at: string
+}
+
+function makeFakeDb(seo: SiteSeoSettings | undefined, sitemapRows: FakeRow[]): DbClient {
+  const handle = async <Row extends Record<string, unknown> = Record<string, unknown>>(
+    strings: TemplateStringsArray,
+    ..._values: unknown[]
+  ): Promise<DbResult<Row>> => {
+    const sql = strings.join('?').replace(/\s+/g, ' ').trim().toLowerCase()
+
+    // getLatestSnapshotForVersion — site_snapshots lookup
+    if (sql.includes('site_snapshots')) {
+      return {
+        rows: [{
+          row_id: 'page_home',
+          site_json: makeSiteJson(seo),
+          runtime_assets_json: null,
+          importmap_body: null,
+          importmap_sha256: null,
+        } as unknown as Row],
+        rowCount: 1,
+      }
+    }
+
+    // listPublishedRowsForSitemap
+    if (sql.includes('data_row_versions.published_at')) {
+      return { rows: sitemapRows as unknown as Row[], rowCount: sitemapRows.length }
+    }
+
+    return { rows: [], rowCount: 0 }
+  }
+  return handle as unknown as DbClient
+}
+
+const URL_NO_ORIGIN = new URL('http://localhost:3001/robots.txt')
+
+beforeEach(() => {
+  resetSeoEndpointCachesForTests()
+  // Each test regenerates against a fresh publish version — the snapshot
+  // memo is version-keyed (createVersionedSingleFlight), so bumping makes
+  // every cached body and snapshot of the previous test a miss.
+  bumpPublishVersion()
+})
+
+describe('GET /robots.txt', () => {
+  it('serves text/plain with default allow + sitemap line', async () => {
+    const res = await serveRobotsTxt(makeFakeDb(undefined, []), URL_NO_ORIGIN)
+    expect(res.headers.get('content-type')).toBe('text/plain; charset=utf-8')
+    const body = await res.text()
+    expect(body).toContain('User-agent: *\nAllow: /')
+    expect(body).toContain('Sitemap: http://localhost:3001/sitemap.xml')
+    expect(body).not.toContain('<')
+  })
+
+  it('emits AI-crawler blocks when groups are disabled', async () => {
+    const db = makeFakeDb(
+      { robots: { allowAiTrainingCrawlers: false, allowAiAnswerCrawlers: false } },
+      [],
+    )
+    const body = await (await serveRobotsTxt(db, URL_NO_ORIGIN)).text()
+    expect(body).toContain('User-agent: GPTBot\nDisallow: /')
+    expect(body).toContain('User-agent: PerplexityBot\nDisallow: /')
+  })
+
+  it('disables indexing wholesale when indexingEnabled is false', async () => {
+    const db = makeFakeDb({ robots: { indexingEnabled: false } }, [])
+    const body = await (await serveRobotsTxt(db, URL_NO_ORIGIN)).text()
+    expect(body).toContain('User-agent: *\nDisallow: /')
+  })
+
+  it('caches per publish version', async () => {
+    const db = makeFakeDb(undefined, [])
+    const first = await (await serveRobotsTxt(db, URL_NO_ORIGIN)).text()
+    // Same version: served from cache even if settings change underneath.
+    const dbChanged = makeFakeDb({ robots: { indexingEnabled: false } }, [])
+    const second = await (await serveRobotsTxt(dbChanged, URL_NO_ORIGIN)).text()
+    expect(second).toBe(first)
+    // New publish version: regenerated.
+    bumpPublishVersion()
+    const third = await (await serveRobotsTxt(dbChanged, URL_NO_ORIGIN)).text()
+    expect(third).toContain('Disallow: /')
+  })
+})
+
+describe('GET /sitemap.xml', () => {
+  const rows: FakeRow[] = [
+    {
+      row_id: 'row_1',
+      row_slug: 'hello',
+      table_route_base: '/posts',
+      cells_json: { title: 'Hello' },
+      published_at: '2026-06-01T00:00:00.000Z',
+    },
+    {
+      row_id: 'row_2',
+      row_slug: 'hidden',
+      table_route_base: '/posts',
+      cells_json: { title: 'Hidden', seo: { noindex: true } },
+      published_at: '2026-06-01T00:00:00.000Z',
+    },
+  ]
+
+  it('serves application/xml with pages and rows, excluding noindex + templates', async () => {
+    const res = await serveSitemapXml(makeFakeDb(undefined, rows), URL_NO_ORIGIN)
+    expect(res.headers.get('content-type')).toBe('application/xml; charset=utf-8')
+    const body = await res.text()
+    expect(body).toContain('<loc>http://localhost:3001/</loc>')
+    expect(body).toContain('<loc>http://localhost:3001/about</loc>')
+    expect(body).toContain('<loc>http://localhost:3001/posts/hello</loc>')
+    expect(body).toContain('<lastmod>2026-06-01T00:00:00.000Z</lastmod>')
+    expect(body).not.toContain('/secret')
+    expect(body).not.toContain('post-template')
+    expect(body).not.toContain('/posts/hidden')
+  })
+
+  it('honours excludedTargets', async () => {
+    const db = makeFakeDb({ sitemap: { excludedTargets: ['page:page_about', 'row:row_1'] } }, rows)
+    const body = await (await serveSitemapXml(db, URL_NO_ORIGIN)).text()
+    expect(body).not.toContain('/about')
+    expect(body).not.toContain('/posts/hello')
+    expect(body).toContain('<loc>http://localhost:3001/</loc>')
+  })
+
+  it('returns 404 when sitemap generation is disabled', async () => {
+    const db = makeFakeDb({ sitemap: { enabled: false } }, rows)
+    const res = await serveSitemapXml(db, URL_NO_ORIGIN)
+    expect(res.status).toBe(404)
+  })
+})
diff --git a/src/admin/modals/Settings/sections/GeneralSection.tsx b/src/admin/modals/Settings/sections/GeneralSection.tsx
index 82ad9dd5b..d9c695adc 100644
--- a/src/admin/modals/Settings/sections/GeneralSection.tsx
+++ b/src/admin/modals/Settings/sections/GeneralSection.tsx
@@ -14,7 +14,7 @@
 import { Suspense, lazy, useState } from 'react'
 import { useEditorStore } from '@site/store/store'
 import { useAsyncResource } from '@admin/lib/useAsyncResource'
-import { Input, Textarea } from '@ui/components/Input'
+import { Input } from '@ui/components/Input'
 import { Button } from '@ui/components/Button'
 import { SkeletonBlock } from '@ui/components/Skeleton'
 import { ImagesSolidIcon } from 'pixel-art-icons/icons/images-solid'
@@ -70,39 +70,6 @@ export function GeneralSection() {
         />
       </div>
 
-      {/* ── Meta Title ────────────────────────────────────────────────────── */}
-      <div className={s.genFieldRow}>
-        <label htmlFor="gen-meta-title" className={s.label}>
-          Meta Title
-        </label>
-        <Input
-          id="gen-meta-title"
-          type="text"
-          defaultValue={settings.metaTitle ?? ''}
-          placeholder="My Website"
-          onBlur={(e) =>
-            updateSiteSettings({ metaTitle: e.target.value.trim() || undefined })
-          }
-          onKeyDown={(e) => e.key === 'Enter' && (e.target as HTMLInputElement).blur()}
-        />
-      </div>
-
-      {/* ── Meta Description ──────────────────────────────────────────────── */}
-      <div className={s.genFieldRow}>
-        <label htmlFor="gen-meta-desc" className={s.label}>
-          Meta Description
-        </label>
-        <Textarea
-          id="gen-meta-desc"
-          defaultValue={settings.metaDescription ?? ''}
-          placeholder="A short description of your website."
-          rows={3}
-          onBlur={(e) =>
-            updateSiteSettings({ metaDescription: e.target.value.trim() || undefined })
-          }
-        />
-      </div>
-
       {/* ── Language ──────────────────────────────────────────────────────── */}
       <div className={s.genFieldRow}>
         <label htmlFor="gen-lang" className={s.label}>
diff --git a/src/core/page-tree/siteSettings.ts b/src/core/page-tree/siteSettings.ts
index 7e7ed5aa9..24c10082e 100644
--- a/src/core/page-tree/siteSettings.ts
+++ b/src/core/page-tree/siteSettings.ts
@@ -35,8 +35,6 @@ import { SiteSeoSettingsSchema, parseSiteSeoSettings } from '@core/seo'
 // ---------------------------------------------------------------------------
 
 export const SiteSettingsSchema = Type.Object({
-  metaTitle: Type.Optional(Type.String()),
-  metaDescription: Type.Optional(Type.String()),
   faviconUrl: Type.Optional(Type.String()),
   language: Type.Optional(Type.String()),
   /** Structured framework token settings — absent means framework disabled. */
@@ -92,8 +90,6 @@ export function parseSiteSettings(raw: unknown): SiteSettings {
   const seo = parseSiteSeoSettings(r.seo)
 
   return {
-    ...(typeof r.metaTitle === 'string' ? { metaTitle: r.metaTitle } : {}),
-    ...(typeof r.metaDescription === 'string' ? { metaDescription: r.metaDescription } : {}),
     ...(typeof r.faviconUrl === 'string' ? { faviconUrl: r.faviconUrl } : {}),
     ...(typeof r.language === 'string' ? { language: r.language } : {}),
     framework,
diff --git a/src/core/publisher/index.ts b/src/core/publisher/index.ts
index 7f0e8ba4a..655d85495 100644
--- a/src/core/publisher/index.ts
+++ b/src/core/publisher/index.ts
@@ -6,7 +6,7 @@
 // relative paths and never through this barrel.
 
 export { publishPage } from './render'
-export type { PublishedRuntimePackageImportmap } from './render'
+export type { PublishedRuntimePackageImportmap, PublishedSeo } from './render'
 
 export { renderNode, resolveSpecialRenderer, getSpecialRendererModuleIds } from './renderNode'
 
diff --git a/src/core/publisher/render.ts b/src/core/publisher/render.ts
index 50661a6a3..e90208e02 100644
--- a/src/core/publisher/render.ts
+++ b/src/core/publisher/render.ts
@@ -29,6 +29,7 @@ import type { Page, SiteDocument } from '@core/page-tree'
 import type { IModuleRegistry } from '@core/module-engine'
 import type { TemplateRenderDataContext } from '@core/templates/dynamicBindings'
 import { buildPageFrame, buildSiteFrame, buildRouteFrame } from '@core/templates/contextFrames'
+import { buildDocumentMetaTags, resolvePageSeoFallback, type PublishedSeo } from './seoHead'
 import { classNamesForClassIds } from '@core/page-tree'
 import {
   isRenderableHtmlAttributeName,
@@ -40,7 +41,7 @@ import { collectUserStylesheetCss } from './userStylesheets'
 import { PUBLISHER_RESET_CSS } from './reset'
 import { buildSiteFrameworkCss } from './frameworkCss'
 import type { SiteCssBundle } from './siteCssBundle'
-import { escapeHtml, isSafeUrl } from './utils'
+import { escapeHtml } from './utils'
 import { createBaseCspPlan, cspMetaTag } from './cspPlan'
 import type { PublishedPageRuntimeAssets } from '@core/site-runtime/schemas'
 import { hasPublishedRuntimeScripts, scriptTagsForRuntimeAssets } from '@core/site-runtime'
@@ -60,6 +61,7 @@ import type {
 // RenderAccumulators + ResolvedLoopRenderData; tests import escapeProps).
 export { escapeHtml, isSafeUrl } from './utils'
 export { escapeProps } from './escapeProps'
+export type { PublishedSeo } from './seoHead'
 export { renderNode } from './renderNode'
 export type {
   RenderConfig,
@@ -159,6 +161,15 @@ export interface PublishPageOptions {
    * on first fetch, which is safe — the next page load sees the real version).
    */
   publishVersion?: number
+  /**
+   * Pre-resolved SEO metadata + JSON-LD entities for this route. The server
+   * passes this for both page and row renders (it knows the public origin,
+   * the row's SEO cells, and the entry template). When omitted, publishPage
+   * resolves page-level SEO itself from `page.seo` + `site.settings.seo` —
+   * previews and exports share the exact same resolver, minus the
+   * origin-dependent absolute URLs.
+   */
+  seo?: PublishedSeo
   /**
    * Editor-only: annotate each node's outermost emitted element with
    * `uid="<id>"`. Default off — real publishes emit clean, id-less
@@ -307,40 +318,6 @@ function bodyHtmlAttributes(value: unknown): string {
     .join('')
 }
 
-/**
- * `<head>` metadata tags derived from site settings + page.
- *
- * - `title` falls back through metaTitle → page.title → site.name.
- * - URL-typed settings (faviconUrl) are validated by
- *   isSafeUrl() (blocks `javascript:` / `vbscript:` schemes) and then
- *   escapeHtml()'d for safe attribute interpolation.
- * - `lang` honours WCAG 2.1 AA SC 3.1.1 and escapes the BCP-47 tag
- *   because settings.language is user-controlled.
- */
-interface DocumentMetaTags {
-  pageTitle: string
-  metaDesc: string
-  favicon: string
-  langAttr: string
-}
-
-function buildDocumentMetaTags(site: SiteDocument, page: Page): DocumentMetaTags {
-  const { settings } = site
-  const metaDesc = settings.metaDescription
-    ? `\n  <meta name="description" content="${escapeHtml(settings.metaDescription)}">`
-    : ''
-  const favicon =
-    settings.faviconUrl && isSafeUrl(settings.faviconUrl)
-      ? `\n  <link rel="icon" href="${escapeHtml(settings.faviconUrl)}">`
-      : ''
-  return {
-    pageTitle: escapeHtml(settings.metaTitle ?? page.title ?? site.name),
-    metaDesc,
-    favicon,
-    langAttr: escapeHtml(settings.language ?? 'en'),
-  }
-}
-
 /**
  * Runtime / importmap / loop-runtime `<script>` tags + the flags the CSP
  * builder needs. Centralising every "do we need a script tag?" branch in
@@ -439,8 +416,7 @@ function lineOrEmpty(content: string): string {
 interface AssembledDocumentParts {
   langAttr: string
   csp: string
-  pageTitle: string
-  metaDesc: string
+  seoHeadHtml: string
   favicon: string
   styleHeadHtml: string
   importmapTag: string
@@ -460,7 +436,7 @@ function assembleHtmlDocument(parts: AssembledDocumentParts): string {
     `<head>\n` +
     `  <meta charset="UTF-8">\n` +
     `  <meta name="viewport" content="width=device-width, initial-scale=1.0">${parts.csp}\n` +
-    `  <title>${parts.pageTitle}</title>${parts.metaDesc}${parts.favicon}\n` +
+    `${parts.seoHeadHtml}${parts.favicon}\n` +
     parts.styleHeadHtml +
     lineOrEmpty(parts.importmapTag) +
     lineOrEmpty(parts.headRuntimeScripts) +
@@ -504,12 +480,13 @@ export function publishPage(
   // Read-only inputs of this render pass. A renderer that needs a different
   // page (VC ref) or template frame (loop iteration) derives a child config —
   // it never mutates this one.
+  const templateContext = composeTemplateContext(page, site, options.templateContext)
   const config: RenderConfig = {
     page,
     site,
     registry,
     breakpointId: options.breakpointId,
-    templateContext: composeTemplateContext(page, site, options.templateContext),
+    templateContext,
     loopData: options.loopData,
     mediaAssets: options.mediaAssets,
     dynamicNodeIds: dynamicNodeIds.size > 0 ? dynamicNodeIds : undefined,
@@ -556,15 +533,15 @@ export function publishPage(
     acc.cssMap,
   )
 
-  const meta = buildDocumentMetaTags(site, page)
+  const seo = options.seo ?? resolvePageSeoFallback(page, site, templateContext)
+  const meta = buildDocumentMetaTags(site, seo)
   const runtime = buildRuntimeAssetsBlock(options, acc)
   const csp = buildContentSecurityPolicy(runtime.anyScriptTag, runtime.importmap)
 
   const html = assembleHtmlDocument({
     langAttr: meta.langAttr,
     csp,
-    pageTitle: meta.pageTitle,
-    metaDesc: meta.metaDesc,
+    seoHeadHtml: meta.seoHeadHtml,
     favicon: meta.favicon,
     styleHeadHtml,
     importmapTag: runtime.importmapTag,
diff --git a/src/core/publisher/seoHead.ts b/src/core/publisher/seoHead.ts
new file mode 100644
index 000000000..098f6206a
--- /dev/null
+++ b/src/core/publisher/seoHead.ts
@@ -0,0 +1,159 @@
+/**
+ * SEO `<head>` assembly for published pages.
+ *
+ * Owns the `<title>` + meta/link/JSON-LD emission and the page-level SEO
+ * fallback resolution used when the caller didn't pre-resolve metadata.
+ * The server passes a fully-resolved `PublishedSeo` (it knows the public
+ * origin, row SEO cells, and entry templates); previews/exports fall back
+ * to `resolvePageSeoFallback`, which runs the SAME `@core/seo` resolver —
+ * one fallback engine everywhere, minus origin-dependent absolute URLs.
+ */
+
+import type { Page, SiteDocument } from '@core/page-tree'
+import type { TemplateRenderDataContext } from '@core/templates/dynamicBindings'
+import { buildPageFrame } from '@core/templates/contextFrames'
+import { interpolateTokens } from '@core/templates/tokenInterpolation'
+import {
+  resolveSeoMetadata,
+  buildJsonLdEntities,
+  serializeJsonLd,
+  type JsonLdEntity,
+  type ResolvedSeoMetadata,
+} from '@core/seo'
+import { escapeHtml, isSafeUrl } from './utils'
+
+/**
+ * Resolved SEO payload for one published route: the final metadata values
+ * the head tags emit, plus the schema.org JSON-LD entities. Built by
+ * `resolveSeoMetadata` + `buildJsonLdEntities` from `@core/seo` — either by
+ * the server caller (full context) or by `publishPage`'s internal fallback.
+ */
+export interface PublishedSeo {
+  resolved: ResolvedSeoMetadata
+  jsonLd: JsonLdEntity[]
+}
+
+/**
+ * `<head>` metadata derived from the resolved SEO payload + site settings.
+ *
+ * - Every text value is escapeHtml()'d; URL-typed values (canonical, images,
+ *   favicon) are additionally validated by isSafeUrl() (blocks
+ *   `javascript:` / `vbscript:` schemes).
+ * - `noindex` emits `noindex` only — a noindexed page's links still pass
+ *   crawl equity, so `nofollow` is never bundled silently.
+ * - JSON-LD entities are serialized with `serializeJsonLd`, which escapes
+ *   `</script` and `<!--` so user strings cannot break out of the element.
+ * - `lang` honours WCAG 2.1 AA SC 3.1.1 and escapes the BCP-47 tag
+ *   because settings.language is user-controlled.
+ */
+export interface DocumentMetaTags {
+  /** `<title>` + every SEO meta/link/JSON-LD line, two-space indented. */
+  seoHeadHtml: string
+  favicon: string
+  langAttr: string
+}
+
+/**
+ * Resolve the page-level SEO fallback when the caller didn't pass
+ * `options.seo`. Covers previews, exports, and tests — same resolver as the
+ * server path, with title patterns interpolated against the composed
+ * template context. No origin is available here, so absolute URLs
+ * (canonical, og:url) and origin-dependent JSON-LD are omitted.
+ */
+export function resolvePageSeoFallback(
+  page: Page,
+  site: SiteDocument,
+  templateContext: TemplateRenderDataContext,
+): PublishedSeo {
+  const pageFrame = buildPageFrame(page)
+  const resolved = resolveSeoMetadata({
+    target: page.seo,
+    siteSeo: site.settings.seo,
+    siteName: site.name,
+    baseTitle: page.title,
+    routeKind: 'page',
+    routePath: pageFrame.permalink,
+    language: site.settings.language,
+    interpolate: (pattern) => interpolateTokens(pattern, templateContext),
+  })
+  const jsonLd = buildJsonLdEntities(resolved, {
+    kind: 'page',
+    routePath: pageFrame.permalink,
+    siteName: site.name,
+    organization: site.settings.seo?.organization,
+  })
+  return { resolved, jsonLd }
+}
+
+export function buildDocumentMetaTags(site: SiteDocument, seo: PublishedSeo): DocumentMetaTags {
+  const { settings } = site
+  const { resolved, jsonLd } = seo
+
+  const lines: string[] = []
+  lines.push(`<title>${escapeHtml(resolved.title)}</title>`)
+  if (resolved.description) {
+    lines.push(`<meta name="description" content="${escapeHtml(resolved.description)}">`)
+  }
+  if (resolved.noindex) {
+    lines.push('<meta name="robots" content="noindex">')
+  }
+  if (resolved.canonicalUrl && isSafeUrl(resolved.canonicalUrl)) {
+    lines.push(`<link rel="canonical" href="${escapeHtml(resolved.canonicalUrl)}">`)
+  }
+
+  lines.push(`<meta property="og:title" content="${escapeHtml(resolved.ogTitle)}">`)
+  if (resolved.ogDescription) {
+    lines.push(`<meta property="og:description" content="${escapeHtml(resolved.ogDescription)}">`)
+  }
+  if (resolved.ogImage && isSafeUrl(resolved.ogImage)) {
+    lines.push(`<meta property="og:image" content="${escapeHtml(resolved.ogImage)}">`)
+    if (resolved.ogImageAlt) {
+      lines.push(`<meta property="og:image:alt" content="${escapeHtml(resolved.ogImageAlt)}">`)
+    }
+  }
+  lines.push(`<meta property="og:type" content="${escapeHtml(resolved.ogType)}">`)
+  if (resolved.ogUrl && isSafeUrl(resolved.ogUrl)) {
+    lines.push(`<meta property="og:url" content="${escapeHtml(resolved.ogUrl)}">`)
+  }
+  lines.push(`<meta property="og:site_name" content="${escapeHtml(site.name)}">`)
+  if (resolved.ogLocale) {
+    lines.push(`<meta property="og:locale" content="${escapeHtml(resolved.ogLocale)}">`)
+  }
+  if (resolved.ogType === 'article') {
+    if (resolved.articlePublishedTime) {
+      lines.push(`<meta property="article:published_time" content="${escapeHtml(resolved.articlePublishedTime)}">`)
+    }
+    if (resolved.articleModifiedTime) {
+      lines.push(`<meta property="article:modified_time" content="${escapeHtml(resolved.articleModifiedTime)}">`)
+    }
+  }
+
+  lines.push(`<meta name="twitter:card" content="${escapeHtml(resolved.xCard)}">`)
+  if (resolved.xSiteHandle) {
+    lines.push(`<meta name="twitter:site" content="${escapeHtml(resolved.xSiteHandle)}">`)
+  }
+  lines.push(`<meta name="twitter:title" content="${escapeHtml(resolved.xTitle)}">`)
+  if (resolved.xDescription) {
+    lines.push(`<meta name="twitter:description" content="${escapeHtml(resolved.xDescription)}">`)
+  }
+  if (resolved.xImage && isSafeUrl(resolved.xImage)) {
+    lines.push(`<meta name="twitter:image" content="${escapeHtml(resolved.xImage)}">`)
+    if (resolved.xImageAlt) {
+      lines.push(`<meta name="twitter:image:alt" content="${escapeHtml(resolved.xImageAlt)}">`)
+    }
+  }
+
+  for (const entity of jsonLd) {
+    lines.push(`<script type="application/ld+json">${serializeJsonLd(entity)}</script>`)
+  }
+
+  const favicon =
+    settings.faviconUrl && isSafeUrl(settings.faviconUrl)
+      ? `\n  <link rel="icon" href="${escapeHtml(settings.faviconUrl)}">`
+      : ''
+  return {
+    seoHeadHtml: lines.map((line) => `  ${line}`).join('\n'),
+    favicon,
+    langAttr: escapeHtml(settings.language ?? 'en'),
+  }
+}

From 7eb1590a803dd6a4f5b7c0bdde26812ecdc1a914 Mon Sep 17 00:00:00 2001
From: DavidBabinec <hello@davidbabinec.com>
Date: Fri, 12 Jun 2026 13:17:32 +0200
Subject: [PATCH 04/26] feat(seo): admin SEO workspace, Tools navigation, seo
 API and capabilities

New /admin/tools/seo workspace (Meta / Robots.txt / Sitemap tabs): target
index with search, filters, issue chips, health dots, and keyboard nav;
sticky preview editor with Search/OG/X/Schema platform views, inherited
values as placeholders, pixel length meters, media-library image pickers,
and a dirty-switch guard dialog. Site defaults editor covers title
patterns, social defaults, X handle, and Organization JSON-LD fields.
Robots tab pairs indexing + AI-crawler toggles with a byte-identical
generated preview; Sitemap tab manages enable/exclusions with counts.
Plugin admin pages move under a new Tools nav dropdown alongside SEO.
Server: /admin/api/cms/seo route group (targets index, target writes with
ownership gates, site settings) and seo.read/seo.manage capabilities.

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
---
 server/auth/capabilities.ts                   |   2 +
 server/db/migrations-pg.ts                    |   4 +-
 server/db/migrations-sqlite.ts                |   4 +-
 server/handlers/cms/index.ts                  |   2 +
 server/handlers/cms/seo.ts                    | 231 ++++++++++++
 .../admin/capabilityAwareAdmin.test.tsx       |   3 +-
 src/__tests__/admin/seoWorkspace.test.tsx     | 297 ++++++++++++++++
 src/__tests__/server/seoHandler.test.ts       | 220 ++++++++++++
 src/admin/AuthenticatedAdmin.tsx              |   8 +
 src/admin/access.ts                           |   6 +-
 src/admin/pages/seo/SeoPage.module.css        |  16 +
 src/admin/pages/seo/SeoPage.tsx               |  72 ++++
 .../components/AiSuggestionBubbles.module.css |  37 ++
 .../seo/components/AiSuggestionBubbles.tsx    | 128 +++++++
 .../seo/components/MetaLengthMeter.module.css |  56 +++
 .../pages/seo/components/MetaLengthMeter.tsx  |  51 +++
 .../components/OpenGraphPreview.module.css    |  54 +++
 .../pages/seo/components/OpenGraphPreview.tsx |  23 ++
 .../seo/components/SchemaPreview.module.css   |  14 +
 .../pages/seo/components/SchemaPreview.tsx    |  48 +++
 .../SearchSnippetPreview.module.css           |  42 +++
 .../seo/components/SearchSnippetPreview.tsx   |  24 ++
 .../seo/components/SeoImageField.module.css   |  24 ++
 .../pages/seo/components/SeoImageField.tsx    |  81 +++++
 .../components/SeoPreviewEditor.module.css    | 126 +++++++
 .../pages/seo/components/SeoPreviewEditor.tsx | 329 ++++++++++++++++++
 .../seo/components/SeoTargetIndex.module.css  | 126 +++++++
 .../pages/seo/components/SeoTargetIndex.tsx   | 232 ++++++++++++
 .../seo/components/SiteDefaultsEditor.tsx     | 246 +++++++++++++
 .../seo/components/XCardPreview.module.css    |  70 ++++
 .../pages/seo/components/XCardPreview.tsx     |  29 ++
 src/admin/pages/seo/hooks/useSeoDraft.ts      | 141 ++++++++
 src/admin/pages/seo/hooks/useSeoWorkspace.ts  |  91 +++++
 src/admin/pages/seo/lib/resolveTargetSeo.ts   |  82 +++++
 src/admin/pages/seo/lib/seoApi.ts             | 110 ++++++
 src/admin/pages/seo/tabs/MetaTab.module.css   |  26 ++
 src/admin/pages/seo/tabs/MetaTab.tsx          | 110 ++++++
 src/admin/pages/seo/tabs/RobotsTab.tsx        | 144 ++++++++
 .../pages/seo/tabs/SettingsTabs.module.css    | 126 +++++++
 src/admin/pages/seo/tabs/SitemapTab.tsx       | 153 ++++++++
 src/admin/pages/users/utils/capabilities.ts   |  12 +
 src/admin/router.tsx                          |   1 +
 .../AdminSectionNavigation.tsx                | 119 ++++++-
 src/admin/workspace.ts                        |   5 +
 src/core/capabilities.ts                      |   3 +
 .../dist/icons/tool-case-solid.d.ts           |   3 +
 .../dist/icons/tool-case-solid.js             |   4 +
 .../pixel-art-icons/icons/tool-case-solid.tsx |  18 +
 48 files changed, 3736 insertions(+), 17 deletions(-)
 create mode 100644 server/handlers/cms/seo.ts
 create mode 100644 src/__tests__/admin/seoWorkspace.test.tsx
 create mode 100644 src/__tests__/server/seoHandler.test.ts
 create mode 100644 src/admin/pages/seo/SeoPage.module.css
 create mode 100644 src/admin/pages/seo/SeoPage.tsx
 create mode 100644 src/admin/pages/seo/components/AiSuggestionBubbles.module.css
 create mode 100644 src/admin/pages/seo/components/AiSuggestionBubbles.tsx
 create mode 100644 src/admin/pages/seo/components/MetaLengthMeter.module.css
 create mode 100644 src/admin/pages/seo/components/MetaLengthMeter.tsx
 create mode 100644 src/admin/pages/seo/components/OpenGraphPreview.module.css
 create mode 100644 src/admin/pages/seo/components/OpenGraphPreview.tsx
 create mode 100644 src/admin/pages/seo/components/SchemaPreview.module.css
 create mode 100644 src/admin/pages/seo/components/SchemaPreview.tsx
 create mode 100644 src/admin/pages/seo/components/SearchSnippetPreview.module.css
 create mode 100644 src/admin/pages/seo/components/SearchSnippetPreview.tsx
 create mode 100644 src/admin/pages/seo/components/SeoImageField.module.css
 create mode 100644 src/admin/pages/seo/components/SeoImageField.tsx
 create mode 100644 src/admin/pages/seo/components/SeoPreviewEditor.module.css
 create mode 100644 src/admin/pages/seo/components/SeoPreviewEditor.tsx
 create mode 100644 src/admin/pages/seo/components/SeoTargetIndex.module.css
 create mode 100644 src/admin/pages/seo/components/SeoTargetIndex.tsx
 create mode 100644 src/admin/pages/seo/components/SiteDefaultsEditor.tsx
 create mode 100644 src/admin/pages/seo/components/XCardPreview.module.css
 create mode 100644 src/admin/pages/seo/components/XCardPreview.tsx
 create mode 100644 src/admin/pages/seo/hooks/useSeoDraft.ts
 create mode 100644 src/admin/pages/seo/hooks/useSeoWorkspace.ts
 create mode 100644 src/admin/pages/seo/lib/resolveTargetSeo.ts
 create mode 100644 src/admin/pages/seo/lib/seoApi.ts
 create mode 100644 src/admin/pages/seo/tabs/MetaTab.module.css
 create mode 100644 src/admin/pages/seo/tabs/MetaTab.tsx
 create mode 100644 src/admin/pages/seo/tabs/RobotsTab.tsx
 create mode 100644 src/admin/pages/seo/tabs/SettingsTabs.module.css
 create mode 100644 src/admin/pages/seo/tabs/SitemapTab.tsx
 create mode 100644 vendor/pixel-art-icons/dist/icons/tool-case-solid.d.ts
 create mode 100644 vendor/pixel-art-icons/dist/icons/tool-case-solid.js
 create mode 100644 vendor/pixel-art-icons/icons/tool-case-solid.tsx

diff --git a/server/auth/capabilities.ts b/server/auth/capabilities.ts
index 37d228338..c3260920a 100644
--- a/server/auth/capabilities.ts
+++ b/server/auth/capabilities.ts
@@ -76,6 +76,8 @@ const adminCapabilities: CoreCapability[] = [
   'ai.tools.write',
   'ai.providers.manage',
   'ai.audit.read',
+  'seo.read',
+  'seo.manage',
 ]
 
 const clientCapabilities: CoreCapability[] = [
diff --git a/server/db/migrations-pg.ts b/server/db/migrations-pg.ts
index 5d314b6d2..f0c8dd164 100644
--- a/server/db/migrations-pg.ts
+++ b/server/db/migrations-pg.ts
@@ -61,8 +61,8 @@ export const pgMigrations: Migration[] = [
       -- UI are preserved.
       insert into roles (id, slug, name, description, is_system, capabilities_json)
       values
-        ('owner', 'owner', 'Owner', 'Permanent installation owner with full system access.', true, '["dashboard.read","site.read","site.structure.edit","site.content.edit","site.style.edit","pages.edit","pages.publish","content.create","content.edit.own","content.edit.any","content.publish.own","content.publish.any","content.manage","media.read","media.write","media.replace","media.delete","runtime.dependencies","storage.elect","storage.migrate","plugins.read","plugins.configure","plugins.install","plugins.lifecycle","users.manage","roles.manage","audit.read","data.tables.read","data.tables.manage","data.rows.move","data.export","data.import","ai.chat","ai.tools.write","ai.providers.manage","ai.audit.read"]'::jsonb),
-        ('admin', 'admin', 'Admin', 'Full admin access (cannot manage roles).', true, '["dashboard.read","site.read","site.structure.edit","site.content.edit","site.style.edit","pages.edit","pages.publish","content.create","content.edit.own","content.edit.any","content.publish.own","content.publish.any","content.manage","media.read","media.write","media.replace","media.delete","runtime.dependencies","storage.elect","storage.migrate","plugins.read","plugins.configure","plugins.install","plugins.lifecycle","users.manage","audit.read","data.tables.read","data.tables.manage","data.rows.move","data.export","data.import","ai.chat","ai.tools.write","ai.providers.manage","ai.audit.read"]'::jsonb),
+        ('owner', 'owner', 'Owner', 'Permanent installation owner with full system access.', true, '["dashboard.read","site.read","site.structure.edit","site.content.edit","site.style.edit","pages.edit","pages.publish","content.create","content.edit.own","content.edit.any","content.publish.own","content.publish.any","content.manage","media.read","media.write","media.replace","media.delete","runtime.dependencies","storage.elect","storage.migrate","plugins.read","plugins.configure","plugins.install","plugins.lifecycle","users.manage","roles.manage","audit.read","data.tables.read","data.tables.manage","data.rows.move","data.export","data.import","ai.chat","ai.tools.write","ai.providers.manage","ai.audit.read","seo.read","seo.manage"]'::jsonb),
+        ('admin', 'admin', 'Admin', 'Full admin access (cannot manage roles).', true, '["dashboard.read","site.read","site.structure.edit","site.content.edit","site.style.edit","pages.edit","pages.publish","content.create","content.edit.own","content.edit.any","content.publish.own","content.publish.any","content.manage","media.read","media.write","media.replace","media.delete","runtime.dependencies","storage.elect","storage.migrate","plugins.read","plugins.configure","plugins.install","plugins.lifecycle","users.manage","audit.read","data.tables.read","data.tables.manage","data.rows.move","data.export","data.import","ai.chat","ai.tools.write","ai.providers.manage","ai.audit.read","seo.read","seo.manage"]'::jsonb),
         ('client', 'client', 'Client', 'Can edit page copy (text, images, links) but not structure or styles.', true, '["dashboard.read","site.read","site.content.edit","media.read","data.tables.read"]'::jsonb),
         ('member', 'member', 'Member', 'Public-facing member account — no admin access by default.', true, '[]'::jsonb)
       on conflict (id) do update
diff --git a/server/db/migrations-sqlite.ts b/server/db/migrations-sqlite.ts
index c44ac5ee8..299bc58ce 100644
--- a/server/db/migrations-sqlite.ts
+++ b/server/db/migrations-sqlite.ts
@@ -56,8 +56,8 @@ export const sqliteMigrations: Migration[] = [
       -- UI are preserved.
       insert into roles (id, slug, name, description, is_system, capabilities_json)
       values
-        ('owner', 'owner', 'Owner', 'Permanent installation owner with full system access.', 1, '["dashboard.read","site.read","site.structure.edit","site.content.edit","site.style.edit","pages.edit","pages.publish","content.create","content.edit.own","content.edit.any","content.publish.own","content.publish.any","content.manage","media.read","media.write","media.replace","media.delete","runtime.dependencies","storage.elect","storage.migrate","plugins.read","plugins.configure","plugins.install","plugins.lifecycle","users.manage","roles.manage","audit.read","data.tables.read","data.tables.manage","data.rows.move","data.export","data.import","ai.chat","ai.tools.write","ai.providers.manage","ai.audit.read"]'),
-        ('admin', 'admin', 'Admin', 'Full admin access (cannot manage roles).', 1, '["dashboard.read","site.read","site.structure.edit","site.content.edit","site.style.edit","pages.edit","pages.publish","content.create","content.edit.own","content.edit.any","content.publish.own","content.publish.any","content.manage","media.read","media.write","media.replace","media.delete","runtime.dependencies","storage.elect","storage.migrate","plugins.read","plugins.configure","plugins.install","plugins.lifecycle","users.manage","audit.read","data.tables.read","data.tables.manage","data.rows.move","data.export","data.import","ai.chat","ai.tools.write","ai.providers.manage","ai.audit.read"]'),
+        ('owner', 'owner', 'Owner', 'Permanent installation owner with full system access.', 1, '["dashboard.read","site.read","site.structure.edit","site.content.edit","site.style.edit","pages.edit","pages.publish","content.create","content.edit.own","content.edit.any","content.publish.own","content.publish.any","content.manage","media.read","media.write","media.replace","media.delete","runtime.dependencies","storage.elect","storage.migrate","plugins.read","plugins.configure","plugins.install","plugins.lifecycle","users.manage","roles.manage","audit.read","data.tables.read","data.tables.manage","data.rows.move","data.export","data.import","ai.chat","ai.tools.write","ai.providers.manage","ai.audit.read","seo.read","seo.manage"]'),
+        ('admin', 'admin', 'Admin', 'Full admin access (cannot manage roles).', 1, '["dashboard.read","site.read","site.structure.edit","site.content.edit","site.style.edit","pages.edit","pages.publish","content.create","content.edit.own","content.edit.any","content.publish.own","content.publish.any","content.manage","media.read","media.write","media.replace","media.delete","runtime.dependencies","storage.elect","storage.migrate","plugins.read","plugins.configure","plugins.install","plugins.lifecycle","users.manage","audit.read","data.tables.read","data.tables.manage","data.rows.move","data.export","data.import","ai.chat","ai.tools.write","ai.providers.manage","ai.audit.read","seo.read","seo.manage"]'),
         ('client', 'client', 'Client', 'Can edit page copy (text, images, links) but not structure or styles.', 1, '["dashboard.read","site.read","site.content.edit","media.read","data.tables.read"]'),
         ('member', 'member', 'Member', 'Public-facing member account — no admin access by default.', 1, '[]')
       on conflict (id) do update
diff --git a/server/handlers/cms/index.ts b/server/handlers/cms/index.ts
index 41169a8f3..37d8621d9 100644
--- a/server/handlers/cms/index.ts
+++ b/server/handlers/cms/index.ts
@@ -47,6 +47,7 @@ import { handleMediaFolderRoutes } from './mediaFolders'
 import { handleMediaStorageAdminRoutes } from './mediaStorageAdmin'
 import { handlePluginsRoutes } from './plugins'
 import { handleDataRoutes } from './data'
+import { handleSeoRoutes } from './seo'
 import { handleDashboardRoutes } from './dashboard'
 import { handleFontsRoutes } from './fonts'
 import { handlePublishRoutes } from './publish'
@@ -100,6 +101,7 @@ export async function handleCmsRequest(
     ?? (await handleMediaRoutes(req, db))
     ?? (await handlePluginsRoutes(req, db, options))
     ?? (await handleDataRoutes(req, db, options))
+    ?? (await handleSeoRoutes(req, db, options))
     // Dashboard stats — read-only aggregate counts used by the admin
     // dashboard widgets. Lives after data routes so future routes
     // under `/data/...` can never accidentally shadow it.
diff --git a/server/handlers/cms/seo.ts b/server/handlers/cms/seo.ts
new file mode 100644
index 000000000..347ecf01a
--- /dev/null
+++ b/server/handlers/cms/seo.ts
@@ -0,0 +1,231 @@
+/**
+ * SEO workspace API — `/admin/api/cms/seo/*`.
+ *
+ *   GET  /seo/targets        — the complete target index (pages, templates,
+ *                              post rows) plus site SEO defaults and the
+ *                              configured public origin. Draft cells: the
+ *                              workspace edits drafts, publish takes them live.
+ *   PUT  /seo/targets/:kind/:id — write one target's structured `seo` cell.
+ *   PUT  /seo/site           — write `site.settings.seo` (defaults + robots
+ *                              + sitemap settings live in one object; the
+ *                              Robots/Sitemap tabs save through here too).
+ *
+ * Capabilities: `seo.read` to read, `seo.manage` to write. Target writes
+ * additionally require the persona that owns the underlying target —
+ * `pages.edit` for page/template rows, a content-edit capability for post
+ * rows — so the SEO workspace can't smuggle edits past the content gates.
+ */
+import { Type } from '@core/utils/typeboxHelpers'
+import type { DataRow, DataTable } from '@core/data/schemas'
+import { readSeoCell, readTitleCell } from '@core/data/cells'
+import { SeoMetadataSchema, SiteSeoSettingsSchema, parseSiteSeoSettings } from '@core/seo'
+import { normalizeRouteBase } from '@core/templates'
+import { parsePageTemplate } from '@core/page-tree'
+import type { DbClient } from '../../db/client'
+import { badRequest, jsonResponse, readValidatedBody } from '../../http'
+import { requireCapability, userHasAnyCapability, userHasCapability } from '../../auth/authz'
+import { canonicalPublicOrigin } from '../../auth/security'
+import { getDraftSite, saveDraftSite } from '../../repositories/site'
+import { listDataTables } from '../../repositories/data/tables'
+import { getDataRow, listDataRows, saveDataRowDraft } from '../../repositories/data'
+import { CMS_API_PREFIX } from './shared'
+import type { CmsHandlerOptions } from './shared'
+import { runRouteTable, type Route, type RouteParams } from './routeTable'
+
+// ---------------------------------------------------------------------------
+// Body schemas
+// ---------------------------------------------------------------------------
+
+const SeoTargetPutBodySchema = Type.Object({
+  seo: SeoMetadataSchema,
+})
+
+const SiteSeoPutBodySchema = Type.Object({
+  seo: SiteSeoSettingsSchema,
+})
+
+// ---------------------------------------------------------------------------
+// Target index
+// ---------------------------------------------------------------------------
+
+export type SeoTargetKind = 'page' | 'template' | 'post'
+
+interface SeoTargetPayload {
+  kind: SeoTargetKind
+  id: string
+  title: string
+  /** Public route path; null for templates (not directly routable). */
+  route: string | null
+  tableSlug?: string
+  tableLabel?: string
+  /**
+   * Templates only: the postType table slugs this entry template applies
+   * to. Lets the admin preview resolve a post's template title pattern
+   * exactly like the publisher does. Empty for `everywhere` templates.
+   */
+  templateTableSlugs?: string[]
+  seo: ReturnType<typeof readSeoCell> | null
+  status: string
+  updatedAt: string
+  publishedAt: string | null
+}
+
+function pageRowToTarget(row: DataRow): SeoTargetPayload {
+  const template = row.cells.templateEnabled === true
+    ? parsePageTemplate({
+        enabled: true,
+        target: row.cells.templateTarget,
+        priority: row.cells.templatePriority,
+      })
+    : null
+  // Mirrors isTemplatePage(page): parsePageTemplate only returns a config
+  // for enabled templates, so a non-null config means "template page".
+  const isTemplate = template !== null
+  const slug = row.slug.replace(/^\/+/, '')
+  return {
+    kind: isTemplate ? 'template' : 'page',
+    id: row.id,
+    title: readTitleCell(row.cells) || row.slug,
+    route: isTemplate ? null : slug === 'index' || slug === '' ? '/' : `/${slug}`,
+    ...(isTemplate
+      ? { templateTableSlugs: template.target.kind === 'postTypes' ? template.target.tableSlugs : [] }
+      : {}),
+    seo: readSeoCell(row.cells) ?? null,
+    status: row.status,
+    updatedAt: row.updatedAt,
+    publishedAt: row.publishedAt,
+  }
+}
+
+function postRowToTarget(row: DataRow, table: DataTable): SeoTargetPayload {
+  const routeBase = normalizeRouteBase(table.routeBase ?? '')
+  return {
+    kind: 'post',
+    id: row.id,
+    title: readTitleCell(row.cells) || row.slug,
+    route: routeBase ? `${routeBase}/${row.slug}` : null,
+    tableSlug: table.slug,
+    tableLabel: table.pluralLabel,
+    seo: readSeoCell(row.cells) ?? null,
+    status: row.status,
+    updatedAt: row.updatedAt,
+    publishedAt: row.publishedAt,
+  }
+}
+
+async function handleGetTargets(req: Request, db: DbClient): Promise<Response> {
+  const user = await requireCapability(req, db, 'seo.read')
+  if (user instanceof Response) return user
+
+  const [site, tables, pageRows] = await Promise.all([
+    getDraftSite(db),
+    listDataTables(db),
+    listDataRows(db, 'pages'),
+  ])
+
+  const postTables = tables.filter((table) => table.kind === 'postType')
+  const postTargets: SeoTargetPayload[] = []
+  for (const table of postTables) {
+    const rows = await listDataRows(db, table.id)
+    for (const row of rows) postTargets.push(postRowToTarget(row, table))
+  }
+
+  return jsonResponse({
+    siteName: site?.name ?? '',
+    language: site?.settings.language ?? null,
+    publicOrigin: canonicalPublicOrigin(),
+    siteSeo: site?.settings.seo ?? null,
+    targets: [...pageRows.map(pageRowToTarget), ...postTargets],
+  })
+}
+
+// ---------------------------------------------------------------------------
+// Target write
+// ---------------------------------------------------------------------------
+
+async function handlePutTarget(
+  req: Request,
+  db: DbClient,
+  params: RouteParams,
+): Promise<Response> {
+  const user = await requireCapability(req, db, 'seo.manage')
+  if (user instanceof Response) return user
+
+  const body = await readValidatedBody(req, SeoTargetPutBodySchema)
+  if (!body) return badRequest('Invalid SEO metadata payload')
+
+  const row = await getDataRow(db, params.id)
+  if (!row) return jsonResponse({ error: 'Target not found' }, { status: 404 })
+
+  const isPageRow = row.tableId === 'pages'
+  const kindMatchesRow = isPageRow
+    ? params.kind === 'page' || params.kind === 'template'
+    : params.kind === 'post'
+  if (!kindMatchesRow) return badRequest('Target kind does not match the row')
+
+  // Target-level ownership: the SEO workspace must not smuggle writes past
+  // the personas that own the underlying rows.
+  if (isPageRow) {
+    if (!userHasCapability(user, 'pages.edit')) {
+      return jsonResponse({ error: 'Forbidden' }, { status: 403 })
+    }
+  } else if (!userHasAnyCapability(user, ['content.edit.any', 'content.manage'])) {
+    return jsonResponse({ error: 'Forbidden' }, { status: 403 })
+  }
+
+  const updated = await saveDataRowDraft(
+    db,
+    row.id,
+    { cells: { ...row.cells, seo: body.seo }, slug: row.slug },
+    user.id,
+  )
+  if (!updated) return jsonResponse({ error: 'Target not found' }, { status: 404 })
+
+  return jsonResponse({
+    target: row.tableId === 'pages'
+      ? pageRowToTarget(updated)
+      : postRowToTarget(updated, (await listDataTables(db)).find((t) => t.id === row.tableId)!),
+  })
+}
+
+// ---------------------------------------------------------------------------
+// Site SEO settings (defaults + robots + sitemap)
+// ---------------------------------------------------------------------------
+
+async function handlePutSiteSeo(req: Request, db: DbClient): Promise<Response> {
+  const user = await requireCapability(req, db, 'seo.manage')
+  if (user instanceof Response) return user
+
+  const body = await readValidatedBody(req, SiteSeoPutBodySchema)
+  if (!body) return badRequest('Invalid site SEO payload')
+
+  const site = await getDraftSite(db)
+  if (!site) return jsonResponse({ error: 'Site not found' }, { status: 404 })
+
+  const seo = parseSiteSeoSettings(body.seo)
+  await saveDraftSite(db, { ...site, settings: { ...site.settings, seo } }, user.id)
+
+  return jsonResponse({ seo: seo ?? null })
+}
+
+// ---------------------------------------------------------------------------
+// Route table + dispatcher
+// ---------------------------------------------------------------------------
+
+const SEO_ROUTES: readonly Route<[CmsHandlerOptions]>[] = [
+  { method: 'GET', pattern: `${CMS_API_PREFIX}/seo/targets`, handler: handleGetTargets },
+  {
+    method: 'PUT',
+    pattern: new RegExp(`^${CMS_API_PREFIX}/seo/targets/(?<kind>page|template|post)/(?<id>[^/]+)$`),
+    handler: handlePutTarget,
+  },
+  { method: 'PUT', pattern: `${CMS_API_PREFIX}/seo/site`, handler: handlePutSiteSeo },
+]
+
+export async function handleSeoRoutes(
+  req: Request,
+  db: DbClient,
+  options: CmsHandlerOptions,
+): Promise<Response | null> {
+  return runRouteTable(req, db, SEO_ROUTES, options)
+}
diff --git a/src/__tests__/admin/capabilityAwareAdmin.test.tsx b/src/__tests__/admin/capabilityAwareAdmin.test.tsx
index e4b47f0f5..5ea7d76d3 100644
--- a/src/__tests__/admin/capabilityAwareAdmin.test.tsx
+++ b/src/__tests__/admin/capabilityAwareAdmin.test.tsx
@@ -71,8 +71,7 @@ function makeTable(id: string, name: string, slug: string) {
       { type: 'text', id: 'slug', label: 'Slug', required: true, builtIn: true },
       { type: 'richText', id: 'body', label: 'Body', format: 'markdown', builtIn: true },
       { type: 'media', id: 'featuredMedia', label: 'Featured media', mediaKind: 'image', builtIn: true },
-      { type: 'text', id: 'seoTitle', label: 'SEO title', builtIn: true },
-      { type: 'longText', id: 'seoDescription', label: 'SEO description', builtIn: true },
+      { type: 'seoMetadata', id: 'seo', label: 'SEO', builtIn: true },
     ],
     createdByUserId: null,
     updatedByUserId: null,
diff --git a/src/__tests__/admin/seoWorkspace.test.tsx b/src/__tests__/admin/seoWorkspace.test.tsx
new file mode 100644
index 000000000..e1ba7b58a
--- /dev/null
+++ b/src/__tests__/admin/seoWorkspace.test.tsx
@@ -0,0 +1,297 @@
+/**
+ * SEO workspace UI tests — /admin/tools/seo.
+ *
+ * Renders the Meta/Robots/Sitemap tabs against a mocked fetch:
+ *   - tab switching through the Tabs primitive
+ *   - target search / filter / selection driving the preview editor
+ *   - snippet edits writing the STRUCTURED seo object on save
+ *   - inherited values rendering as placeholders (X falls back to OG/search)
+ *   - the Customize X gate
+ *   - robots toggles updating the generated preview
+ *   - the Tools nav dropdown exposing the SEO link
+ */
+import { afterEach, describe, expect, it } from 'bun:test'
+import { cleanup, fireEvent, render, screen, waitFor, within } from '@testing-library/react'
+import { MemoryRouter } from '@admin/lib/routing'
+import { AdminSessionProvider } from '@admin/session'
+import { AdminSectionNavigation } from '@admin/shared/AdminSectionNavigation'
+import { MetaTab } from '@admin/pages/seo/tabs/MetaTab'
+import { RobotsTab } from '@admin/pages/seo/tabs/RobotsTab'
+import { useSeoWorkspace } from '@admin/pages/seo/hooks/useSeoWorkspace'
+import type { CmsCurrentUser } from '@core/persistence'
+
+const originalFetch = globalThis.fetch
+const now = '2026-06-12T10:00:00.000Z'
+
+function currentUser(capabilities: string[]): CmsCurrentUser {
+  return {
+    id: 'user_1',
+    email: 'seo@example.com',
+    displayName: 'SEO Editor',
+    status: 'active',
+    role: {
+      id: 'test-role',
+      slug: 'test-role',
+      name: 'Test Role',
+      description: '',
+      isSystem: false,
+      capabilities,
+    },
+    capabilities,
+    lastLoginAt: null,
+    failedLoginCount: 0,
+    lockedUntil: null,
+    passwordUpdatedAt: null,
+    mfaEnabled: false,
+    mfaEnabledAt: null,
+    mfaRecoveryCodesRemaining: 0,
+    stepUpAuthMode: 'required',
+    stepUpWindowMinutes: 15,
+    avatarMediaId: null,
+    avatarUrl: null,
+    gravatarHash: '',
+    createdAt: now,
+    updatedAt: now,
+  }
+}
+
+function json(body: unknown, status = 200) {
+  return new Response(JSON.stringify(body), {
+    status,
+    headers: { 'content-type': 'application/json' },
+  })
+}
+
+interface FetchCall {
+  input: RequestInfo | URL
+  init?: RequestInit
+}
+
+const TARGETS_PAYLOAD = {
+  siteName: 'Acme',
+  language: 'en',
+  publicOrigin: 'https://acme.com',
+  siteSeo: {
+    titlePattern: '{page.title} — {site.name}',
+    description: 'Site default description',
+  },
+  targets: [
+    {
+      kind: 'page',
+      id: 'page_home',
+      title: 'Home',
+      route: '/',
+      seo: null,
+      status: 'published',
+      updatedAt: now,
+      publishedAt: now,
+    },
+    {
+      kind: 'page',
+      id: 'page_about',
+      title: 'About',
+      route: '/about',
+      seo: { title: 'About Acme', description: 'Who we are.' },
+      status: 'published',
+      updatedAt: now,
+      publishedAt: now,
+    },
+    {
+      kind: 'template',
+      id: 'page_tpl',
+      title: 'Post template',
+      route: null,
+      templateTableSlugs: ['posts'],
+      seo: { title: '{currentEntry.title} — {site.name}' },
+      status: 'published',
+      updatedAt: now,
+      publishedAt: null,
+    },
+    {
+      kind: 'post',
+      id: 'row_hello',
+      title: 'Hello world',
+      route: '/posts/hello-world',
+      tableSlug: 'posts',
+      tableLabel: 'Posts',
+      seo: null,
+      status: 'published',
+      updatedAt: now,
+      publishedAt: now,
+    },
+  ],
+}
+
+function mockSeoFetch(): FetchCall[] {
+  const calls: FetchCall[] = []
+  globalThis.fetch = (async (input: RequestInfo | URL, init?: RequestInit) => {
+    calls.push({ input, init })
+    const url = String(input)
+    if (url === '/admin/api/cms/seo/targets') return json(TARGETS_PAYLOAD)
+    if (url.startsWith('/admin/api/cms/seo/targets/') && init?.method === 'PUT') {
+      const body = JSON.parse(String(init.body)) as { seo: Record<string, unknown> }
+      const id = url.split('/').at(-1)
+      const stored = TARGETS_PAYLOAD.targets.find((t) => t.id === id)!
+      return json({ target: { ...stored, seo: body.seo } })
+    }
+    if (url === '/admin/api/cms/seo/site' && init?.method === 'PUT') {
+      const body = JSON.parse(String(init.body)) as { seo: Record<string, unknown> }
+      return json({ seo: body.seo })
+    }
+    return json({ error: `Unhandled ${url}` }, 404)
+  }) as typeof fetch
+  return calls
+}
+
+function MetaHarness({ canManage = true }: { canManage?: boolean }) {
+  const workspace = useSeoWorkspace()
+  if (workspace.loading) return <p>Loading…</p>
+  return <MetaTab workspace={workspace} canManage={canManage} />
+}
+
+function RobotsHarness() {
+  const workspace = useSeoWorkspace()
+  if (workspace.loading) return <p>Loading…</p>
+  return <RobotsTab workspace={workspace} canManage />
+}
+
+function renderWithSession(node: React.ReactElement, capabilities: string[] = ['seo.read', 'seo.manage', 'ai.chat']) {
+  return render(
+    <MemoryRouter initialEntries={['/admin/tools/seo']}>
+      <AdminSessionProvider user={currentUser(capabilities)}>
+        {node}
+      </AdminSessionProvider>
+    </MemoryRouter>,
+  )
+}
+
+afterEach(() => {
+  cleanup()
+  globalThis.fetch = originalFetch
+})
+
+describe('SEO Meta tab', () => {
+  it('lists targets, filters by search, and selects into the editor', async () => {
+    mockSeoFetch()
+    renderWithSession(<MetaHarness />)
+
+    const aboutRow = await screen.findByTestId('seo-target-page_about')
+    expect(screen.getByTestId('seo-target-site-defaults')).toBeDefined()
+    expect(screen.getByTestId('seo-target-row_hello')).toBeDefined()
+
+    // Search narrows the list.
+    fireEvent.change(screen.getByTestId('seo-target-search'), { target: { value: 'about' } })
+    expect(screen.queryByTestId('seo-target-row_hello')).toBeNull()
+
+    // Selecting a row activates the preview editor for that target.
+    fireEvent.click(aboutRow)
+    const editor = await screen.findByRole('region', { name: 'SEO for About' })
+    expect(within(editor).getByDisplayValue('About Acme')).toBeDefined()
+  })
+
+  it('shows inherited values as placeholders and saves the structured object', async () => {
+    const calls = mockSeoFetch()
+    renderWithSession(<MetaHarness />)
+
+    fireEvent.click(await screen.findByTestId('seo-target-page_home'))
+    const editor = await screen.findByRole('region', { name: 'SEO for Home' })
+
+    // No explicit title — the placeholder shows the interpolated site pattern.
+    const titleInput = within(editor).getByLabelText('Title') as HTMLInputElement
+    expect(titleInput.value).toBe('')
+    expect(titleInput.placeholder).toBe('Home — Acme')
+
+    fireEvent.change(titleInput, { target: { value: 'Welcome to Acme' } })
+    fireEvent.change(within(editor).getByLabelText('Description'), {
+      target: { value: 'The Acme homepage.' },
+    })
+    fireEvent.click(screen.getByTestId('seo-save'))
+
+    await waitFor(() => {
+      const put = calls.find(
+        (call) =>
+          String(call.input) === '/admin/api/cms/seo/targets/page/page_home' &&
+          call.init?.method === 'PUT',
+      )
+      expect(put).toBeDefined()
+      expect(JSON.parse(String(put!.init!.body))).toEqual({
+        seo: { title: 'Welcome to Acme', description: 'The Acme homepage.' },
+      })
+    })
+  })
+
+  it('keeps X fields behind the customize gate until they differ', async () => {
+    mockSeoFetch()
+    renderWithSession(<MetaHarness />)
+
+    fireEvent.click(await screen.findByTestId('seo-target-page_about'))
+    const editor = await screen.findByRole('region', { name: 'SEO for About' })
+
+    // Switch to the X platform view.
+    fireEvent.click(within(editor).getByRole('button', { name: 'X' }))
+    expect(within(editor).queryByLabelText('X title')).toBeNull()
+
+    fireEvent.click(screen.getByTestId('seo-customize-x'))
+    const xTitle = within(editor).getByLabelText('X title') as HTMLInputElement
+    // Inherits the search title through the OG fallback chain.
+    expect(xTitle.placeholder).toBe('About Acme')
+  })
+
+  it('guards target switching while the editor is dirty', async () => {
+    mockSeoFetch()
+    renderWithSession(<MetaHarness />)
+
+    fireEvent.click(await screen.findByTestId('seo-target-page_home'))
+    const editor = await screen.findByRole('region', { name: 'SEO for Home' })
+    fireEvent.change(within(editor).getByLabelText('Title'), { target: { value: 'Dirty' } })
+
+    // Switching opens the in-app confirm dialog instead of discarding.
+    fireEvent.click(screen.getByTestId('seo-target-page_about'))
+    expect(await screen.findByText('Discard unsaved changes?')).toBeDefined()
+
+    fireEvent.click(screen.getByTestId('seo-discard-switch'))
+    expect(await screen.findByRole('region', { name: 'SEO for About' })).toBeDefined()
+  })
+})
+
+describe('SEO Robots tab', () => {
+  it('updates the generated preview as AI-crawler toggles flip', async () => {
+    mockSeoFetch()
+    renderWithSession(<RobotsHarness />)
+
+    const preview = await screen.findByTestId('seo-robots-preview')
+    expect(preview.textContent).toContain('User-agent: *\nAllow: /')
+    expect(preview.textContent).not.toContain('GPTBot')
+
+    fireEvent.click(screen.getByTestId('seo-robots-ai-training'))
+    expect(screen.getByTestId('seo-robots-preview').textContent).toContain('User-agent: GPTBot\nDisallow: /')
+  })
+})
+
+describe('Tools navigation', () => {
+  it('exposes the SEO link inside the Tools dropdown', async () => {
+    mockSeoFetch()
+    render(
+      <MemoryRouter initialEntries={['/admin/dashboard']}>
+        <AdminSessionProvider user={currentUser(['dashboard.read', 'seo.read'])}>
+          <AdminSectionNavigation section="dashboard" />
+        </AdminSessionProvider>
+      </MemoryRouter>,
+    )
+
+    fireEvent.click(await screen.findByTestId('tools-nav-trigger'))
+    expect(await screen.findByTestId('tools-nav-seo')).toBeDefined()
+  })
+
+  it('hides the Tools dropdown without seo.read or plugin pages', () => {
+    mockSeoFetch()
+    render(
+      <MemoryRouter initialEntries={['/admin/dashboard']}>
+        <AdminSessionProvider user={currentUser(['dashboard.read'])}>
+          <AdminSectionNavigation section="dashboard" />
+        </AdminSessionProvider>
+      </MemoryRouter>,
+    )
+    expect(screen.queryByTestId('tools-nav-trigger')).toBeNull()
+  })
+})
diff --git a/src/__tests__/server/seoHandler.test.ts b/src/__tests__/server/seoHandler.test.ts
new file mode 100644
index 000000000..65a6f5df7
--- /dev/null
+++ b/src/__tests__/server/seoHandler.test.ts
@@ -0,0 +1,220 @@
+/**
+ * SEO workspace API tests — /admin/api/cms/seo/*.
+ *
+ * Real isolated SQLite DB via the capability harness: migrations applied,
+ * owner seeded through the real setup endpoints, requests dispatched through
+ * handleCmsRequest. Covers the target index (pages incl. the seeded entry
+ * template, post rows), target writes (incl. ownership gates), and site SEO
+ * settings persistence.
+ */
+import { beforeAll, afterAll, describe, expect, it } from 'bun:test'
+import {
+  createCapabilityTestHarness,
+  expectForbidden,
+  readJson,
+  type CapabilityTestHarness,
+} from '../helpers/capabilityHarness'
+import type { SeoMetadata, SiteSeoSettings } from '@core/seo'
+
+interface SeoTarget {
+  kind: 'page' | 'template' | 'post'
+  id: string
+  title: string
+  route: string | null
+  tableSlug?: string
+  seo: SeoMetadata | null
+  status: string
+}
+
+interface TargetsResponse {
+  siteName: string
+  publicOrigin: string | null
+  siteSeo: SiteSeoSettings | null
+  targets: SeoTarget[]
+}
+
+let h: CapabilityTestHarness
+let owner: string
+
+beforeAll(async () => {
+  h = await createCapabilityTestHarness()
+  owner = await h.setupOwner()
+})
+
+afterAll(async () => {
+  await h.cleanup()
+})
+
+async function fetchTargets(cookie: string): Promise<TargetsResponse> {
+  const res = await h.cms('/admin/api/cms/seo/targets', { cookie })
+  expect(res.status).toBe(200)
+  return readJson<TargetsResponse>(res)
+}
+
+describe('GET /admin/api/cms/seo/targets', () => {
+  it('returns pages, entry templates, and post rows', async () => {
+    // Creating a postType table through the data API seeds its default entry
+    // template page — the migration-seeded `posts` table predates the boot
+    // backfill in this isolated test DB.
+    const createTableRes = await h.cms('/admin/api/cms/data/tables', {
+      method: 'POST',
+      cookie: owner,
+      json: { name: 'Guides', kind: 'postType', routeBase: '/guides' },
+    })
+    expect([200, 201]).toContain(createTableRes.status)
+
+    // Create one post row through the data API so the index has a 'post' target.
+    const createRes = await h.cms('/admin/api/cms/data/tables/posts/rows', {
+      method: 'POST',
+      cookie: owner,
+      json: { cells: { title: 'Hello world', slug: 'hello-world' } },
+    })
+    expect(createRes.status).toBe(201)
+
+    const body = await fetchTargets(owner)
+    expect(body.siteName.length).toBeGreaterThan(0)
+
+    const kinds = new Set(body.targets.map((t) => t.kind))
+    expect(kinds.has('page')).toBe(true)
+    expect(kinds.has('template')).toBe(true)
+    expect(kinds.has('post')).toBe(true)
+
+    const post = body.targets.find((t) => t.kind === 'post' && t.title === 'Hello world')
+    expect(post).toBeDefined()
+    expect(post!.route).toBe('/posts/hello-world')
+
+    const template = body.targets.find((t) => t.kind === 'template')
+    expect(template!.route).toBeNull()
+  })
+
+  it('requires seo.read', async () => {
+    const stranger = await h.createRoleUser({
+      name: 'No SEO',
+      slug: 'no-seo',
+      capabilities: ['dashboard.read'],
+    })
+    await expectForbidden(await h.cms('/admin/api/cms/seo/targets', { cookie: stranger.cookie }))
+  })
+})
+
+describe('PUT /admin/api/cms/seo/targets/:kind/:id', () => {
+  it('writes the structured seo cell on a post row and round-trips', async () => {
+    const before = await fetchTargets(owner)
+    const post = before.targets.find((t) => t.kind === 'post')!
+
+    const seo: SeoMetadata = {
+      title: 'Custom SEO title',
+      description: 'Custom description',
+      ogImage: '/uploads/og.png',
+      ogImageAlt: 'OG image',
+      noindex: false,
+    }
+    const res = await h.cms(`/admin/api/cms/seo/targets/post/${post.id}`, {
+      method: 'PUT',
+      cookie: owner,
+      json: { seo },
+    })
+    expect(res.status).toBe(200)
+    const { target } = await readJson<{ target: SeoTarget }>(res)
+    expect(target.seo?.title).toBe('Custom SEO title')
+
+    const after = await fetchTargets(owner)
+    expect(after.targets.find((t) => t.id === post.id)!.seo?.description).toBe('Custom description')
+  })
+
+  it('writes page targets through the page kind', async () => {
+    const index = await fetchTargets(owner)
+    const page = index.targets.find((t) => t.kind === 'page')!
+    const res = await h.cms(`/admin/api/cms/seo/targets/page/${page.id}`, {
+      method: 'PUT',
+      cookie: owner,
+      json: { seo: { title: 'Page SEO title' } },
+    })
+    expect(res.status).toBe(200)
+    const after = await fetchTargets(owner)
+    expect(after.targets.find((t) => t.id === page.id)!.seo?.title).toBe('Page SEO title')
+  })
+
+  it('rejects a kind that does not match the row', async () => {
+    const index = await fetchTargets(owner)
+    const page = index.targets.find((t) => t.kind === 'page')!
+    const res = await h.cms(`/admin/api/cms/seo/targets/post/${page.id}`, {
+      method: 'PUT',
+      cookie: owner,
+      json: { seo: { title: 'X' } },
+    })
+    expect(res.status).toBe(400)
+  })
+
+  it('rejects invalid payloads', async () => {
+    const index = await fetchTargets(owner)
+    const page = index.targets.find((t) => t.kind === 'page')!
+    const res = await h.cms(`/admin/api/cms/seo/targets/page/${page.id}`, {
+      method: 'PUT',
+      cookie: owner,
+      json: { seo: { ogType: 'banana' } },
+    })
+    expect(res.status).toBe(400)
+  })
+
+  it('enforces target ownership beyond seo.manage', async () => {
+    // seo.manage but no pages.edit / content edit → 403 on both target kinds.
+    const seoOnly = await h.createRoleUser({
+      name: 'SEO only',
+      slug: 'seo-only',
+      capabilities: ['seo.read', 'seo.manage'],
+    })
+    const index = await fetchTargets(owner)
+    const page = index.targets.find((t) => t.kind === 'page')!
+    const post = index.targets.find((t) => t.kind === 'post')!
+
+    await expectForbidden(await h.cms(`/admin/api/cms/seo/targets/page/${page.id}`, {
+      method: 'PUT',
+      cookie: seoOnly.cookie,
+      json: { seo: { title: 'X' } },
+    }))
+    await expectForbidden(await h.cms(`/admin/api/cms/seo/targets/post/${post.id}`, {
+      method: 'PUT',
+      cookie: seoOnly.cookie,
+      json: { seo: { title: 'X' } },
+    }))
+  })
+})
+
+describe('PUT /admin/api/cms/seo/site', () => {
+  it('persists site SEO defaults incl. robots and sitemap settings', async () => {
+    const seo: SiteSeoSettings = {
+      titlePattern: '{page.title} — {site.name}',
+      description: 'Site default description',
+      defaultXCard: 'summary_large_image',
+      xSiteHandle: '@acme',
+      organization: { name: 'Acme Inc', logoUrl: '/uploads/logo.png' },
+      robots: { allowAiTrainingCrawlers: false },
+      sitemap: { enabled: true, excludedTargets: [] },
+    }
+    const res = await h.cms('/admin/api/cms/seo/site', {
+      method: 'PUT',
+      cookie: owner,
+      json: { seo },
+    })
+    expect(res.status).toBe(200)
+
+    const after = await fetchTargets(owner)
+    expect(after.siteSeo?.titlePattern).toBe('{page.title} — {site.name}')
+    expect(after.siteSeo?.robots?.allowAiTrainingCrawlers).toBe(false)
+    expect(after.siteSeo?.organization?.name).toBe('Acme Inc')
+  })
+
+  it('requires seo.manage', async () => {
+    const reader = await h.createRoleUser({
+      name: 'SEO reader',
+      slug: 'seo-reader',
+      capabilities: ['seo.read'],
+    })
+    await expectForbidden(await h.cms('/admin/api/cms/seo/site', {
+      method: 'PUT',
+      cookie: reader.cookie,
+      json: { seo: {} },
+    }))
+  })
+})
diff --git a/src/admin/AuthenticatedAdmin.tsx b/src/admin/AuthenticatedAdmin.tsx
index 831e422f4..8ef6e98b5 100644
--- a/src/admin/AuthenticatedAdmin.tsx
+++ b/src/admin/AuthenticatedAdmin.tsx
@@ -95,6 +95,10 @@ const AiPage = prewarmedLazy(
   () => import('./pages/ai/AiPage').then((m) => ({ default: m.AiPage })),
   { displayName: 'AiPage' },
 )
+const SeoPage = prewarmedLazy(
+  () => import('./pages/seo/SeoPage').then((m) => ({ default: m.SeoPage })),
+  { displayName: 'SeoPage' },
+)
 const AccountPage = prewarmedLazy(
   () => import('./pages/account/AccountPage').then((m) => ({ default: m.AccountPage })),
   { displayName: 'AccountPage' },
@@ -151,6 +155,7 @@ if (typeof window !== 'undefined') {
     pathname.startsWith('/admin/plugins') ? PluginsPage :
     pathname.startsWith('/admin/users') ? UsersPage :
     pathname.startsWith('/admin/ai') ? AiPage :
+    pathname.startsWith('/admin/tools/seo') ? SeoPage :
     pathname.startsWith('/admin/account') ? AccountPage :
     DashboardPage
   void activePage.preload().catch(() => {
@@ -179,6 +184,7 @@ const ALL_WORKSPACE_PAGES = [
   PluginsPage,
   UsersPage,
   AiPage,
+  SeoPage,
   AccountPage,
   PluginPage,
 ]
@@ -192,6 +198,7 @@ function pageForSection(section: AdminWorkspace) {
     section === 'plugins' ? PluginsPage :
     section === 'users' ? UsersPage :
     section === 'ai' ? AiPage :
+    section === 'seo' ? SeoPage :
     section === 'pluginPage' ? PluginPage :
     section === 'account' ? AccountPage :
     DashboardPage
@@ -311,6 +318,7 @@ export default function AuthenticatedAdmin({ section, currentUser }: Authenticat
               section === 'plugins' ? <PluginsPage /> :
               section === 'users' ? <UsersPage /> :
               section === 'ai' ? <AiPage /> :
+              section === 'seo' ? <SeoPage /> :
               section === 'pluginPage' ? <PluginPage /> :
               section === 'account' ? <AccountPage /> :
               <DashboardPage />}
diff --git a/src/admin/access.ts b/src/admin/access.ts
index da768d15b..52cdc3d99 100644
--- a/src/admin/access.ts
+++ b/src/admin/access.ts
@@ -220,6 +220,8 @@ export function canAccessWorkspace(user: CmsCurrentUser | null, workspace: Admin
       return canAccessUsersWorkspace(user)
     case 'ai':
       return canAccessAiWorkspace(user)
+    case 'seo':
+      return hasCapability(user, 'seo.read')
     case 'account':
       // Self-targeted page — every authenticated user can manage their own
       // profile + devices. Anonymous visitors fall through to false.
@@ -231,7 +233,7 @@ export function firstAccessibleWorkspace(user: CmsCurrentUser | null): AdminWork
   // Dashboard comes first — it's the canonical admin home. Falls through to
   // the next accessible workspace for users whose role doesn't grant
   // `dashboard.read` (rare; only happens with hand-edited custom roles).
-  const order: AdminWorkspace[] = ['dashboard', 'site', 'content', 'data', 'media', 'plugins', 'users', 'ai']
+  const order: AdminWorkspace[] = ['dashboard', 'site', 'content', 'data', 'media', 'plugins', 'users', 'ai', 'seo']
   return order.find((workspace) => canAccessWorkspace(user, workspace)) ?? null
 }
 
@@ -253,6 +255,8 @@ export function workspacePath(workspace: AdminWorkspace): string {
       return '/admin/users'
     case 'ai':
       return '/admin/ai'
+    case 'seo':
+      return '/admin/tools/seo'
     case 'pluginPage':
       return '/admin/plugins'
     case 'account':
diff --git a/src/admin/pages/seo/SeoPage.module.css b/src/admin/pages/seo/SeoPage.module.css
new file mode 100644
index 000000000..789ccb655
--- /dev/null
+++ b/src/admin/pages/seo/SeoPage.module.css
@@ -0,0 +1,16 @@
+.tabsRow {
+  display: flex;
+  gap: 6px;
+}
+
+.body {
+  display: flex;
+  flex-direction: column;
+  gap: 16px;
+}
+
+.loadError {
+  margin: 24px 0;
+  color: var(--editor-danger-text);
+  font-size: 13px;
+}
diff --git a/src/admin/pages/seo/SeoPage.tsx b/src/admin/pages/seo/SeoPage.tsx
new file mode 100644
index 000000000..69e591d47
--- /dev/null
+++ b/src/admin/pages/seo/SeoPage.tsx
@@ -0,0 +1,72 @@
+/**
+ * SeoPage — `/admin/tools/seo`.
+ *
+ * The SEO & AEO workspace: per-target metadata editing with live platform
+ * previews (Meta tab), generated robots.txt with AI-crawler controls
+ * (Robots.txt tab), and sitemap generation settings (Sitemap tab).
+ *
+ * Tab chrome uses the shared `Tabs` compound primitive (ARIA tabs with
+ * automatic activation); the page owns the active value and the shared
+ * workspace data (one `GET /seo/targets` load).
+ *
+ * Capabilities: `seo.read` gates the workspace (enforced by
+ * `canAccessWorkspace`); `seo.manage` gates every write — tabs receive
+ * `canManage` and disable their editing affordances with inline reasons.
+ */
+
+import { useState } from 'react'
+import { Tabs, TabList, Tab, TabPanel } from '@ui/components/Tabs'
+import { AdminPageLayout } from '@admin/layouts/AdminPageLayout'
+import { hasCapability } from '@admin/access'
+import { useCurrentAdminUser } from '@admin/sessionContext'
+import { MetaTab } from './tabs/MetaTab'
+import { RobotsTab } from './tabs/RobotsTab'
+import { SitemapTab } from './tabs/SitemapTab'
+import { useSeoWorkspace } from './hooks/useSeoWorkspace'
+import styles from './SeoPage.module.css'
+
+type TabValue = 'meta' | 'robots' | 'sitemap'
+
+export function SeoPage() {
+  const currentUser = useCurrentAdminUser()
+  const unrestricted = !currentUser
+  const canManage = unrestricted || hasCapability(currentUser, 'seo.manage')
+
+  const [tab, setTab] = useState<TabValue>('meta')
+  const workspace = useSeoWorkspace()
+
+  return (
+    <Tabs value={tab} onChange={setTab}>
+      <AdminPageLayout
+        workspace="seo"
+        title="SEO"
+        titleId="seo-title"
+        description="Search and answer-engine optimization: metadata, social cards, structured data, robots, and sitemap."
+        tabs={
+          <TabList ariaLabel="SEO sections">
+            <Tab value="meta">Meta</Tab>
+            <Tab value="robots">Robots.txt</Tab>
+            <Tab value="sitemap">Sitemap</Tab>
+          </TabList>
+        }
+        loading={workspace.loading}
+      >
+        {workspace.error ? (
+          <p className={styles.loadError} role="alert">{workspace.error}</p>
+        ) : (
+          <div className={styles.body}>
+            <TabPanel value="meta">
+              <MetaTab workspace={workspace} canManage={canManage} />
+            </TabPanel>
+            <TabPanel value="robots">
+              <RobotsTab workspace={workspace} canManage={canManage} />
+            </TabPanel>
+            <TabPanel value="sitemap">
+              <SitemapTab workspace={workspace} canManage={canManage} />
+            </TabPanel>
+          </div>
+        )}
+      </AdminPageLayout>
+    </Tabs>
+  )
+}
diff --git a/src/admin/pages/seo/components/AiSuggestionBubbles.module.css b/src/admin/pages/seo/components/AiSuggestionBubbles.module.css
new file mode 100644
index 000000000..304c7cde8
--- /dev/null
+++ b/src/admin/pages/seo/components/AiSuggestionBubbles.module.css
@@ -0,0 +1,37 @@
+.wrap {
+  display: flex;
+  flex-direction: column;
+  gap: 6px;
+  align-items: flex-end;
+}
+
+.loadingText {
+  font-size: 11px;
+  color: var(--editor-text-muted);
+}
+
+.error {
+  margin: 0;
+  font-size: 11px;
+  color: var(--editor-danger-text);
+  text-align: right;
+}
+
+.bubbles {
+  display: flex;
+  flex-wrap: wrap;
+  gap: 6px;
+  justify-content: flex-end;
+}
+
+.bubble {
+  max-width: 100%;
+  white-space: normal;
+  text-align: left;
+  border-radius: var(--input-radius);
+}
+
+.bubbleAction {
+  border-radius: var(--input-radius);
+  color: var(--editor-text-muted);
+}
diff --git a/src/admin/pages/seo/components/AiSuggestionBubbles.tsx b/src/admin/pages/seo/components/AiSuggestionBubbles.tsx
new file mode 100644
index 000000000..7720e1284
--- /dev/null
+++ b/src/admin/pages/seo/components/AiSuggestionBubbles.tsx
@@ -0,0 +1,128 @@
+/**
+ * AiSuggestionSparkle — the ✨ action on metadata inputs.
+ *
+ * Click → `POST /admin/api/cms/seo/generate` → three suggestions render as
+ * tappable bubbles under the input. Tapping fills the input through the
+ * normal dirty/save flow (nothing auto-saves). Two trailing bubbles:
+ * "More options" regenerates (excluding already-shown texts) and "Reject"
+ * dismisses the row.
+ *
+ * Gating: requires `ai.chat` — without it the sparkle renders disabled with
+ * an inline reason (never available-then-blocked). Provider-not-configured
+ * surfaces as an inline error with a pointer to the AI workspace, matching
+ * the AgentPanel's handling.
+ */
+import { useState } from 'react'
+import { Button } from '@ui/components/Button'
+import { AiBoxSolidIcon } from 'pixel-art-icons/icons/ai-box-solid'
+import { hasCapability } from '@admin/access'
+import { useCurrentAdminUser } from '@admin/sessionContext'
+import { getErrorMessage } from '@core/utils/errorMessage'
+import { generateSeoSuggestions, type SeoTarget } from '../lib/seoApi'
+import type { SeoDraftField } from '../hooks/useSeoDraft'
+import styles from './AiSuggestionBubbles.module.css'
+
+interface AiSuggestionSparkleProps {
+  target: SeoTarget
+  field: SeoDraftField
+  canManage: boolean
+  onPick: (suggestion: string) => void
+}
+
+export function AiSuggestionSparkle({ target, field, canManage, onPick }: AiSuggestionSparkleProps) {
+  const currentUser = useCurrentAdminUser()
+  const unrestricted = !currentUser
+  const canChat = unrestricted || hasCapability(currentUser, 'ai.chat')
+
+  const [suggestions, setSuggestions] = useState<string[] | null>(null)
+  const [seen, setSeen] = useState<string[]>([])
+  const [loading, setLoading] = useState(false)
+  const [error, setError] = useState<string | null>(null)
+
+  async function generate(exclude: string[]): Promise<void> {
+    setLoading(true)
+    setError(null)
+    try {
+      const next = await generateSeoSuggestions(target.kind, target.id, field, exclude)
+      setSuggestions(next)
+      setSeen([...exclude, ...next])
+    } catch (err) {
+      console.error('[seo-page] suggestion generation failed:', err)
+      setError(getErrorMessage(err, 'Could not generate suggestions'))
+    } finally {
+      setLoading(false)
+    }
+  }
+
+  function pick(suggestion: string): void {
+    onPick(suggestion)
+    setSuggestions(null)
+  }
+
+  const disabledReason = !canManage
+    ? 'Your role does not include Manage SEO'
+    : !canChat
+      ? 'Your role does not include Use AI chat'
+      : undefined
+
+  return (
+    <div className={styles.wrap}>
+      <Button
+        type="button"
+        variant="ghost"
+        size="xs"
+        disabled={disabledReason !== undefined || loading}
+        tooltip={disabledReason ?? 'Generate suggestions with AI'}
+        aria-label={`Generate ${field} suggestions with AI`}
+        onClick={() => void generate([])}
+        data-testid={`seo-sparkle-${field}`}
+      >
+        <AiBoxSolidIcon size={13} aria-hidden="true" />
+        {loading && <span className={styles.loadingText}>Generating…</span>}
+      </Button>
+
+      {error && <p className={styles.error} role="alert">{error}</p>}
+
+      {suggestions !== null && suggestions.length > 0 && (
+        <div className={styles.bubbles} role="group" aria-label="AI suggestions">
+          {suggestions.map((suggestion) => (
+            <Button
+              key={suggestion}
+              type="button"
+              variant="secondary"
+              size="xs"
+              className={styles.bubble}
+              onClick={() => pick(suggestion)}
+            >
+              {suggestion}
+            </Button>
+          ))}
+          <Button
+            type="button"
+            variant="ghost"
+            size="xs"
+            className={styles.bubbleAction}
+            disabled={loading}
+            onClick={() => void generate(seen)}
+            data-testid={`seo-sparkle-${field}-more`}
+          >
+            More options
+          </Button>
+          <Button
+            type="button"
+            variant="ghost"
+            size="xs"
+            className={styles.bubbleAction}
+            onClick={() => {
+              setSuggestions(null)
+              setError(null)
+            }}
+            data-testid={`seo-sparkle-${field}-reject`}
+          >
+            Reject
+          </Button>
+        </div>
+      )}
+    </div>
+  )
+}
diff --git a/src/admin/pages/seo/components/MetaLengthMeter.module.css b/src/admin/pages/seo/components/MetaLengthMeter.module.css
new file mode 100644
index 000000000..bf7989026
--- /dev/null
+++ b/src/admin/pages/seo/components/MetaLengthMeter.module.css
@@ -0,0 +1,56 @@
+.meter {
+  display: flex;
+  align-items: center;
+  gap: 8px;
+}
+
+.meterInherited {
+  opacity: 0.55;
+}
+
+.track {
+  position: relative;
+  flex: 1;
+  height: 3px;
+  border-radius: 2px;
+  background: var(--editor-surface-4);
+  overflow: hidden;
+}
+
+.fill {
+  position: absolute;
+  inset: 0 auto 0 0;
+  width: var(--seo-meter-fill);
+  border-radius: 2px;
+}
+
+.fill_ok {
+  background: var(--editor-success-green);
+}
+
+.fill_amber {
+  background: var(--editor-warning);
+}
+
+.fill_over {
+  background: var(--editor-danger);
+}
+
+.count {
+  font-size: 10px;
+  font-variant-numeric: tabular-nums;
+  color: var(--editor-text-muted);
+}
+
+.count_amber {
+  color: var(--editor-warning-text);
+}
+
+.count_over {
+  color: var(--editor-danger-text);
+}
+
+/* Track reads the fill width from the custom property set inline. */
+.track {
+  --seo-meter-fill: 0%;
+}
diff --git a/src/admin/pages/seo/components/MetaLengthMeter.tsx b/src/admin/pages/seo/components/MetaLengthMeter.tsx
new file mode 100644
index 000000000..d6cdf0e80
--- /dev/null
+++ b/src/admin/pages/seo/components/MetaLengthMeter.tsx
@@ -0,0 +1,51 @@
+/**
+ * MetaLengthMeter — live character + approximate pixel-width meter for SEO
+ * title/description fields, against Google's desktop truncation budgets
+ * (~580px title / ~990px description). Zones: ok (≤85%), amber, over.
+ * Inherited (placeholder) values render the meter muted — informative but
+ * clearly not the user's own text.
+ */
+import { cn } from '@ui/cn'
+import {
+  approxPixelWidth,
+  meterZone,
+  TITLE_PIXEL_BUDGET,
+  DESCRIPTION_PIXEL_BUDGET,
+  TITLE_CHAR_GUIDE,
+  DESCRIPTION_CHAR_GUIDE,
+} from '@core/seo'
+import type { CSSProperties } from 'react'
+import styles from './MetaLengthMeter.module.css'
+
+interface MetaLengthMeterProps {
+  text: string
+  budget: 'title' | 'description'
+  /** False when the meter measures an inherited placeholder, not user text. */
+  explicit: boolean
+}
+
+export function MetaLengthMeter({ text, budget, explicit }: MetaLengthMeterProps) {
+  const pixelBudget = budget === 'title' ? TITLE_PIXEL_BUDGET : DESCRIPTION_PIXEL_BUDGET
+  const charGuide = budget === 'title' ? TITLE_CHAR_GUIDE : DESCRIPTION_CHAR_GUIDE
+  const width = approxPixelWidth(text)
+  const zone = meterZone(width, pixelBudget)
+  const fillPct = Math.min(100, Math.round((width / pixelBudget) * 100))
+
+  return (
+    <div
+      className={cn(styles.meter, !explicit && styles.meterInherited)}
+      role="status"
+      aria-label={`${budget === 'title' ? 'Title' : 'Description'} length: ${text.length} characters, ${zone === 'over' ? 'over' : 'within'} the display budget`}
+    >
+      <span
+        className={cn(styles.track)}
+        style={{ '--seo-meter-fill': `${fillPct}%` } as CSSProperties}
+      >
+        <span className={cn(styles.fill, styles[`fill_${zone}`])} />
+      </span>
+      <span className={cn(styles.count, styles[`count_${zone}`])}>
+        {text.length}/{charGuide}
+      </span>
+    </div>
+  )
+}
diff --git a/src/admin/pages/seo/components/OpenGraphPreview.module.css b/src/admin/pages/seo/components/OpenGraphPreview.module.css
new file mode 100644
index 000000000..7171e574b
--- /dev/null
+++ b/src/admin/pages/seo/components/OpenGraphPreview.module.css
@@ -0,0 +1,54 @@
+.card {
+  display: flex;
+  flex-direction: column;
+  margin: 0;
+  border-radius: var(--panel-radius);
+  overflow: hidden;
+  background: var(--editor-surface);
+}
+
+.image {
+  width: 100%;
+  aspect-ratio: 1.91 / 1;
+  object-fit: cover;
+}
+
+.imagePlaceholder {
+  width: 100%;
+  aspect-ratio: 1.91 / 1;
+  display: flex;
+  align-items: center;
+  justify-content: center;
+  background: var(--editor-surface-3);
+  color: var(--editor-text-muted);
+  font-size: 12px;
+}
+
+.meta {
+  display: flex;
+  flex-direction: column;
+  gap: 2px;
+  padding: 10px 14px;
+}
+
+.site {
+  font-size: 10px;
+  text-transform: uppercase;
+  letter-spacing: 0.04em;
+  color: var(--editor-text-muted);
+}
+
+.title {
+  font-size: 13px;
+  font-weight: 700;
+  color: var(--editor-text-bright);
+}
+
+.description {
+  font-size: 12px;
+  color: var(--editor-text);
+  display: -webkit-box;
+  -webkit-line-clamp: 2;
+  -webkit-box-orient: vertical;
+  overflow: hidden;
+}
diff --git a/src/admin/pages/seo/components/OpenGraphPreview.tsx b/src/admin/pages/seo/components/OpenGraphPreview.tsx
new file mode 100644
index 000000000..c606516f8
--- /dev/null
+++ b/src/admin/pages/seo/components/OpenGraphPreview.tsx
@@ -0,0 +1,23 @@
+/**
+ * OpenGraphPreview — link-card mock (Facebook/LinkedIn-style) rendered from
+ * resolved values: image area, site name, OG title + description.
+ */
+import type { ResolvedSeoMetadata } from '@core/seo'
+import styles from './OpenGraphPreview.module.css'
+
+export function OpenGraphPreview({ resolved, siteName }: { resolved: ResolvedSeoMetadata; siteName: string }) {
+  return (
+    <figure className={styles.card} aria-label="Open Graph preview">
+      {resolved.ogImage ? (
+        <img className={styles.image} src={resolved.ogImage} alt={resolved.ogImageAlt ?? ''} />
+      ) : (
+        <div className={styles.imagePlaceholder} aria-hidden="true">No social image</div>
+      )}
+      <div className={styles.meta}>
+        <span className={styles.site}>{siteName}</span>
+        <span className={styles.title}>{resolved.ogTitle}</span>
+        {resolved.ogDescription && <span className={styles.description}>{resolved.ogDescription}</span>}
+      </div>
+    </figure>
+  )
+}
diff --git a/src/admin/pages/seo/components/SchemaPreview.module.css b/src/admin/pages/seo/components/SchemaPreview.module.css
new file mode 100644
index 000000000..f16f5d2a2
--- /dev/null
+++ b/src/admin/pages/seo/components/SchemaPreview.module.css
@@ -0,0 +1,14 @@
+.schema {
+  display: flex;
+  flex-direction: column;
+  gap: 10px;
+}
+
+.empty {
+  margin: 0;
+  padding: 14px 16px;
+  border-radius: var(--panel-radius);
+  background: var(--editor-surface);
+  font-size: 12px;
+  color: var(--editor-text-muted);
+}
diff --git a/src/admin/pages/seo/components/SchemaPreview.tsx b/src/admin/pages/seo/components/SchemaPreview.tsx
new file mode 100644
index 000000000..cddf81044
--- /dev/null
+++ b/src/admin/pages/seo/components/SchemaPreview.tsx
@@ -0,0 +1,48 @@
+/**
+ * SchemaPreview — read-only, pretty-printed JSON-LD exactly as the publisher
+ * will emit it for the selected target (same `buildJsonLdEntities` call).
+ * Makes the AEO output inspectable instead of invisible.
+ */
+import { buildJsonLdEntities, type ResolvedSeoMetadata } from '@core/seo'
+import { Code } from '@ui/components/Code'
+import type { SeoTarget } from '../lib/seoApi'
+import type { SeoWorkspace } from '../hooks/useSeoWorkspace'
+import styles from './SchemaPreview.module.css'
+
+export function SchemaPreview({
+  target,
+  resolved,
+  workspace,
+}: {
+  target: SeoTarget
+  resolved: ResolvedSeoMetadata
+  workspace: SeoWorkspace
+}) {
+  const entities = buildJsonLdEntities(resolved, {
+    kind: target.kind === 'post' ? 'row' : 'page',
+    routePath: target.route ?? '/',
+    origin: workspace.publicOrigin ?? undefined,
+    siteName: workspace.siteName,
+    organization: workspace.siteSeo?.organization,
+  })
+
+  if (entities.length === 0) {
+    return (
+      <p className={styles.empty} role="status">
+        {resolved.noindex
+          ? 'Noindex targets emit no structured data.'
+          : workspace.publicOrigin
+            ? 'No structured data applies to this target.'
+            : 'Structured data with absolute URLs is emitted once PUBLIC_ORIGINS is configured.'}
+      </p>
+    )
+  }
+
+  return (
+    <div className={styles.schema} aria-label="JSON-LD structured data preview">
+      {entities.map((entity, index) => (
+        <Code key={index}>{JSON.stringify(entity, null, 2)}</Code>
+      ))}
+    </div>
+  )
+}
diff --git a/src/admin/pages/seo/components/SearchSnippetPreview.module.css b/src/admin/pages/seo/components/SearchSnippetPreview.module.css
new file mode 100644
index 000000000..1b051d9b3
--- /dev/null
+++ b/src/admin/pages/seo/components/SearchSnippetPreview.module.css
@@ -0,0 +1,42 @@
+.snippet {
+  display: flex;
+  flex-direction: column;
+  gap: 2px;
+  margin: 0;
+  padding: 14px 16px;
+  border-radius: var(--panel-radius);
+  background: var(--editor-surface);
+}
+
+.url {
+  font-size: 11px;
+  color: var(--editor-text-muted);
+  white-space: nowrap;
+  overflow: hidden;
+  text-overflow: ellipsis;
+}
+
+.title {
+  font-size: 16px;
+  font-weight: 500;
+  color: var(--editor-info-text);
+  overflow-wrap: break-word;
+}
+
+.description {
+  font-size: 12px;
+  line-height: 1.5;
+  color: var(--editor-text);
+}
+
+.noindexBadge {
+  align-self: flex-start;
+  margin-top: 6px;
+  font-size: 10px;
+  text-transform: uppercase;
+  letter-spacing: 0.04em;
+  padding: 2px 6px;
+  border-radius: var(--editor-radius-sm);
+  background: var(--editor-danger-bg);
+  color: var(--editor-danger-text);
+}
diff --git a/src/admin/pages/seo/components/SearchSnippetPreview.tsx b/src/admin/pages/seo/components/SearchSnippetPreview.tsx
new file mode 100644
index 000000000..09e26e827
--- /dev/null
+++ b/src/admin/pages/seo/components/SearchSnippetPreview.tsx
@@ -0,0 +1,24 @@
+/**
+ * SearchSnippetPreview — Google-style result snippet rendered from the
+ * RESOLVED metadata, so what the user sees is what the publisher emits.
+ * Pure display; editing happens in the controlled inputs below it.
+ */
+import type { ResolvedSeoMetadata } from '@core/seo'
+import styles from './SearchSnippetPreview.module.css'
+
+export function SearchSnippetPreview({ resolved }: { resolved: ResolvedSeoMetadata }) {
+  return (
+    <figure className={styles.snippet} aria-label="Search result preview">
+      <span className={styles.url}>
+        {resolved.canonicalUrl ?? 'example.com — set PUBLIC_ORIGINS for absolute URLs'}
+      </span>
+      <span className={styles.title}>{resolved.title}</span>
+      <span className={styles.description}>
+        {resolved.description ?? 'Search engines will generate a description from page content.'}
+      </span>
+      {resolved.noindex && (
+        <span className={styles.noindexBadge} role="status">noindex — hidden from search</span>
+      )}
+    </figure>
+  )
+}
diff --git a/src/admin/pages/seo/components/SeoImageField.module.css b/src/admin/pages/seo/components/SeoImageField.module.css
new file mode 100644
index 000000000..58384ebae
--- /dev/null
+++ b/src/admin/pages/seo/components/SeoImageField.module.css
@@ -0,0 +1,24 @@
+.field {
+  display: flex;
+  flex-direction: column;
+  gap: 4px;
+}
+
+.label {
+  font-size: 11px;
+  font-weight: 600;
+  text-transform: uppercase;
+  letter-spacing: 0.04em;
+  color: var(--editor-text-muted);
+}
+
+.controls {
+  display: flex;
+  align-items: center;
+  gap: 6px;
+}
+
+.controls > :first-child {
+  flex: 1;
+  min-width: 0;
+}
diff --git a/src/admin/pages/seo/components/SeoImageField.tsx b/src/admin/pages/seo/components/SeoImageField.tsx
new file mode 100644
index 000000000..872a18426
--- /dev/null
+++ b/src/admin/pages/seo/components/SeoImageField.tsx
@@ -0,0 +1,81 @@
+/**
+ * SeoImageField — social-image picker for OG/X images.
+ *
+ * Primary affordance: the media library picker (same `MediaPickerModal` the
+ * favicon picker uses). A URL input stays available as the secondary path
+ * for externally-hosted images. Empty value falls back through the resolver
+ * chain — the inherited value renders as a muted preview row.
+ */
+import { lazy, Suspense, useState } from 'react'
+import { Button } from '@ui/components/Button'
+import { Input } from '@ui/components/Input'
+import { ImagesSolidIcon } from 'pixel-art-icons/icons/images-solid'
+import type { CmsMediaAsset } from '@core/persistence'
+import styles from './SeoImageField.module.css'
+
+const MediaPickerModal = lazy(() =>
+  import('@admin/pages/media/components/MediaPickerModal/MediaPickerModal').then(
+    (m) => ({ default: m.MediaPickerModal }),
+  ),
+)
+
+interface SeoImageFieldProps {
+  label: string
+  /** Explicit value ('' when inheriting). */
+  value: string
+  /** Resolved fallback shown when no explicit value is set. */
+  inheritedValue: string | null
+  disabled: boolean
+  onChange: (next: string) => void
+}
+
+export function SeoImageField({ label, value, inheritedValue, disabled, onChange }: SeoImageFieldProps) {
+  const [pickerOpen, setPickerOpen] = useState(false)
+
+  function handlePick(asset: CmsMediaAsset): void {
+    onChange(asset.publicPath)
+    setPickerOpen(false)
+  }
+
+  return (
+    <div className={styles.field}>
+      <span className={styles.label}>{label}</span>
+      <div className={styles.controls}>
+        <Input
+          type="text"
+          value={value}
+          placeholder={inheritedValue ?? 'No image — pick from the library'}
+          disabled={disabled}
+          aria-label={`${label} URL`}
+          onChange={(e) => onChange(e.target.value)}
+        />
+        <Button
+          variant="secondary"
+          size="sm"
+          disabled={disabled}
+          onClick={() => setPickerOpen(true)}
+          aria-label={`Browse media library for ${label}`}
+        >
+          <ImagesSolidIcon size={13} aria-hidden="true" />
+          <span>Browse</span>
+        </Button>
+        {value !== '' && (
+          <Button variant="ghost" size="sm" disabled={disabled} onClick={() => onChange('')} aria-label={`Clear ${label}`}>
+            Clear
+          </Button>
+        )}
+      </div>
+      {pickerOpen && (
+        <Suspense fallback={null}>
+          <MediaPickerModal
+            open={pickerOpen}
+            onClose={() => setPickerOpen(false)}
+            mediaKind="image"
+            currentValue={value || null}
+            onPick={handlePick}
+          />
+        </Suspense>
+      )}
+    </div>
+  )
+}
diff --git a/src/admin/pages/seo/components/SeoPreviewEditor.module.css b/src/admin/pages/seo/components/SeoPreviewEditor.module.css
new file mode 100644
index 000000000..276b5f56d
--- /dev/null
+++ b/src/admin/pages/seo/components/SeoPreviewEditor.module.css
@@ -0,0 +1,126 @@
+.editor {
+  display: flex;
+  flex-direction: column;
+  gap: 14px;
+  background: var(--editor-surface-2);
+  border-radius: 16px;
+  padding: 16px;
+}
+
+.header {
+  display: flex;
+  align-items: flex-start;
+  justify-content: space-between;
+  gap: 12px;
+}
+
+.headerText {
+  display: flex;
+  flex-direction: column;
+  gap: 2px;
+  min-width: 0;
+}
+
+.headerTitle {
+  margin: 0;
+  font-size: 15px;
+  font-weight: 700;
+  color: var(--editor-text-bright);
+  white-space: nowrap;
+  overflow: hidden;
+  text-overflow: ellipsis;
+}
+
+.headerRoute {
+  font-size: 11px;
+  color: var(--editor-text-muted);
+}
+
+.saveControls {
+  display: flex;
+  align-items: center;
+  gap: 8px;
+  flex-shrink: 0;
+}
+
+.saveStatus {
+  font-size: 11px;
+  color: var(--editor-text-muted);
+}
+
+.error {
+  margin: 0;
+  font-size: 12px;
+  color: var(--editor-danger-text);
+}
+
+.readOnlyNote,
+.templateNote {
+  margin: 0;
+  font-size: 12px;
+  color: var(--editor-info-text);
+}
+
+.platformBody {
+  display: flex;
+  flex-direction: column;
+  gap: 12px;
+}
+
+.field {
+  display: flex;
+  flex-direction: column;
+  gap: 4px;
+}
+
+.fieldLabelRow {
+  display: flex;
+  align-items: center;
+  justify-content: space-between;
+  gap: 8px;
+}
+
+.fieldLabel {
+  font-size: 11px;
+  font-weight: 600;
+  text-transform: uppercase;
+  letter-spacing: 0.04em;
+  color: var(--editor-text-muted);
+}
+
+.fieldHint {
+  margin: 0;
+  font-size: 11px;
+  color: var(--editor-text-muted);
+}
+
+.switchRow {
+  display: flex;
+  align-items: center;
+  gap: 8px;
+}
+
+.switchLabel {
+  font-size: 12px;
+  color: var(--editor-text);
+}
+
+.customizeRow {
+  display: flex;
+  align-items: center;
+  justify-content: space-between;
+  gap: 12px;
+}
+
+.customizeHint {
+  margin: 0;
+  font-size: 12px;
+  color: var(--editor-text-muted);
+}
+
+.sectionHeading {
+  margin: 8px 0 0;
+  font-size: 12px;
+  font-weight: 700;
+  color: var(--editor-text-bright);
+}
diff --git a/src/admin/pages/seo/components/SeoPreviewEditor.tsx b/src/admin/pages/seo/components/SeoPreviewEditor.tsx
new file mode 100644
index 000000000..b4d1ef772
--- /dev/null
+++ b/src/admin/pages/seo/components/SeoPreviewEditor.tsx
@@ -0,0 +1,329 @@
+/**
+ * SeoPreviewEditor — the Meta tab's left column for page / template / post
+ * targets.
+ *
+ * Platform switcher (Search / Open Graph / X / Schema) over an editable
+ * snippet: controlled Input/Textarea primitives styled as the platform
+ * preview, never raw contentEditable. Every empty field shows its RESOLVED
+ * fallback as placeholder text (the shared `@core/seo` resolver), so the
+ * user always sees exactly what will be emitted. Title/description carry
+ * live pixel meters. Save is quiet and local.
+ */
+import { useId, useState } from 'react'
+import { Button } from '@ui/components/Button'
+import { Input, Textarea } from '@ui/components/Input'
+import { Select } from '@ui/components/Select'
+import { Switch } from '@ui/components/Switch'
+import { SegmentedControl } from '@ui/components/SegmentedControl'
+import { getErrorMessage } from '@core/utils/errorMessage'
+import { isSafeCanonicalUrl } from '@core/seo'
+import type { SeoTarget } from '../lib/seoApi'
+import { resolveTargetSeo, templateForPost } from '../lib/resolveTargetSeo'
+import type { SeoWorkspace } from '../hooks/useSeoWorkspace'
+import { useSeoDraft, normalizeSeoDraft, type SeoDraftField } from '../hooks/useSeoDraft'
+import { SearchSnippetPreview } from './SearchSnippetPreview'
+import { OpenGraphPreview } from './OpenGraphPreview'
+import { XCardPreview } from './XCardPreview'
+import { SchemaPreview } from './SchemaPreview'
+import { MetaLengthMeter } from './MetaLengthMeter'
+import { SeoImageField } from './SeoImageField'
+import { AiSuggestionSparkle } from './AiSuggestionBubbles'
+import styles from './SeoPreviewEditor.module.css'
+
+type Platform = 'search' | 'og' | 'x' | 'schema'
+
+const PLATFORM_OPTIONS: { value: Platform; label: string }[] = [
+  { value: 'search', label: 'Search' },
+  { value: 'og', label: 'Open Graph' },
+  { value: 'x', label: 'X' },
+  { value: 'schema', label: 'Schema' },
+]
+
+interface SeoPreviewEditorProps {
+  target: SeoTarget
+  workspace: SeoWorkspace
+  canManage: boolean
+  onDirtyChange: (dirty: boolean) => void
+}
+
+export function SeoPreviewEditor({ target, workspace, canManage, onDirtyChange }: SeoPreviewEditorProps) {
+  const [platform, setPlatform] = useState<Platform>('search')
+  const draft = useSeoDraft(target.seo, onDirtyChange)
+  const fieldIdBase = useId()
+
+  const resolved = resolveTargetSeo(target, draft.draft, workspace.resolveContext)
+  const template = templateForPost(target, workspace.targets)
+  const canonicalValue = draft.draft.canonicalUrl ?? ''
+  const canonicalInvalid = canonicalValue !== '' && !isSafeCanonicalUrl(canonicalValue)
+
+  async function handleSave(): Promise<void> {
+    if (canonicalInvalid) {
+      draft.markError('Canonical URL must be an absolute http(s) URL')
+      return
+    }
+    draft.markSaving()
+    try {
+      const normalized = normalizeSeoDraft(draft.draft)
+      await workspace.saveTarget(target.kind, target.id, normalized)
+      draft.markSaved(normalized)
+    } catch (err) {
+      console.error('[seo-page] save failed:', err)
+      draft.markError(getErrorMessage(err, 'Could not save SEO metadata'))
+    }
+  }
+
+  const xCustomized =
+    draft.draft.xTitle !== undefined ||
+    draft.draft.xDescription !== undefined ||
+    draft.draft.xImage !== undefined ||
+    draft.draft.xImageAlt !== undefined ||
+    draft.draft.xCard !== undefined
+  const [xExpanded, setXExpanded] = useState(false)
+  const showXFields = xCustomized || xExpanded
+
+  function field(field: SeoDraftField, label: string, opts?: {
+    textarea?: boolean
+    meterBudget?: 'title' | 'description'
+    invalid?: boolean
+    sparkle?: boolean
+  }) {
+    const id = `${fieldIdBase}-${field}`
+    const value = draft.draft[field] ?? ''
+    const placeholder = resolvedPlaceholder(field)
+    const common = {
+      id,
+      value,
+      placeholder,
+      disabled: !canManage,
+      'aria-invalid': opts?.invalid || undefined,
+    }
+    return (
+      <div className={styles.field}>
+        <div className={styles.fieldLabelRow}>
+          <label htmlFor={id} className={styles.fieldLabel}>{label}</label>
+          {opts?.sparkle && (
+            <AiSuggestionSparkle
+              target={target}
+              field={field}
+              canManage={canManage}
+              onPick={(suggestion) => draft.setField(field, suggestion)}
+            />
+          )}
+        </div>
+        {opts?.textarea ? (
+          <Textarea
+            {...common}
+            rows={3}
+            onChange={(e) => draft.setField(field, e.target.value)}
+          />
+        ) : (
+          <Input
+            {...common}
+            type="text"
+            onChange={(e) => draft.setField(field, e.target.value)}
+          />
+        )}
+        {opts?.meterBudget && (
+          <MetaLengthMeter text={value || placeholder || ''} budget={opts.meterBudget} explicit={value !== ''} />
+        )}
+      </div>
+    )
+  }
+
+  function resolvedPlaceholder(field: SeoDraftField): string {
+    switch (field) {
+      case 'title': return resolved.title
+      case 'description': return resolved.description ?? 'No description — add one or set a site default'
+      case 'canonicalUrl': return resolved.canonicalUrl ?? 'Derived from the public origin'
+      case 'ogTitle': return resolved.ogTitle
+      case 'ogDescription': return resolved.ogDescription ?? ''
+      case 'ogImage': return resolved.ogImage ?? ''
+      case 'ogImageAlt': return resolved.ogImageAlt ?? ''
+      case 'xTitle': return resolved.xTitle
+      case 'xDescription': return resolved.xDescription ?? ''
+      case 'xImage': return resolved.xImage ?? ''
+      case 'xImageAlt': return resolved.xImageAlt ?? ''
+    }
+  }
+
+  return (
+    <section className={styles.editor} aria-label={`SEO for ${target.title}`}>
+      <header className={styles.header}>
+        <div className={styles.headerText}>
+          <h2 className={styles.headerTitle}>{target.title}</h2>
+          <span className={styles.headerRoute}>
+            {target.route ?? (target.kind === 'template' ? `Entry template${target.tableSlug ? ` · ${target.tableSlug}` : ''}` : '')}
+          </span>
+        </div>
+        <SaveControls
+          dirty={draft.isDirty}
+          state={draft.saveState}
+          canManage={canManage}
+          onSave={() => void handleSave()}
+        />
+      </header>
+      {draft.saveError && <p className={styles.error} role="alert">{draft.saveError}</p>}
+      {!canManage && (
+        <p className={styles.readOnlyNote} role="status">
+          Read-only — your role does not include Manage SEO.
+        </p>
+      )}
+      {target.kind === 'template' && (
+        <p className={styles.templateNote} role="status">
+          Template defaults — title and description act as patterns
+          (<code>{'{currentEntry.title}'}</code>, <code>{'{site.name}'}</code>) for every matching post.
+        </p>
+      )}
+
+      <SegmentedControl
+        value={platform}
+        options={PLATFORM_OPTIONS}
+        onChange={setPlatform}
+        size="sm"
+        aria-label="Preview platform"
+        data-testid="seo-platform-switcher"
+      />
+
+      {platform === 'search' && (
+        <div className={styles.platformBody}>
+          <SearchSnippetPreview resolved={resolved} />
+          {field('title', 'Title', { meterBudget: 'title', sparkle: true })}
+          {field('description', 'Description', { textarea: true, meterBudget: 'description', sparkle: true })}
+          {field('canonicalUrl', 'Canonical URL', { invalid: canonicalInvalid })}
+          {canonicalInvalid && (
+            <p className={styles.error} role="alert">Canonical URL must be an absolute http(s) URL.</p>
+          )}
+          <div className={styles.switchRow}>
+            <Switch
+              checked={draft.draft.noindex === true}
+              onCheckedChange={draft.setNoindex}
+              disabled={!canManage}
+              aria-label="Exclude from search engines (noindex)"
+              switchSize="sm"
+            />
+            <span className={styles.switchLabel}>
+              Exclude from search engines (<code>noindex</code>)
+            </span>
+          </div>
+        </div>
+      )}
+
+      {platform === 'og' && (
+        <div className={styles.platformBody}>
+          <OpenGraphPreview resolved={resolved} siteName={workspace.siteName} />
+          {field('ogTitle', 'OG title', { sparkle: true })}
+          {field('ogDescription', 'OG description', { textarea: true, sparkle: true })}
+          <SeoImageField
+            label="OG image"
+            value={draft.draft.ogImage ?? ''}
+            inheritedValue={resolved.ogImage ?? null}
+            disabled={!canManage}
+            onChange={(next) => draft.setField('ogImage', next)}
+          />
+          {field('ogImageAlt', 'OG image alt')}
+          <div className={styles.field}>
+            <label htmlFor={`${fieldIdBase}-ogType`} className={styles.fieldLabel}>OG type</label>
+            <Select
+              id={`${fieldIdBase}-ogType`}
+              value={draft.draft.ogType ?? ''}
+              disabled={!canManage}
+              onChange={(e) => draft.setOgType(e.target.value === '' ? undefined : (e.target.value as 'website' | 'article'))}
+            >
+              <option value="">Auto ({resolved.ogType})</option>
+              <option value="website">website</option>
+              <option value="article">article</option>
+            </Select>
+          </div>
+        </div>
+      )}
+
+      {platform === 'x' && (
+        <div className={styles.platformBody}>
+          <XCardPreview resolved={resolved} />
+          {!showXFields ? (
+            <div className={styles.customizeRow}>
+              <p className={styles.customizeHint}>
+                X uses the Open Graph values until customized.
+              </p>
+              <Button variant="secondary" size="sm" disabled={!canManage} onClick={() => setXExpanded(true)} data-testid="seo-customize-x">
+                Customize X preview
+              </Button>
+            </div>
+          ) : (
+            <>
+              {field('xTitle', 'X title', { sparkle: true })}
+              {field('xDescription', 'X description', { textarea: true, sparkle: true })}
+              <SeoImageField
+                label="X image"
+                value={draft.draft.xImage ?? ''}
+                inheritedValue={resolved.xImage ?? null}
+                disabled={!canManage}
+                onChange={(next) => draft.setField('xImage', next)}
+              />
+              {field('xImageAlt', 'X image alt')}
+              <div className={styles.field}>
+                <label htmlFor={`${fieldIdBase}-xCard`} className={styles.fieldLabel}>Card type</label>
+                <Select
+                  id={`${fieldIdBase}-xCard`}
+                  value={draft.draft.xCard ?? ''}
+                  disabled={!canManage}
+                  onChange={(e) => draft.setXCard(e.target.value === '' ? undefined : (e.target.value as 'summary' | 'summary_large_image'))}
+                >
+                  <option value="">Auto ({resolved.xCard})</option>
+                  <option value="summary">summary</option>
+                  <option value="summary_large_image">summary_large_image</option>
+                </Select>
+              </div>
+            </>
+          )}
+        </div>
+      )}
+
+      {platform === 'schema' && (
+        <div className={styles.platformBody}>
+          <SchemaPreview target={target} resolved={resolved} workspace={workspace} />
+          {template && (
+            <p className={styles.templateNote} role="status">
+              Patterns inherit from the “{template.title}” entry template.
+            </p>
+          )}
+        </div>
+      )}
+    </section>
+  )
+}
+
+/** Quiet save affordance: Save button + tiny inline state text. */
+export function SaveControls({
+  dirty,
+  state,
+  canManage,
+  onSave,
+}: {
+  dirty: boolean
+  state: 'idle' | 'saving' | 'saved' | 'error'
+  canManage: boolean
+  onSave: () => void
+}) {
+  const statusText =
+    state === 'saving' ? 'Saving…'
+    : state === 'saved' && !dirty ? 'Saved'
+    : dirty ? 'Unsaved changes' : ''
+  return (
+    <div className={styles.saveControls}>
+      {statusText && (
+        <span className={styles.saveStatus} role="status">{statusText}</span>
+      )}
+      <Button
+        variant="primary"
+        size="sm"
+        disabled={!canManage || !dirty || state === 'saving'}
+        tooltip={!canManage ? 'Your role does not include Manage SEO' : undefined}
+        onClick={onSave}
+        data-testid="seo-save"
+      >
+        Save
+      </Button>
+    </div>
+  )
+}
diff --git a/src/admin/pages/seo/components/SeoTargetIndex.module.css b/src/admin/pages/seo/components/SeoTargetIndex.module.css
new file mode 100644
index 000000000..ca2bd5a78
--- /dev/null
+++ b/src/admin/pages/seo/components/SeoTargetIndex.module.css
@@ -0,0 +1,126 @@
+.index {
+  display: flex;
+  flex-direction: column;
+  gap: 10px;
+}
+
+.summaryRow {
+  display: flex;
+  flex-wrap: wrap;
+  gap: 6px;
+}
+
+.summaryChip {
+  font-size: 11px;
+  padding: 2px 8px;
+  border-radius: var(--editor-radius-sm);
+  background: var(--editor-surface-3);
+  color: var(--editor-warning-text);
+}
+
+.list {
+  display: flex;
+  flex-direction: column;
+  gap: 1px;
+  background: var(--editor-surface);
+  border-radius: 16px;
+  overflow: hidden;
+  outline: none;
+}
+
+.list:focus-visible {
+  box-shadow: 0 0 0 2px var(--editor-focus-ring);
+}
+
+.row {
+  display: flex;
+  align-items: center;
+  justify-content: space-between;
+  gap: 10px;
+  width: 100%;
+  padding: 8px 12px;
+  border-radius: 0;
+  background: var(--editor-surface-2);
+  text-align: left;
+}
+
+.row:hover {
+  background: var(--editor-surface-3);
+}
+
+.rowSelected,
+.rowSelected:hover {
+  background: var(--editor-surface-4);
+}
+
+.rowPinned {
+  background: var(--editor-surface-3);
+}
+
+.rowMain {
+  display: flex;
+  flex-direction: column;
+  gap: 1px;
+  min-width: 0;
+}
+
+.rowTitle {
+  font-size: 12px;
+  font-weight: 600;
+  color: var(--editor-text-bright);
+  white-space: nowrap;
+  overflow: hidden;
+  text-overflow: ellipsis;
+}
+
+.rowSub {
+  font-size: 11px;
+  color: var(--editor-text-muted);
+  white-space: nowrap;
+  overflow: hidden;
+  text-overflow: ellipsis;
+}
+
+.rowMeta {
+  display: flex;
+  align-items: center;
+  gap: 8px;
+  flex-shrink: 0;
+}
+
+.rowKind {
+  font-size: 10px;
+  text-transform: uppercase;
+  letter-spacing: 0.04em;
+  color: var(--editor-text-muted);
+}
+
+.dots {
+  display: inline-flex;
+  gap: 3px;
+}
+
+.dot {
+  width: 6px;
+  height: 6px;
+  border-radius: 50%;
+}
+
+.dot_ok {
+  background: var(--editor-success-green);
+}
+
+.dot_warn {
+  background: var(--editor-warning);
+}
+
+.dot_bad {
+  background: var(--editor-danger);
+}
+
+.empty {
+  padding: 16px;
+  font-size: 12px;
+  color: var(--editor-text-muted);
+  background: var(--editor-surface-2);
+}
diff --git a/src/admin/pages/seo/components/SeoTargetIndex.tsx b/src/admin/pages/seo/components/SeoTargetIndex.tsx
new file mode 100644
index 000000000..8948707cc
--- /dev/null
+++ b/src/admin/pages/seo/components/SeoTargetIndex.tsx
@@ -0,0 +1,232 @@
+/**
+ * SeoTargetIndex — the Meta tab's right column: navigation + audit context.
+ *
+ * Search bar, kind filters (All / Pages / Posts / Templates / Issues), an
+ * issues summary chip row, the pinned Site defaults row, and dense target
+ * rows with per-field health dots. Keyboard: ↑/↓ move the selection,
+ * Enter activates, `/` focuses search.
+ */
+import { useRef, useState, type KeyboardEvent } from 'react'
+import { SearchBar } from '@ui/components/SearchBar'
+import { SegmentedControl } from '@ui/components/SegmentedControl'
+import { Button } from '@ui/components/Button'
+import { computeSeoHealth, type SeoHealth } from '@core/seo'
+import { cn } from '@ui/cn'
+import type { SeoTarget } from '../lib/seoApi'
+import { resolveTargetSeo } from '../lib/resolveTargetSeo'
+import type { SeoWorkspace } from '../hooks/useSeoWorkspace'
+import styles from './SeoTargetIndex.module.css'
+
+type Filter = 'all' | 'pages' | 'posts' | 'templates' | 'issues'
+
+const FILTER_OPTIONS: { value: Filter; label: string }[] = [
+  { value: 'all', label: 'All' },
+  { value: 'pages', label: 'Pages' },
+  { value: 'posts', label: 'Posts' },
+  { value: 'templates', label: 'Templates' },
+  { value: 'issues', label: 'Issues' },
+]
+
+interface IndexedTarget {
+  target: SeoTarget
+  health: SeoHealth
+}
+
+interface SeoTargetIndexProps {
+  workspace: SeoWorkspace
+  selectedId: string
+  siteDefaultsId: string
+  onSelect: (id: string) => void
+}
+
+export function SeoTargetIndex({ workspace, selectedId, siteDefaultsId, onSelect }: SeoTargetIndexProps) {
+  const [query, setQuery] = useState('')
+  const [filter, setFilter] = useState<Filter>('all')
+  const searchRef = useRef<HTMLInputElement>(null)
+  const listRef = useRef<HTMLDivElement>(null)
+
+  const indexed: IndexedTarget[] = workspace.targets.map((target) => ({
+    target,
+    health: computeSeoHealth(
+      target.seo ?? undefined,
+      resolveTargetSeo(target, undefined, workspace.resolveContext),
+    ),
+  }))
+
+  const missingTitles = indexed.filter((item) => item.health.title !== 'ok').length
+  const missingDescriptions = indexed.filter((item) => item.health.description !== 'ok').length
+  const noindexed = indexed.filter((item) => !item.health.indexable).length
+
+  const normalizedQuery = query.trim().toLowerCase()
+  const visible = indexed.filter(({ target, health }) => {
+    if (filter === 'pages' && target.kind !== 'page') return false
+    if (filter === 'posts' && target.kind !== 'post') return false
+    if (filter === 'templates' && target.kind !== 'template') return false
+    if (filter === 'issues' && health.issueCount === 0) return false
+    if (normalizedQuery === '') return true
+    return (
+      target.title.toLowerCase().includes(normalizedQuery) ||
+      (target.route ?? '').toLowerCase().includes(normalizedQuery)
+    )
+  })
+
+  // Keyboard order: pinned site row first, then the visible targets.
+  const order: string[] = [siteDefaultsId, ...visible.map(({ target }) => target.id)]
+
+  function handleListKeyDown(event: KeyboardEvent<HTMLDivElement>): void {
+    if (event.key === '/') {
+      event.preventDefault()
+      searchRef.current?.focus()
+      return
+    }
+    if (event.key !== 'ArrowDown' && event.key !== 'ArrowUp') return
+    event.preventDefault()
+    const currentIndex = order.indexOf(selectedId)
+    const nextIndex = event.key === 'ArrowDown'
+      ? Math.min(order.length - 1, currentIndex + 1)
+      : Math.max(0, currentIndex - 1)
+    const next = order[nextIndex]
+    if (next !== undefined && next !== selectedId) onSelect(next)
+  }
+
+  return (
+    <section className={styles.index} aria-label="SEO targets">
+      <SearchBar
+        ref={searchRef}
+        value={query}
+        onValueChange={setQuery}
+        placeholder="Search targets…"
+        aria-label="Search SEO targets"
+        data-testid="seo-target-search"
+      />
+
+      <SegmentedControl
+        value={filter}
+        options={FILTER_OPTIONS}
+        onChange={setFilter}
+        size="xs"
+        aria-label="Filter targets"
+        data-testid="seo-target-filter"
+      />
+
+      {(missingTitles > 0 || missingDescriptions > 0 || noindexed > 0) && (
+        <div className={styles.summaryRow} role="status">
+          {missingTitles > 0 && (
+            <span className={styles.summaryChip}>{missingTitles} title {missingTitles === 1 ? 'issue' : 'issues'}</span>
+          )}
+          {missingDescriptions > 0 && (
+            <span className={styles.summaryChip}>{missingDescriptions} description {missingDescriptions === 1 ? 'issue' : 'issues'}</span>
+          )}
+          {noindexed > 0 && (
+            <span className={styles.summaryChip}>{noindexed} noindexed</span>
+          )}
+        </div>
+      )}
+
+      {/* eslint-disable-next-line jsx-a11y/no-noninteractive-element-interactions -- keyboard list navigation; rows themselves are buttons */}
+      <div
+        ref={listRef}
+        className={styles.list}
+        role="listbox"
+        aria-label="SEO target list"
+        tabIndex={0}
+        onKeyDown={handleListKeyDown}
+      >
+        <TargetRow
+          pinned
+          label="Site defaults"
+          sublabel="Fallbacks for every target"
+          selected={selectedId === siteDefaultsId}
+          onSelect={() => onSelect(siteDefaultsId)}
+          testId="seo-target-site-defaults"
+        />
+        {visible.map(({ target, health }) => (
+          <TargetRow
+            key={target.id}
+            label={target.title}
+            sublabel={target.route ?? (target.kind === 'template' ? 'Entry template' : '—')}
+            kind={target.kind}
+            tableLabel={target.tableLabel}
+            health={health}
+            selected={selectedId === target.id}
+            onSelect={() => onSelect(target.id)}
+            testId={`seo-target-${target.id}`}
+          />
+        ))}
+        {visible.length === 0 && (
+          <p className={styles.empty} role="status">No targets match the current filter.</p>
+        )}
+      </div>
+    </section>
+  )
+}
+
+function TargetRow({
+  label,
+  sublabel,
+  kind,
+  tableLabel,
+  health,
+  selected,
+  pinned = false,
+  onSelect,
+  testId,
+}: {
+  label: string
+  sublabel: string
+  kind?: SeoTarget['kind']
+  tableLabel?: string
+  health?: SeoHealth
+  selected: boolean
+  pinned?: boolean
+  onSelect: () => void
+  testId: string
+}) {
+  const kindLabel = kind === 'post' ? (tableLabel ?? 'Post') : kind === 'template' ? 'Template' : kind === 'page' ? 'Page' : 'Site'
+  return (
+    <Button
+      type="button"
+      variant="ghost"
+      className={cn(styles.row, selected && styles.rowSelected, pinned && styles.rowPinned)}
+      role="option"
+      aria-selected={selected}
+      onClick={onSelect}
+      data-testid={testId}
+    >
+      <span className={styles.rowMain}>
+        <span className={styles.rowTitle}>{label}</span>
+        <span className={styles.rowSub}>{sublabel}</span>
+      </span>
+      <span className={styles.rowMeta}>
+        <span className={styles.rowKind}>{kindLabel}</span>
+        {health && <HealthDots health={health} />}
+      </span>
+    </Button>
+  )
+}
+
+/**
+ * Compact health indicators: title, description, image, indexing — green
+ * when ok, amber for soft issues, red for missing/noindex. Each dot carries
+ * a title tooltip naming the field + state for hover discovery.
+ */
+function HealthDots({ health }: { health: SeoHealth }) {
+  return (
+    <span className={styles.dots} aria-label={healthSummary(health)}>
+      <Dot state={health.title === 'ok' ? 'ok' : health.title === 'long' ? 'warn' : 'bad'} label={`Title: ${health.title}`} />
+      <Dot state={health.description === 'ok' ? 'ok' : health.description === 'long' ? 'warn' : 'bad'} label={`Description: ${health.description}`} />
+      <Dot state={health.image === 'ok' ? 'ok' : health.image === 'missingAlt' ? 'warn' : 'bad'} label={`Social image: ${health.image}`} />
+      <Dot state={health.indexable ? 'ok' : 'bad'} label={health.indexable ? 'Indexable' : 'Noindex'} />
+    </span>
+  )
+}
+
+function healthSummary(health: SeoHealth): string {
+  return health.issueCount === 0
+    ? 'No SEO issues'
+    : `${health.issueCount} SEO ${health.issueCount === 1 ? 'issue' : 'issues'}`
+}
+
+function Dot({ state, label }: { state: 'ok' | 'warn' | 'bad'; label: string }) {
+  return <span className={cn(styles.dot, styles[`dot_${state}`])} title={label} />
+}
diff --git a/src/admin/pages/seo/components/SiteDefaultsEditor.tsx b/src/admin/pages/seo/components/SiteDefaultsEditor.tsx
new file mode 100644
index 000000000..5f6ad8b2e
--- /dev/null
+++ b/src/admin/pages/seo/components/SiteDefaultsEditor.tsx
@@ -0,0 +1,246 @@
+/**
+ * SiteDefaultsEditor — the pinned "Site defaults" target's editing surface.
+ *
+ * Edits `site.settings.seo`: the title pattern (shared `{source.field}`
+ * token syntax), site description, default social image + alt, default X
+ * card type, X site handle, and the Organization fields that feed the
+ * site-wide JSON-LD. Robots/sitemap settings live on the same object but
+ * are edited in their own tabs.
+ */
+import { useEffect, useId, useState } from 'react'
+import { Input, Textarea } from '@ui/components/Input'
+import { Select } from '@ui/components/Select'
+import { getErrorMessage } from '@core/utils/errorMessage'
+import type { SiteSeoSettings } from '@core/seo'
+import type { SeoWorkspace } from '../hooks/useSeoWorkspace'
+import { SeoImageField } from './SeoImageField'
+import { SaveControls } from './SeoPreviewEditor'
+import styles from './SeoPreviewEditor.module.css'
+
+type SiteStringField =
+  | 'titlePattern'
+  | 'description'
+  | 'defaultOgImage'
+  | 'defaultOgImageAlt'
+  | 'xSiteHandle'
+
+function normalizeSiteSeo(draft: SiteSeoSettings): SiteSeoSettings {
+  const next: SiteSeoSettings = {}
+  const stringFields: SiteStringField[] = ['titlePattern', 'description', 'defaultOgImage', 'defaultOgImageAlt', 'xSiteHandle']
+  for (const key of stringFields) {
+    const value = draft[key]
+    if (typeof value === 'string' && value.trim() !== '') next[key] = value.trim()
+  }
+  if (draft.defaultXCard !== undefined) next.defaultXCard = draft.defaultXCard
+  const orgName = draft.organization?.name?.trim() ?? ''
+  const orgLogo = draft.organization?.logoUrl?.trim() ?? ''
+  if (orgName !== '' || orgLogo !== '') {
+    next.organization = {
+      ...(orgName !== '' ? { name: orgName } : {}),
+      ...(orgLogo !== '' ? { logoUrl: orgLogo } : {}),
+    }
+  }
+  if (draft.robots !== undefined) next.robots = draft.robots
+  if (draft.sitemap !== undefined) next.sitemap = draft.sitemap
+  return next
+}
+
+function sameSiteSeo(a: SiteSeoSettings, b: SiteSeoSettings): boolean {
+  return JSON.stringify(normalizeSiteSeo(a)) === JSON.stringify(normalizeSiteSeo(b))
+}
+
+interface SiteDefaultsEditorProps {
+  workspace: SeoWorkspace
+  canManage: boolean
+  onDirtyChange: (dirty: boolean) => void
+}
+
+export function SiteDefaultsEditor({ workspace, canManage, onDirtyChange }: SiteDefaultsEditorProps) {
+  const stored = workspace.siteSeo ?? {}
+  const [draft, setDraft] = useState<SiteSeoSettings>(stored)
+  const [baseline, setBaseline] = useState<SiteSeoSettings>(stored)
+  const [saveState, setSaveState] = useState<'idle' | 'saving' | 'saved' | 'error'>('idle')
+  const [saveError, setSaveError] = useState<string | null>(null)
+  const idBase = useId()
+
+  const isDirty = !sameSiteSeo(draft, baseline)
+
+  // Exception #1 (React Compiler rules): parent dirty-guard consumes this
+  // through an effect so it tracks every dirtiness flip.
+  useEffect(() => {
+    onDirtyChange(isDirty)
+    // eslint-disable-next-line react-hooks/exhaustive-deps -- notify only when dirtiness flips
+  }, [isDirty])
+
+  function setField(field: SiteStringField, value: string): void {
+    setDraft((current) => {
+      const next = { ...current }
+      if (value === '') delete next[field]
+      else next[field] = value
+      return next
+    })
+    if (saveState !== 'idle') setSaveState('idle')
+  }
+
+  function setOrgField(field: 'name' | 'logoUrl', value: string): void {
+    setDraft((current) => {
+      const organization = { ...current.organization }
+      if (value === '') delete organization[field]
+      else organization[field] = value
+      const next = { ...current }
+      if (Object.keys(organization).length === 0) delete next.organization
+      else next.organization = organization
+      return next
+    })
+    if (saveState !== 'idle') setSaveState('idle')
+  }
+
+  async function handleSave(): Promise<void> {
+    setSaveState('saving')
+    setSaveError(null)
+    try {
+      const normalized = normalizeSiteSeo(draft)
+      await workspace.saveSite(normalized)
+      setBaseline(normalized)
+      setDraft(normalized)
+      setSaveState('saved')
+    } catch (err) {
+      console.error('[seo-page] site defaults save failed:', err)
+      setSaveState('error')
+      setSaveError(getErrorMessage(err, 'Could not save site SEO defaults'))
+    }
+  }
+
+  return (
+    <section className={styles.editor} aria-label="Site SEO defaults">
+      <header className={styles.header}>
+        <div className={styles.headerText}>
+          <h2 className={styles.headerTitle}>Site defaults</h2>
+          <span className={styles.headerRoute}>Fallbacks for every page and post</span>
+        </div>
+        <SaveControls dirty={isDirty} state={saveState} canManage={canManage} onSave={() => void handleSave()} />
+      </header>
+      {saveError && <p className={styles.error} role="alert">{saveError}</p>}
+      {!canManage && (
+        <p className={styles.readOnlyNote} role="status">
+          Read-only — your role does not include Manage SEO.
+        </p>
+      )}
+      {!workspace.siteSeo && !isDirty && (
+        <p className={styles.templateNote} role="status">
+          No site defaults yet — set a title pattern and description so every
+          target has sensible metadata out of the box.
+        </p>
+      )}
+
+      <div className={styles.platformBody}>
+        <div className={styles.field}>
+          <label htmlFor={`${idBase}-pattern`} className={styles.fieldLabel}>Title pattern</label>
+          <Input
+            id={`${idBase}-pattern`}
+            type="text"
+            value={draft.titlePattern ?? ''}
+            placeholder="{page.title} — {site.name}"
+            disabled={!canManage}
+            onChange={(e) => setField('titlePattern', e.target.value)}
+          />
+          <p className={styles.fieldHint}>
+            Tokens: <code>{'{page.title}'}</code>, <code>{'{site.name}'}</code>, <code>{'{currentEntry.title}'}</code>.
+            Targets with an explicit SEO title skip the pattern.
+          </p>
+        </div>
+
+        <div className={styles.field}>
+          <label htmlFor={`${idBase}-description`} className={styles.fieldLabel}>Site description</label>
+          <Textarea
+            id={`${idBase}-description`}
+            rows={3}
+            value={draft.description ?? ''}
+            placeholder="Used when a page or post has no description of its own."
+            disabled={!canManage}
+            onChange={(e) => setField('description', e.target.value)}
+          />
+        </div>
+
+        <SeoImageField
+          label="Default social image"
+          value={draft.defaultOgImage ?? ''}
+          inheritedValue={null}
+          disabled={!canManage}
+          onChange={(next) => setField('defaultOgImage', next)}
+        />
+
+        <div className={styles.field}>
+          <label htmlFor={`${idBase}-ogalt`} className={styles.fieldLabel}>Default image alt text</label>
+          <Input
+            id={`${idBase}-ogalt`}
+            type="text"
+            value={draft.defaultOgImageAlt ?? ''}
+            disabled={!canManage}
+            onChange={(e) => setField('defaultOgImageAlt', e.target.value)}
+          />
+        </div>
+
+        <div className={styles.field}>
+          <label htmlFor={`${idBase}-xcard`} className={styles.fieldLabel}>Default X card</label>
+          <Select
+            id={`${idBase}-xcard`}
+            value={draft.defaultXCard ?? ''}
+            disabled={!canManage}
+            onChange={(e) => {
+              const value = e.target.value
+              setDraft((current) => {
+                const next = { ...current }
+                if (value === '') delete next.defaultXCard
+                else next.defaultXCard = value as 'summary' | 'summary_large_image'
+                return next
+              })
+              if (saveState !== 'idle') setSaveState('idle')
+            }}
+          >
+            <option value="">Auto (large when an image is set)</option>
+            <option value="summary">summary</option>
+            <option value="summary_large_image">summary_large_image</option>
+          </Select>
+        </div>
+
+        <div className={styles.field}>
+          <label htmlFor={`${idBase}-xhandle`} className={styles.fieldLabel}>X site handle</label>
+          <Input
+            id={`${idBase}-xhandle`}
+            type="text"
+            value={draft.xSiteHandle ?? ''}
+            placeholder="@yoursite"
+            disabled={!canManage}
+            onChange={(e) => setField('xSiteHandle', e.target.value)}
+          />
+        </div>
+
+        <h3 className={styles.sectionHeading}>Organization (structured data)</h3>
+        <p className={styles.fieldHint}>
+          Emitted as schema.org <code>Organization</code> JSON-LD on the homepage —
+          how answer engines identify who runs this site.
+        </p>
+
+        <div className={styles.field}>
+          <label htmlFor={`${idBase}-orgname`} className={styles.fieldLabel}>Organization name</label>
+          <Input
+            id={`${idBase}-orgname`}
+            type="text"
+            value={draft.organization?.name ?? ''}
+            disabled={!canManage}
+            onChange={(e) => setOrgField('name', e.target.value)}
+          />
+        </div>
+
+        <SeoImageField
+          label="Organization logo"
+          value={draft.organization?.logoUrl ?? ''}
+          inheritedValue={null}
+          disabled={!canManage}
+          onChange={(next) => setOrgField('logoUrl', next)}
+        />
+      </div>
+    </section>
+  )
+}
diff --git a/src/admin/pages/seo/components/XCardPreview.module.css b/src/admin/pages/seo/components/XCardPreview.module.css
new file mode 100644
index 000000000..6370832e2
--- /dev/null
+++ b/src/admin/pages/seo/components/XCardPreview.module.css
@@ -0,0 +1,70 @@
+.card {
+  margin: 0;
+  border-radius: var(--panel-radius);
+  overflow: hidden;
+  background: var(--editor-surface);
+}
+
+.cardLarge {
+  display: flex;
+  flex-direction: column;
+}
+
+.cardSummary {
+  display: grid;
+  grid-template-columns: 96px minmax(0, 1fr);
+  align-items: stretch;
+}
+
+.cardLarge .image,
+.cardLarge .imagePlaceholder {
+  width: 100%;
+  aspect-ratio: 1.91 / 1;
+}
+
+.cardSummary .image,
+.cardSummary .imagePlaceholder {
+  width: 96px;
+  height: 100%;
+  min-height: 96px;
+}
+
+.image {
+  object-fit: cover;
+}
+
+.imagePlaceholder {
+  display: flex;
+  align-items: center;
+  justify-content: center;
+  background: var(--editor-surface-3);
+  color: var(--editor-text-muted);
+  font-size: 11px;
+}
+
+.meta {
+  display: flex;
+  flex-direction: column;
+  gap: 2px;
+  padding: 10px 14px;
+}
+
+.title {
+  font-size: 13px;
+  font-weight: 700;
+  color: var(--editor-text-bright);
+}
+
+.description {
+  font-size: 12px;
+  color: var(--editor-text);
+  display: -webkit-box;
+  -webkit-line-clamp: 2;
+  -webkit-box-orient: vertical;
+  overflow: hidden;
+}
+
+.handle {
+  font-size: 11px;
+  color: var(--editor-text-muted);
+}
diff --git a/src/admin/pages/seo/components/XCardPreview.tsx b/src/admin/pages/seo/components/XCardPreview.tsx
new file mode 100644
index 000000000..131a7b3b7
--- /dev/null
+++ b/src/admin/pages/seo/components/XCardPreview.tsx
@@ -0,0 +1,29 @@
+/**
+ * XCardPreview — X (Twitter) card mock rendered from resolved values.
+ * Layout follows the card type: `summary_large_image` stacks a wide image
+ * above the text; `summary` puts a small square thumb beside it.
+ */
+import { cn } from '@ui/cn'
+import type { ResolvedSeoMetadata } from '@core/seo'
+import styles from './XCardPreview.module.css'
+
+export function XCardPreview({ resolved }: { resolved: ResolvedSeoMetadata }) {
+  const large = resolved.xCard === 'summary_large_image'
+  return (
+    <figure
+      className={cn(styles.card, large ? styles.cardLarge : styles.cardSummary)}
+      aria-label="X card preview"
+    >
+      {resolved.xImage ? (
+        <img className={styles.image} src={resolved.xImage} alt={resolved.xImageAlt ?? ''} />
+      ) : (
+        <div className={styles.imagePlaceholder} aria-hidden="true">No image</div>
+      )}
+      <div className={styles.meta}>
+        <span className={styles.title}>{resolved.xTitle}</span>
+        {resolved.xDescription && <span className={styles.description}>{resolved.xDescription}</span>}
+        {resolved.xSiteHandle && <span className={styles.handle}>{resolved.xSiteHandle}</span>}
+      </div>
+    </figure>
+  )
+}
diff --git a/src/admin/pages/seo/hooks/useSeoDraft.ts b/src/admin/pages/seo/hooks/useSeoDraft.ts
new file mode 100644
index 000000000..9c38a24de
--- /dev/null
+++ b/src/admin/pages/seo/hooks/useSeoDraft.ts
@@ -0,0 +1,141 @@
+/**
+ * useSeoDraft — local draft state for one target's SeoMetadata object.
+ *
+ * Field edits stay local until Save; empty strings mean "unset" (the field
+ * falls back through the resolver chain), so the persisted object only
+ * carries explicit overrides. `isDirty` compares the normalized draft to the
+ * stored value, and the parent is notified so target switching can guard
+ * against silent discards.
+ */
+import { useEffect, useState } from 'react'
+import type { SeoMetadata } from '@core/seo'
+
+export type SeoSaveState = 'idle' | 'saving' | 'saved' | 'error'
+
+/** String-valued SeoMetadata keys editable through the snippet inputs. */
+export type SeoDraftField =
+  | 'title'
+  | 'description'
+  | 'canonicalUrl'
+  | 'ogTitle'
+  | 'ogDescription'
+  | 'ogImage'
+  | 'ogImageAlt'
+  | 'xTitle'
+  | 'xDescription'
+  | 'xImage'
+  | 'xImageAlt'
+
+const STRING_FIELDS: readonly SeoDraftField[] = [
+  'title',
+  'description',
+  'canonicalUrl',
+  'ogTitle',
+  'ogDescription',
+  'ogImage',
+  'ogImageAlt',
+  'xTitle',
+  'xDescription',
+  'xImage',
+  'xImageAlt',
+]
+
+/** Drop empty-string keys so the stored object only has explicit values. */
+export function normalizeSeoDraft(draft: SeoMetadata): SeoMetadata {
+  const next: SeoMetadata = {}
+  for (const key of STRING_FIELDS) {
+    const value = draft[key]
+    if (typeof value === 'string' && value.trim() !== '') next[key] = value.trim()
+  }
+  if (draft.noindex === true) next.noindex = true
+  if (draft.ogType !== undefined) next.ogType = draft.ogType
+  if (draft.xCard !== undefined) next.xCard = draft.xCard
+  return next
+}
+
+function sameSeo(a: SeoMetadata, b: SeoMetadata): boolean {
+  return JSON.stringify(normalizeSeoDraft(a)) === JSON.stringify(normalizeSeoDraft(b))
+}
+
+export interface UseSeoDraftResult {
+  draft: SeoMetadata
+  isDirty: boolean
+  saveState: SeoSaveState
+  saveError: string | null
+  setField: (field: SeoDraftField, value: string) => void
+  setOgType: (value: SeoMetadata['ogType']) => void
+  setXCard: (value: SeoMetadata['xCard']) => void
+  setNoindex: (value: boolean) => void
+  markSaving: () => void
+  markSaved: (saved: SeoMetadata) => void
+  markError: (message: string) => void
+}
+
+export function useSeoDraft(
+  stored: SeoMetadata | null,
+  onDirtyChange: (dirty: boolean) => void,
+): UseSeoDraftResult {
+  const [draft, setDraft] = useState<SeoMetadata>(stored ?? {})
+  const [baseline, setBaseline] = useState<SeoMetadata>(stored ?? {})
+  const [saveState, setSaveState] = useState<SeoSaveState>('idle')
+  const [saveError, setSaveError] = useState<string | null>(null)
+
+  const isDirty = !sameSeo(draft, baseline)
+
+  // Exception #1 (React Compiler rules): the parent's dirty-guard reads this
+  // via effect so it stays correct even when dirtiness changes from saves.
+  useEffect(() => {
+    onDirtyChange(isDirty)
+    // eslint-disable-next-line react-hooks/exhaustive-deps -- notify only when dirtiness flips
+  }, [isDirty])
+
+  function update(mutate: (next: SeoMetadata) => void): void {
+    setDraft((current) => {
+      const next = { ...current }
+      mutate(next)
+      return next
+    })
+    if (saveState !== 'idle') setSaveState('idle')
+    if (saveError) setSaveError(null)
+  }
+
+  return {
+    draft,
+    isDirty,
+    saveState,
+    saveError,
+    setField: (field, value) =>
+      update((next) => {
+        if (value === '') delete next[field]
+        else next[field] = value
+      }),
+    setOgType: (value) =>
+      update((next) => {
+        if (value === undefined) delete next.ogType
+        else next.ogType = value
+      }),
+    setXCard: (value) =>
+      update((next) => {
+        if (value === undefined) delete next.xCard
+        else next.xCard = value
+      }),
+    setNoindex: (value) =>
+      update((next) => {
+        if (value) next.noindex = true
+        else delete next.noindex
+      }),
+    markSaving: () => {
+      setSaveState('saving')
+      setSaveError(null)
+    },
+    markSaved: (saved) => {
+      setBaseline(saved)
+      setDraft(saved)
+      setSaveState('saved')
+    },
+    markError: (message) => {
+      setSaveState('error')
+      setSaveError(message)
+    },
+  }
+}
diff --git a/src/admin/pages/seo/hooks/useSeoWorkspace.ts b/src/admin/pages/seo/hooks/useSeoWorkspace.ts
new file mode 100644
index 000000000..b8bb239bb
--- /dev/null
+++ b/src/admin/pages/seo/hooks/useSeoWorkspace.ts
@@ -0,0 +1,91 @@
+/**
+ * useSeoWorkspace — the SEO workspace's shared data layer.
+ *
+ * Loads the full target index + site SEO settings once, exposes typed save
+ * functions that update local state in place (no refetch on save), and
+ * carries the context object the resolver helpers need.
+ */
+import { useEffect, useState } from 'react'
+import { isAbortError } from '@core/http'
+import { getErrorMessage } from '@core/utils/errorMessage'
+import type { SeoMetadata, SiteSeoSettings } from '@core/seo'
+import {
+  fetchSeoTargets,
+  saveSeoTarget,
+  saveSiteSeo,
+  type SeoTarget,
+  type SeoTargetKind,
+} from '../lib/seoApi'
+import type { ResolveTargetSeoContext } from '../lib/resolveTargetSeo'
+
+export interface SeoWorkspace {
+  loading: boolean
+  error: string | null
+  siteName: string
+  language: string | null
+  publicOrigin: string | null
+  siteSeo: SiteSeoSettings | null
+  targets: SeoTarget[]
+  /** Context bundle for `resolveTargetSeo` / health computation. */
+  resolveContext: ResolveTargetSeoContext
+  /** PUT one target's seo cell; updates local state on success. */
+  saveTarget: (kind: SeoTargetKind, id: string, seo: SeoMetadata) => Promise<void>
+  /** PUT site.settings.seo; updates local state on success. */
+  saveSite: (seo: SiteSeoSettings) => Promise<void>
+}
+
+export function useSeoWorkspace(): SeoWorkspace {
+  const [loading, setLoading] = useState(true)
+  const [error, setError] = useState<string | null>(null)
+  const [siteName, setSiteName] = useState('')
+  const [language, setLanguage] = useState<string | null>(null)
+  const [publicOrigin, setPublicOrigin] = useState<string | null>(null)
+  const [siteSeo, setSiteSeo] = useState<SiteSeoSettings | null>(null)
+  const [targets, setTargets] = useState<SeoTarget[]>([])
+
+  useEffect(() => {
+    const controller = new AbortController()
+    setLoading(true)
+    fetchSeoTargets(controller.signal)
+      .then((payload) => {
+        setSiteName(payload.siteName)
+        setLanguage(payload.language)
+        setPublicOrigin(payload.publicOrigin)
+        setSiteSeo(payload.siteSeo)
+        setTargets(payload.targets)
+        setError(null)
+      })
+      .catch((err: unknown) => {
+        if (isAbortError(err)) return
+        console.error('[seo-page] targets load failed:', err)
+        setError(getErrorMessage(err, 'Could not load SEO targets'))
+      })
+      .finally(() => {
+        if (!controller.signal.aborted) setLoading(false)
+      })
+    return () => controller.abort()
+  }, [])
+
+  async function saveTarget(kind: SeoTargetKind, id: string, seo: SeoMetadata): Promise<void> {
+    const updated = await saveSeoTarget(kind, id, seo)
+    setTargets((current) => current.map((target) => (target.id === id ? updated : target)))
+  }
+
+  async function saveSite(seo: SiteSeoSettings): Promise<void> {
+    const saved = await saveSiteSeo(seo)
+    setSiteSeo(saved)
+  }
+
+  return {
+    loading,
+    error,
+    siteName,
+    language,
+    publicOrigin,
+    siteSeo,
+    targets,
+    resolveContext: { siteName, language, publicOrigin, siteSeo, targets },
+    saveTarget,
+    saveSite,
+  }
+}
diff --git a/src/admin/pages/seo/lib/resolveTargetSeo.ts b/src/admin/pages/seo/lib/resolveTargetSeo.ts
new file mode 100644
index 000000000..cd5b1612f
--- /dev/null
+++ b/src/admin/pages/seo/lib/resolveTargetSeo.ts
@@ -0,0 +1,82 @@
+/**
+ * Admin-side SEO resolution helpers — bridge the workspace's target list to
+ * the shared `@core/seo` resolver so previews, placeholders, and health
+ * indicators show EXACTLY what the publisher will emit.
+ *
+ * Token interpolation: the publisher interpolates `{source.field}` patterns
+ * against the live render context. The admin preview approximates the same
+ * result with the values it has (page title, site name) — enough for the
+ * editor to see "Hello World — Acme" instead of raw pattern syntax.
+ */
+import {
+  resolveSeoMetadata,
+  type ResolvedSeoMetadata,
+  type SeoMetadata,
+  type SiteSeoSettings,
+} from '@core/seo'
+import type { SeoTarget } from './seoApi'
+
+/**
+ * Preview-grade token interpolation. Replaces the tokens the SEO title
+ * patterns commonly use with the values the workspace knows; unknown tokens
+ * collapse to empty string — same forgiving behaviour as the real engine.
+ */
+export function previewInterpolate(
+  pattern: string,
+  values: { pageTitle: string; siteName: string },
+): string {
+  return pattern
+    .replaceAll('{page.title}', values.pageTitle)
+    .replaceAll('{currentEntry.title}', values.pageTitle)
+    .replaceAll('{site.name}', values.siteName)
+    .replace(/\{[a-zA-Z0-9_.]+\}/g, '')
+    .replace(/\s{2,}/g, ' ')
+    .trim()
+}
+
+export interface ResolveTargetSeoContext {
+  siteName: string
+  language: string | null
+  publicOrigin: string | null
+  siteSeo: SiteSeoSettings | null
+  /** All targets — used to find a post's entry template for its patterns. */
+  targets: SeoTarget[]
+}
+
+/** The entry template whose target list covers this post's table. */
+export function templateForPost(target: SeoTarget, targets: SeoTarget[]): SeoTarget | undefined {
+  if (target.kind !== 'post' || !target.tableSlug) return undefined
+  return targets.find(
+    (candidate) =>
+      candidate.kind === 'template' &&
+      (candidate.templateTableSlugs ?? []).includes(target.tableSlug!),
+  )
+}
+
+/**
+ * Resolve the final metadata for a target with a draft SEO object overlayed
+ * (the editor passes its in-progress draft; the index passes the stored
+ * value). Same fallback engine as the publisher.
+ */
+export function resolveTargetSeo(
+  target: SeoTarget,
+  draft: SeoMetadata | undefined,
+  ctx: ResolveTargetSeoContext,
+): ResolvedSeoMetadata {
+  const template = templateForPost(target, ctx.targets)
+  return resolveSeoMetadata({
+    target: draft ?? target.seo ?? undefined,
+    templateSeo: template?.seo ?? undefined,
+    siteSeo: ctx.siteSeo ?? undefined,
+    siteName: ctx.siteName,
+    baseTitle: target.title,
+    routeKind: target.kind === 'post' ? 'row' : 'page',
+    routePath: target.route ?? '/',
+    origin: ctx.publicOrigin ?? undefined,
+    language: ctx.language ?? undefined,
+    publishedAt: target.publishedAt ?? undefined,
+    updatedAt: target.updatedAt,
+    interpolate: (pattern) =>
+      previewInterpolate(pattern, { pageTitle: target.title, siteName: ctx.siteName }),
+  })
+}
diff --git a/src/admin/pages/seo/lib/seoApi.ts b/src/admin/pages/seo/lib/seoApi.ts
new file mode 100644
index 000000000..b9214b95f
--- /dev/null
+++ b/src/admin/pages/seo/lib/seoApi.ts
@@ -0,0 +1,110 @@
+/**
+ * SEO workspace API client — typed wrappers over `/admin/api/cms/seo/*`.
+ *
+ * All responses validate against TypeBox schemas via `apiRequest`
+ * (`@core/http`); the SEO object shapes come straight from `@core/seo`, so
+ * the admin client, the server handler, and the publisher share one source
+ * of truth for the persisted shapes.
+ */
+import { Type, type Static } from '@core/utils/typeboxHelpers'
+import { apiRequest } from '@core/http'
+import { SeoMetadataSchema, SiteSeoSettingsSchema, type SeoMetadata, type SiteSeoSettings } from '@core/seo'
+
+export const SeoTargetKindSchema = Type.Union([
+  Type.Literal('page'),
+  Type.Literal('template'),
+  Type.Literal('post'),
+])
+
+export type SeoTargetKind = Static<typeof SeoTargetKindSchema>
+
+export const SeoTargetSchema = Type.Object({
+  kind: SeoTargetKindSchema,
+  id: Type.String(),
+  title: Type.String(),
+  route: Type.Union([Type.String(), Type.Null()]),
+  tableSlug: Type.Optional(Type.String()),
+  tableLabel: Type.Optional(Type.String()),
+  /** Templates only — the postType table slugs the template applies to. */
+  templateTableSlugs: Type.Optional(Type.Array(Type.String())),
+  seo: Type.Union([SeoMetadataSchema, Type.Null()]),
+  status: Type.String(),
+  updatedAt: Type.String(),
+  publishedAt: Type.Union([Type.String(), Type.Null()]),
+})
+
+export type SeoTarget = Static<typeof SeoTargetSchema>
+
+export const SeoTargetsResponseSchema = Type.Object({
+  siteName: Type.String(),
+  language: Type.Union([Type.String(), Type.Null()]),
+  publicOrigin: Type.Union([Type.String(), Type.Null()]),
+  siteSeo: Type.Union([SiteSeoSettingsSchema, Type.Null()]),
+  targets: Type.Array(SeoTargetSchema),
+})
+
+export type SeoTargetsResponse = Static<typeof SeoTargetsResponseSchema>
+
+const SeoTargetPutResponseSchema = Type.Object({
+  target: SeoTargetSchema,
+})
+
+const SiteSeoPutResponseSchema = Type.Object({
+  seo: Type.Union([SiteSeoSettingsSchema, Type.Null()]),
+})
+
+export async function fetchSeoTargets(signal?: AbortSignal): Promise<SeoTargetsResponse> {
+  return apiRequest('/admin/api/cms/seo/targets', {
+    schema: SeoTargetsResponseSchema,
+    signal,
+    fallbackMessage: 'Could not load SEO targets',
+  })
+}
+
+export async function saveSeoTarget(
+  kind: SeoTargetKind,
+  id: string,
+  seo: SeoMetadata,
+): Promise<SeoTarget> {
+  const result = await apiRequest(`/admin/api/cms/seo/targets/${kind}/${encodeURIComponent(id)}`, {
+    method: 'PUT',
+    body: { seo },
+    schema: SeoTargetPutResponseSchema,
+    fallbackMessage: 'Could not save SEO metadata',
+  })
+  return result.target
+}
+
+export async function saveSiteSeo(seo: SiteSeoSettings): Promise<SiteSeoSettings | null> {
+  const result = await apiRequest('/admin/api/cms/seo/site', {
+    method: 'PUT',
+    body: { seo },
+    schema: SiteSeoPutResponseSchema,
+    fallbackMessage: 'Could not save site SEO settings',
+  })
+  return result.seo
+}
+
+const SeoSuggestionsResponseSchema = Type.Object({
+  suggestions: Type.Array(Type.String()),
+})
+
+/**
+ * One-shot AI metadata suggestions for a target field — returns 3 options.
+ * `exclude` carries already-shown texts so "More options" regenerates fresh
+ * ones instead of repeating.
+ */
+export async function generateSeoSuggestions(
+  kind: SeoTargetKind,
+  id: string,
+  field: string,
+  exclude: string[],
+): Promise<string[]> {
+  const result = await apiRequest('/admin/api/cms/seo/generate', {
+    method: 'POST',
+    body: { kind, id, field, exclude },
+    schema: SeoSuggestionsResponseSchema,
+    fallbackMessage: 'Could not generate suggestions',
+  })
+  return result.suggestions
+}
diff --git a/src/admin/pages/seo/tabs/MetaTab.module.css b/src/admin/pages/seo/tabs/MetaTab.module.css
new file mode 100644
index 000000000..dbcac6422
--- /dev/null
+++ b/src/admin/pages/seo/tabs/MetaTab.module.css
@@ -0,0 +1,26 @@
+.columns {
+  display: grid;
+  grid-template-columns: minmax(0, 1fr) 360px;
+  gap: 16px;
+  align-items: start;
+}
+
+.editorColumn {
+  position: sticky;
+  top: 16px;
+  min-width: 0;
+}
+
+.indexColumn {
+  min-width: 0;
+}
+
+@media (max-width: 960px) {
+  .columns {
+    grid-template-columns: 1fr;
+  }
+
+  .editorColumn {
+    position: static;
+  }
+}
diff --git a/src/admin/pages/seo/tabs/MetaTab.tsx b/src/admin/pages/seo/tabs/MetaTab.tsx
new file mode 100644
index 000000000..596ec5a17
--- /dev/null
+++ b/src/admin/pages/seo/tabs/MetaTab.tsx
@@ -0,0 +1,110 @@
+/**
+ * MetaTab — the SEO workspace's editing surface.
+ *
+ * Two persistent columns:
+ *   - Left: sticky preview editor. Platform switcher (Search / Open Graph /
+ *     X / Schema), editable snippet fields with inherited-value placeholders
+ *     and pixel length meters. The pinned "Site defaults" target renders the
+ *     site-level editor instead (patterns, default images, organization).
+ *   - Right: target index — search, kind filters, issues summary chips,
+ *     dense rows with per-field health dots, full keyboard navigation.
+ *
+ * Dirty guard: switching targets with unsaved changes asks through an
+ * in-app dialog (never `confirm()`); nothing is silently discarded.
+ */
+import { useState } from 'react'
+import { Button } from '@ui/components/Button'
+import { Dialog } from '@ui/components/Dialog'
+import type { SeoTarget } from '../lib/seoApi'
+import type { SeoWorkspace } from '../hooks/useSeoWorkspace'
+import { SeoTargetIndex } from '../components/SeoTargetIndex'
+import { SeoPreviewEditor } from '../components/SeoPreviewEditor'
+import { SiteDefaultsEditor } from '../components/SiteDefaultsEditor'
+import styles from './MetaTab.module.css'
+
+/** Selection id for the pinned site-defaults pseudo-target. */
+export const SITE_DEFAULTS_ID = 'site:defaults'
+
+interface MetaTabProps {
+  workspace: SeoWorkspace
+  canManage: boolean
+}
+
+export function MetaTab({ workspace, canManage }: MetaTabProps) {
+  const [selectedId, setSelectedId] = useState<string>(SITE_DEFAULTS_ID)
+  const [editorDirty, setEditorDirty] = useState(false)
+  const [pendingSelection, setPendingSelection] = useState<string | null>(null)
+
+  const selectedTarget: SeoTarget | null =
+    selectedId === SITE_DEFAULTS_ID
+      ? null
+      : workspace.targets.find((target) => target.id === selectedId) ?? null
+
+  function handleSelect(nextId: string): void {
+    if (nextId === selectedId) return
+    if (editorDirty) {
+      setPendingSelection(nextId)
+      return
+    }
+    setSelectedId(nextId)
+  }
+
+  function discardAndSwitch(): void {
+    if (pendingSelection !== null) {
+      setSelectedId(pendingSelection)
+      setEditorDirty(false)
+      setPendingSelection(null)
+    }
+  }
+
+  return (
+    <div className={styles.columns}>
+      <div className={styles.editorColumn}>
+        {selectedTarget ? (
+          <SeoPreviewEditor
+            key={selectedTarget.id}
+            target={selectedTarget}
+            workspace={workspace}
+            canManage={canManage}
+            onDirtyChange={setEditorDirty}
+          />
+        ) : (
+          <SiteDefaultsEditor
+            key={SITE_DEFAULTS_ID}
+            workspace={workspace}
+            canManage={canManage}
+            onDirtyChange={setEditorDirty}
+          />
+        )}
+      </div>
+
+      <div className={styles.indexColumn}>
+        <SeoTargetIndex
+          workspace={workspace}
+          selectedId={selectedId}
+          siteDefaultsId={SITE_DEFAULTS_ID}
+          onSelect={handleSelect}
+        />
+      </div>
+
+      <Dialog
+        open={pendingSelection !== null}
+        onClose={() => setPendingSelection(null)}
+        title="Discard unsaved changes?"
+        tone="danger"
+        footer={
+          <>
+            <Button variant="secondary" size="sm" onClick={() => setPendingSelection(null)}>
+              Keep editing
+            </Button>
+            <Button variant="destructive" size="sm" onClick={discardAndSwitch} data-testid="seo-discard-switch">
+              Discard changes
+            </Button>
+          </>
+        }
+      >
+        <p>The selected target has unsaved SEO changes. Switching now will discard them.</p>
+      </Dialog>
+    </div>
+  )
+}
diff --git a/src/admin/pages/seo/tabs/RobotsTab.tsx b/src/admin/pages/seo/tabs/RobotsTab.tsx
new file mode 100644
index 000000000..856670150
--- /dev/null
+++ b/src/admin/pages/seo/tabs/RobotsTab.tsx
@@ -0,0 +1,144 @@
+/**
+ * RobotsTab — generated robots.txt controls + live preview.
+ *
+ * Three switches (indexing, AI training crawlers, AI answer crawlers) over
+ * a byte-identical preview of the served file — the preview calls the same
+ * `generateRobotsTxt` the server endpoint uses. Saving writes
+ * `site.settings.seo.robots`; output goes live with the publish lifecycle.
+ */
+import { useState } from 'react'
+import { Switch } from '@ui/components/Switch'
+import { Code } from '@ui/components/Code'
+import { getErrorMessage } from '@core/utils/errorMessage'
+import {
+  generateRobotsTxt,
+  AI_TRAINING_CRAWLERS,
+  AI_ANSWER_CRAWLERS,
+  type SeoRobotsSettings,
+} from '@core/seo'
+import { SaveControls } from '../components/SeoPreviewEditor'
+import type { SeoWorkspace } from '../hooks/useSeoWorkspace'
+import styles from './SettingsTabs.module.css'
+
+interface RobotsTabProps {
+  workspace: SeoWorkspace
+  canManage: boolean
+}
+
+export function RobotsTab({ workspace, canManage }: RobotsTabProps) {
+  const stored = workspace.siteSeo?.robots ?? {}
+  const [draft, setDraft] = useState<SeoRobotsSettings>(stored)
+  const [saveState, setSaveState] = useState<'idle' | 'saving' | 'saved' | 'error'>('idle')
+  const [saveError, setSaveError] = useState<string | null>(null)
+
+  const isDirty = JSON.stringify(draft) !== JSON.stringify(stored)
+
+  const preview = generateRobotsTxt({
+    robots: draft,
+    sitemapEnabled: workspace.siteSeo?.sitemap?.enabled !== false,
+    origin: workspace.publicOrigin ?? undefined,
+  })
+
+  function setFlag(flag: keyof SeoRobotsSettings, value: boolean): void {
+    setDraft((current) => ({ ...current, [flag]: value }))
+    if (saveState !== 'idle') setSaveState('idle')
+  }
+
+  async function handleSave(): Promise<void> {
+    setSaveState('saving')
+    setSaveError(null)
+    try {
+      await workspace.saveSite({ ...(workspace.siteSeo ?? {}), robots: draft })
+      setSaveState('saved')
+    } catch (err) {
+      console.error('[seo-page] robots save failed:', err)
+      setSaveState('error')
+      setSaveError(getErrorMessage(err, 'Could not save robots settings'))
+    }
+  }
+
+  return (
+    <section className={styles.tab} aria-label="Robots.txt settings">
+      <header className={styles.header}>
+        <div>
+          <h2 className={styles.heading}>Robots.txt</h2>
+          <p className={styles.subheading}>
+            Generated automatically and served at <code>/robots.txt</code>. Changes go live on the next publish.
+          </p>
+        </div>
+        <SaveControls dirty={isDirty} state={saveState} canManage={canManage} onSave={() => void handleSave()} />
+      </header>
+      {saveError && <p className={styles.error} role="alert">{saveError}</p>}
+      {!workspace.publicOrigin && (
+        <p className={styles.notice} role="status">
+          No public origin configured — set the <code>PUBLIC_ORIGINS</code> environment
+          variable so the sitemap link (and canonical URLs) use your real domain.
+        </p>
+      )}
+
+      <div className={styles.controls}>
+        <SettingSwitch
+          label="Allow search engine indexing"
+          description="Turning this off serves a global Disallow — the whole site disappears from search."
+          checked={draft.indexingEnabled !== false}
+          disabled={!canManage}
+          onChange={(value) => setFlag('indexingEnabled', value)}
+          testId="seo-robots-indexing"
+        />
+        <SettingSwitch
+          label="Allow AI training crawlers"
+          description={`Bots that ingest content for model training: ${AI_TRAINING_CRAWLERS.join(', ')}.`}
+          checked={draft.allowAiTrainingCrawlers !== false}
+          disabled={!canManage || draft.indexingEnabled === false}
+          onChange={(value) => setFlag('allowAiTrainingCrawlers', value)}
+          testId="seo-robots-ai-training"
+        />
+        <SettingSwitch
+          label="Allow AI search & answer crawlers"
+          description={`Bots that fetch content to ground live AI answers: ${AI_ANSWER_CRAWLERS.join(', ')}. Blocking these removes the site from AI search results.`}
+          checked={draft.allowAiAnswerCrawlers !== false}
+          disabled={!canManage || draft.indexingEnabled === false}
+          onChange={(value) => setFlag('allowAiAnswerCrawlers', value)}
+          testId="seo-robots-ai-answer"
+        />
+      </div>
+
+      <h3 className={styles.previewHeading}>Preview</h3>
+      <div data-testid="seo-robots-preview">
+        <Code className={styles.preview}>{preview}</Code>
+      </div>
+    </section>
+  )
+}
+
+export function SettingSwitch({
+  label,
+  description,
+  checked,
+  disabled,
+  onChange,
+  testId,
+}: {
+  label: string
+  description: string
+  checked: boolean
+  disabled: boolean
+  onChange: (value: boolean) => void
+  testId: string
+}) {
+  return (
+    <div className={styles.switchRow}>
+      <Switch
+        checked={checked}
+        onCheckedChange={onChange}
+        disabled={disabled}
+        aria-label={label}
+        data-testid={testId}
+      />
+      <div className={styles.switchText}>
+        <span className={styles.switchLabel}>{label}</span>
+        <span className={styles.switchDescription}>{description}</span>
+      </div>
+    </div>
+  )
+}
diff --git a/src/admin/pages/seo/tabs/SettingsTabs.module.css b/src/admin/pages/seo/tabs/SettingsTabs.module.css
new file mode 100644
index 000000000..c412c0668
--- /dev/null
+++ b/src/admin/pages/seo/tabs/SettingsTabs.module.css
@@ -0,0 +1,126 @@
+/* Shared layout for the Robots.txt and Sitemap settings tabs. */
+
+.tab {
+  display: flex;
+  flex-direction: column;
+  gap: 16px;
+  max-width: 720px;
+}
+
+.header {
+  display: flex;
+  align-items: flex-start;
+  justify-content: space-between;
+  gap: 12px;
+}
+
+.heading {
+  margin: 0;
+  font-size: 15px;
+  font-weight: 700;
+  color: var(--editor-text-bright);
+}
+
+.subheading {
+  margin: 4px 0 0;
+  font-size: 12px;
+  color: var(--editor-text-muted);
+}
+
+.error {
+  margin: 0;
+  font-size: 12px;
+  color: var(--editor-danger-text);
+}
+
+.notice {
+  margin: 0;
+  padding: 10px 12px;
+  border-radius: var(--editor-radius);
+  background: var(--editor-surface-3);
+  font-size: 12px;
+  color: var(--editor-warning-text);
+}
+
+.controls {
+  display: flex;
+  flex-direction: column;
+  gap: 12px;
+}
+
+.switchRow {
+  display: flex;
+  align-items: flex-start;
+  gap: 10px;
+}
+
+.switchText {
+  display: flex;
+  flex-direction: column;
+  gap: 2px;
+}
+
+.switchLabel {
+  font-size: 12px;
+  font-weight: 600;
+  color: var(--editor-text-bright);
+}
+
+.switchDescription {
+  font-size: 11px;
+  color: var(--editor-text-muted);
+}
+
+.previewHeading {
+  margin: 8px 0 0;
+  font-size: 12px;
+  font-weight: 700;
+  color: var(--editor-text-bright);
+}
+
+.preview {
+  font-size: 11px;
+}
+
+.counts {
+  margin: 0;
+  font-size: 12px;
+  color: var(--editor-text);
+}
+
+.targetList {
+  display: flex;
+  flex-direction: column;
+  gap: 1px;
+  background: var(--editor-surface);
+  border-radius: 16px;
+  overflow: hidden;
+}
+
+.targetRow {
+  display: flex;
+  align-items: center;
+  gap: 10px;
+  padding: 8px 12px;
+  background: var(--editor-surface-2);
+}
+
+.targetTitle {
+  font-size: 12px;
+  font-weight: 600;
+  color: var(--editor-text-bright);
+}
+
+.targetRoute {
+  font-size: 11px;
+  color: var(--editor-text-muted);
+  flex: 1;
+  white-space: nowrap;
+  overflow: hidden;
+  text-overflow: ellipsis;
+}
+
+.targetNote {
+  font-size: 10px;
+  color: var(--editor-warning-text);
+}
diff --git a/src/admin/pages/seo/tabs/SitemapTab.tsx b/src/admin/pages/seo/tabs/SitemapTab.tsx
new file mode 100644
index 000000000..ecdc5d7db
--- /dev/null
+++ b/src/admin/pages/seo/tabs/SitemapTab.tsx
@@ -0,0 +1,153 @@
+/**
+ * SitemapTab — sitemap.xml generation settings.
+ *
+ * Enable/disable, inclusion counts (computed from the same target data the
+ * Meta tab uses), and per-target include/exclude switches for routable
+ * targets. Noindex targets are excluded automatically and shown as such —
+ * the control is disabled with the reason inline.
+ */
+import { useState } from 'react'
+import { Code } from '@ui/components/Code'
+import { Switch } from '@ui/components/Switch'
+import { getErrorMessage } from '@core/utils/errorMessage'
+import type { SeoSitemapSettings } from '@core/seo'
+import { SaveControls } from '../components/SeoPreviewEditor'
+import { SettingSwitch } from './RobotsTab'
+import type { SeoWorkspace } from '../hooks/useSeoWorkspace'
+import styles from './SettingsTabs.module.css'
+
+interface SitemapTabProps {
+  workspace: SeoWorkspace
+  canManage: boolean
+}
+
+export function SitemapTab({ workspace, canManage }: SitemapTabProps) {
+  const stored = workspace.siteSeo?.sitemap ?? {}
+  const [draft, setDraft] = useState<SeoSitemapSettings>(stored)
+  const [saveState, setSaveState] = useState<'idle' | 'saving' | 'saved' | 'error'>('idle')
+  const [saveError, setSaveError] = useState<string | null>(null)
+
+  const isDirty = JSON.stringify(draft) !== JSON.stringify(stored)
+  const enabled = draft.enabled !== false
+  const excluded = new Set(draft.excludedTargets ?? [])
+
+  // Routable targets only — templates have no public URL.
+  const routable = workspace.targets.filter((target) => target.route !== null)
+  const included = routable.filter((target) => {
+    if (target.seo?.noindex === true) return false
+    const key = `${target.kind === 'post' ? 'row' : 'page'}:${target.id}`
+    return !excluded.has(key)
+  })
+
+  function toggleTarget(kind: 'page' | 'row', id: string, include: boolean): void {
+    const key = `${kind}:${id}`
+    setDraft((current) => {
+      const set = new Set(current.excludedTargets ?? [])
+      if (include) set.delete(key)
+      else set.add(key)
+      const next = { ...current }
+      if (set.size === 0) delete next.excludedTargets
+      else next.excludedTargets = [...set].sort()
+      return next
+    })
+    if (saveState !== 'idle') setSaveState('idle')
+  }
+
+  async function handleSave(): Promise<void> {
+    setSaveState('saving')
+    setSaveError(null)
+    try {
+      await workspace.saveSite({ ...(workspace.siteSeo ?? {}), sitemap: draft })
+      setSaveState('saved')
+    } catch (err) {
+      console.error('[seo-page] sitemap save failed:', err)
+      setSaveState('error')
+      setSaveError(getErrorMessage(err, 'Could not save sitemap settings'))
+    }
+  }
+
+  return (
+    <section className={styles.tab} aria-label="Sitemap settings">
+      <header className={styles.header}>
+        <div>
+          <h2 className={styles.heading}>Sitemap</h2>
+          <p className={styles.subheading}>
+            Generated from published content and served at <code>/sitemap.xml</code>. Changes go live on the next publish.
+          </p>
+        </div>
+        <SaveControls dirty={isDirty} state={saveState} canManage={canManage} onSave={() => void handleSave()} />
+      </header>
+      {saveError && <p className={styles.error} role="alert">{saveError}</p>}
+      {!workspace.publicOrigin && (
+        <p className={styles.notice} role="status">
+          No public origin configured — set the <code>PUBLIC_ORIGINS</code> environment
+          variable so sitemap URLs use your real domain.
+        </p>
+      )}
+
+      <div className={styles.controls}>
+        <SettingSwitch
+          label="Generate sitemap.xml"
+          description="Search and answer engines use the sitemap to discover published pages and posts."
+          checked={enabled}
+          disabled={!canManage}
+          onChange={(value) => {
+            setDraft((current) => {
+              const next = { ...current }
+              if (value) delete next.enabled
+              else next.enabled = false
+              return next
+            })
+            if (saveState !== 'idle') setSaveState('idle')
+          }}
+          testId="seo-sitemap-enabled"
+        />
+      </div>
+
+      <p className={styles.counts} role="status" data-testid="seo-sitemap-counts">
+        {enabled
+          ? `${included.length} of ${routable.length} routable targets included.`
+          : 'Sitemap generation is disabled — /sitemap.xml returns 404.'}
+      </p>
+
+      {enabled && (
+        <div className={styles.targetList} aria-label="Sitemap inclusion">
+          {routable.map((target) => {
+            const kindKey = target.kind === 'post' ? 'row' as const : 'page' as const
+            const noindexed = target.seo?.noindex === true
+            const isIncluded = !noindexed && !excluded.has(`${kindKey}:${target.id}`)
+            return (
+              <div key={target.id} className={styles.targetRow}>
+                <Switch
+                  checked={isIncluded}
+                  disabled={!canManage || noindexed}
+                  onCheckedChange={(value) => toggleTarget(kindKey, target.id, value)}
+                  aria-label={`Include ${target.title} in the sitemap`}
+                  switchSize="sm"
+                />
+                <span className={styles.targetTitle}>{target.title}</span>
+                <span className={styles.targetRoute}>{target.route}</span>
+                {noindexed && (
+                  <span className={styles.targetNote}>noindex — excluded automatically</span>
+                )}
+              </div>
+            )
+          })}
+        </div>
+      )}
+
+      <h3 className={styles.previewHeading}>Entry format</h3>
+      <Code className={styles.preview}>{sampleEntry(workspace)}</Code>
+    </section>
+  )
+}
+
+function sampleEntry(workspace: SeoWorkspace): string {
+  const origin = workspace.publicOrigin ?? 'https://example.com'
+  return [
+    '<url>',
+    `  <loc>${origin}/posts/hello-world</loc>`,
+    '  <lastmod>2026-06-12T00:00:00.000Z</lastmod>',
+    '</url>',
+  ].join('\n')
+}
diff --git a/src/admin/pages/users/utils/capabilities.ts b/src/admin/pages/users/utils/capabilities.ts
index 60178f3db..eead7d0f8 100644
--- a/src/admin/pages/users/utils/capabilities.ts
+++ b/src/admin/pages/users/utils/capabilities.ts
@@ -182,6 +182,17 @@ export const CAPABILITY_META: Record<CoreCapability, CapabilityMeta> = {
     label: 'Read AI audit log',
     description: 'View site-wide AI usage, cost, and error events across all users.',
   },
+  // ---------------------------------------------------------------------
+  // SEO workspace
+  // ---------------------------------------------------------------------
+  'seo.read': {
+    label: 'View SEO',
+    description: 'Open the SEO workspace and read metadata, robots, and sitemap settings.',
+  },
+  'seo.manage': {
+    label: 'Manage SEO',
+    description: 'Edit page/post metadata, site SEO defaults, robots.txt, and sitemap settings.',
+  },
 }
 
 /**
@@ -242,6 +253,7 @@ export const CAPABILITY_GROUPS: CapabilityGroup[] = [
     title: 'AI',
     capabilities: ['ai.chat', 'ai.tools.write', 'ai.providers.manage', 'ai.audit.read'],
   },
+  { title: 'SEO', capabilities: ['seo.read', 'seo.manage'] },
   { title: 'Users & Roles', capabilities: ['users.manage', 'roles.manage'] },
   { title: 'Audit', capabilities: ['audit.read'] },
 ]
diff --git a/src/admin/router.tsx b/src/admin/router.tsx
index 9ae4cce0e..1ce2a68f9 100644
--- a/src/admin/router.tsx
+++ b/src/admin/router.tsx
@@ -61,6 +61,7 @@ export function AdminRoutes() {
       <Route path="/admin/plugins" element={withRouteBoundary(<AdminEntry section="plugins" />)} />
       <Route path="/admin/users" element={withRouteBoundary(<AdminEntry section="users" />)} />
       <Route path="/admin/ai" element={withRouteBoundary(<AdminEntry section="ai" />)} />
+      <Route path="/admin/tools/seo" element={withRouteBoundary(<AdminEntry section="seo" />)} />
       <Route path="/admin/account" element={withRouteBoundary(<AdminEntry section="account" />)} />
       <Route
         path="/admin/plugins/:pluginId/:pageId"
diff --git a/src/admin/shared/AdminSectionNavigation/AdminSectionNavigation.tsx b/src/admin/shared/AdminSectionNavigation/AdminSectionNavigation.tsx
index 56ea137de..5b8e07d9f 100644
--- a/src/admin/shared/AdminSectionNavigation/AdminSectionNavigation.tsx
+++ b/src/admin/shared/AdminSectionNavigation/AdminSectionNavigation.tsx
@@ -1,6 +1,11 @@
 /**
  * AdminSectionNavigation — the row of section links shown inside the
- * editor toolbar (Site · Content · Plugins · Users · …plugin pages).
+ * editor toolbar (Site · Content · Plugins · Users · Tools).
+ *
+ * Tools is a dropdown grouping first-party utility screens (SEO; future
+ * Redirects) together with plugin-provided admin pages — plugin pages keep
+ * their `/admin/plugins/:pluginId/:pageId` routes, only the navigation
+ * grouping changed.
  *
  * Lives next to the toolbar styles it consumes so both the heavy
  * AdminCanvasLayout (Site), AdminWorkspaceCanvasLayout (Content / Data /
@@ -8,7 +13,8 @@
  * plugin pages) can share it without one layout pulling another layout's
  * module graph in.
  */
-import { useEffect, useState, useSyncExternalStore, type MouseEvent, type ReactNode } from 'react'
+import { useEffect, useRef, useState, useSyncExternalStore, type MouseEvent, type ReactNode } from 'react'
+import { createPortal } from 'react-dom'
 import { ArticleSolidIcon } from 'pixel-art-icons/icons/article-solid'
 import { DashboardSolidIcon } from 'pixel-art-icons/icons/dashboard-solid'
 import { DatabaseSolidIcon } from 'pixel-art-icons/icons/database-solid'
@@ -16,6 +22,10 @@ import { ImagesSolidIcon } from 'pixel-art-icons/icons/images-solid'
 import { LayoutSolidIcon } from 'pixel-art-icons/icons/layout-solid'
 import { PackageSolidIcon } from 'pixel-art-icons/icons/package-solid'
 import { UsersSolidIcon } from 'pixel-art-icons/icons/users-solid'
+import { ToolCaseSolidIcon } from 'pixel-art-icons/icons/tool-case-solid'
+import { SearchSolidIcon } from 'pixel-art-icons/icons/search-solid'
+import { Button } from '@ui/components/Button'
+import { ContextMenu, ContextMenuItem, ContextMenuSeparator } from '@ui/components/ContextMenu'
 import { listCmsPlugins } from '@core/persistence/cmsPlugins'
 import type { CmsCurrentUser } from '@core/persistence'
 import type { PluginAdminPageRoute } from '@core/plugin-sdk'
@@ -185,16 +195,105 @@ export function AdminSectionNavigation({
           onNavigateStart={onWorkspaceNavigateStart}
         />
       )}
-      {canAccessPlugins && pluginPages.map((page) => (
-        <AdminRouteLink
-          key={`${page.pluginId}:${page.id}`}
-          to={page.route}
+      {(canAccess('seo') || (canAccessPlugins && pluginPages.length > 0)) && (
+        <ToolsNavDropdown
+          active={section === 'seo' || section === 'pluginPage'}
+          showSeo={canAccess('seo')}
+          pluginPages={canAccessPlugins ? pluginPages : []}
           onNavigateStart={onWorkspaceNavigateStart}
+        />
+      )}
+    </>
+  )
+}
+
+/**
+ * Tools dropdown — first-party utility screens (SEO) plus plugin admin
+ * pages, grouped by plugin when a plugin contributes more than one page.
+ * Uses the shared ContextMenu primitive anchored to the trigger button —
+ * same pattern as AccountMenuButton.
+ */
+function ToolsNavDropdown({
+  active,
+  showSeo,
+  pluginPages,
+  onNavigateStart,
+}: {
+  active: boolean
+  showSeo: boolean
+  pluginPages: PluginAdminPageRoute[]
+  onNavigateStart?: () => void
+}) {
+  const [open, setOpen] = useState(false)
+  const triggerRef = useRef<HTMLButtonElement>(null)
+  const navigate = useAdminNavigate()
+
+  function go(to: string): void {
+    setOpen(false)
+    onNavigateStart?.()
+    navigate(to)
+  }
+
+  // Group plugin pages by pluginId so multi-page plugins read as one block.
+  const pluginGroups = new Map<string, PluginAdminPageRoute[]>()
+  for (const page of pluginPages) {
+    const group = pluginGroups.get(page.pluginId)
+    if (group) group.push(page)
+    else pluginGroups.set(page.pluginId, [page])
+  }
+
+  return (
+    <>
+      <Button
+        ref={triggerRef}
+        variant="ghost"
+        size="xs"
+        type="button"
+        active={active || open}
+        aria-label="Tools menu"
+        aria-haspopup="menu"
+        aria-expanded={open}
+        className={toolbarStyles.adminLink}
+        data-testid="tools-nav-trigger"
+        onClick={() => setOpen((current) => !current)}
+      >
+        <ToolCaseSolidIcon size={NAV_ICON_SIZE} aria-hidden="true" />
+        <span>Tools</span>
+      </Button>
+      {open && typeof document !== 'undefined' && createPortal(
+        <ContextMenu
+          ariaLabel="Tools menu"
+          onClose={() => setOpen(false)}
+          anchorRef={triggerRef}
+          side="bottom"
+          align="start"
+          width={220}
+          zIndex={10000}
         >
-          <PackageSolidIcon size={NAV_ICON_SIZE} aria-hidden="true" />
-          <span>{page.navLabel ?? page.title}</span>
-        </AdminRouteLink>
-      ))}
+          {showSeo && (
+            <ContextMenuItem
+              onClick={() => go('/admin/tools/seo')}
+              data-testid="tools-nav-seo"
+            >
+              <SearchSolidIcon size={12} aria-hidden="true" />
+              <span>SEO</span>
+            </ContextMenuItem>
+          )}
+          {showSeo && pluginGroups.size > 0 && <ContextMenuSeparator />}
+          {[...pluginGroups.values()].map((pages) => (
+            pages.map((page) => (
+              <ContextMenuItem
+                key={`${page.pluginId}:${page.id}`}
+                onClick={() => go(page.route)}
+              >
+                <PackageSolidIcon size={12} aria-hidden="true" />
+                <span>{pages.length > 1 ? `${page.pluginName ?? page.pluginId}: ${page.navLabel ?? page.title}` : (page.navLabel ?? page.title)}</span>
+              </ContextMenuItem>
+            ))
+          ))}
+        </ContextMenu>,
+        document.body,
+      )}
     </>
   )
 }
diff --git a/src/admin/workspace.ts b/src/admin/workspace.ts
index c7eac3a03..5e62984c0 100644
--- a/src/admin/workspace.ts
+++ b/src/admin/workspace.ts
@@ -18,6 +18,10 @@
  * `'ai'` is the AI provider settings + defaults workspace. Gated by
  * `ai.providers.manage` (or `ai.audit.read` for the read-only audit tab).
  */
+/**
+ * `'seo'` is the SEO & AEO workspace under the Tools nav dropdown
+ * (`/admin/tools/seo`). Gated by `seo.read`.
+ */
 export type AdminWorkspace =
   | 'dashboard'
   | 'site'
@@ -27,5 +31,6 @@ export type AdminWorkspace =
   | 'plugins'
   | 'users'
   | 'ai'
+  | 'seo'
   | 'pluginPage'
   | 'account'
diff --git a/src/core/capabilities.ts b/src/core/capabilities.ts
index 81dbb8c38..f355270b1 100644
--- a/src/core/capabilities.ts
+++ b/src/core/capabilities.ts
@@ -65,6 +65,9 @@ export const CORE_CAPABILITIES = [
   'ai.tools.write',
   'ai.providers.manage',
   'ai.audit.read',
+  // SEO workspace — read the target index / edit metadata, robots, sitemap.
+  'seo.read',
+  'seo.manage',
 ] as const
 
 export type CoreCapability = typeof CORE_CAPABILITIES[number]
diff --git a/vendor/pixel-art-icons/dist/icons/tool-case-solid.d.ts b/vendor/pixel-art-icons/dist/icons/tool-case-solid.d.ts
new file mode 100644
index 000000000..fa34231dc
--- /dev/null
+++ b/vendor/pixel-art-icons/dist/icons/tool-case-solid.d.ts
@@ -0,0 +1,3 @@
+import React from 'react';
+import type { IconProps } from '../types';
+export declare function ToolCaseSolidIcon({ size, color, className, style }: IconProps): React.ReactElement;
diff --git a/vendor/pixel-art-icons/dist/icons/tool-case-solid.js b/vendor/pixel-art-icons/dist/icons/tool-case-solid.js
new file mode 100644
index 000000000..0c2abefd6
--- /dev/null
+++ b/vendor/pixel-art-icons/dist/icons/tool-case-solid.js
@@ -0,0 +1,4 @@
+import { jsx as _jsx } from "react/jsx-runtime";
+export function ToolCaseSolidIcon({ size = 24, color = 'currentColor', className, style }) {
+    return (_jsx("svg", { width: size, height: size, viewBox: "0 0 24 24", fill: color, xmlns: "http://www.w3.org/2000/svg", className: className, style: style, children: _jsx("path", { d: "M22 21h-2v2H4v-2H2v-8h20v8ZM9 17h6v-2H9v2Zm9-13h2v7h-4V8h-2v3H4V8h2V6h2V4h2v2h2V4h-2V2h8v2Zm-6 4h2V6h-2v2Z" }) }));
+}
diff --git a/vendor/pixel-art-icons/icons/tool-case-solid.tsx b/vendor/pixel-art-icons/icons/tool-case-solid.tsx
new file mode 100644
index 000000000..217bc57a1
--- /dev/null
+++ b/vendor/pixel-art-icons/icons/tool-case-solid.tsx
@@ -0,0 +1,18 @@
+import React from 'react';
+import type { IconProps } from '../types';
+
+export function ToolCaseSolidIcon({ size = 24, color = 'currentColor', className, style }: IconProps): React.ReactElement {
+  return (
+    <svg
+      width={size}
+      height={size}
+      viewBox="0 0 24 24"
+      fill={color}
+      xmlns="http://www.w3.org/2000/svg"
+      className={className}
+      style={style}
+    >
+      <path d="M22 21h-2v2H4v-2H2v-8h20v8ZM9 17h6v-2H9v2Zm9-13h2v7h-4V8h-2v3H4V8h2V6h2V4h2v2h2V4h-2V2h8v2Zm-6 4h2V6h-2v2Z"/>
+    </svg>
+  );
+}

From b47c8fcfd65e18f2045770aba5662e2fd60df0e7 Mon Sep 17 00:00:00 2001
From: DavidBabinec <hello@davidbabinec.com>
Date: Fri, 12 Jun 2026 13:24:43 +0200
Subject: [PATCH 05/26] feat(seo): AI metadata suggestions endpoint and sparkle
 bubbles

POST /admin/api/cms/seo/generate: one tool-less driver call through the
existing server/ai stack (content/site scope default picks the provider),
returns three suggestions parsed from a JSON-array response. Gated by
seo.manage + ai.chat. The editor's sparkle action renders suggestions as
tappable bubbles with More options (exclude-aware regenerate) and Reject.

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
---
 server/handlers/cms/seo.ts               |   2 +
 server/handlers/cms/seoGenerate.ts       | 214 +++++++++++++++++++++++
 src/__tests__/server/seoGenerate.test.ts | 107 ++++++++++++
 3 files changed, 323 insertions(+)
 create mode 100644 server/handlers/cms/seoGenerate.ts
 create mode 100644 src/__tests__/server/seoGenerate.test.ts

diff --git a/server/handlers/cms/seo.ts b/server/handlers/cms/seo.ts
index 347ecf01a..fa965a02d 100644
--- a/server/handlers/cms/seo.ts
+++ b/server/handlers/cms/seo.ts
@@ -31,6 +31,7 @@ import { getDataRow, listDataRows, saveDataRowDraft } from '../../repositories/d
 import { CMS_API_PREFIX } from './shared'
 import type { CmsHandlerOptions } from './shared'
 import { runRouteTable, type Route, type RouteParams } from './routeTable'
+import { handleSeoGenerate } from './seoGenerate'
 
 // ---------------------------------------------------------------------------
 // Body schemas
@@ -220,6 +221,7 @@ const SEO_ROUTES: readonly Route<[CmsHandlerOptions]>[] = [
     handler: handlePutTarget,
   },
   { method: 'PUT', pattern: `${CMS_API_PREFIX}/seo/site`, handler: handlePutSiteSeo },
+  { method: 'POST', pattern: `${CMS_API_PREFIX}/seo/generate`, handler: handleSeoGenerate },
 ]
 
 export async function handleSeoRoutes(
diff --git a/server/handlers/cms/seoGenerate.ts b/server/handlers/cms/seoGenerate.ts
new file mode 100644
index 000000000..00736627a
--- /dev/null
+++ b/server/handlers/cms/seoGenerate.ts
@@ -0,0 +1,214 @@
+/**
+ * AI metadata suggestions — `POST /admin/api/cms/seo/generate`.
+ *
+ * One driver call, three suggestions. Rides the existing `server/ai` stack:
+ * the scope default ('content', falling back to 'site') picks the provider
+ * credential + model; the call runs tool-less with a no-op bridge and the
+ * response text is parsed as a JSON string array.
+ *
+ * Capabilities: `seo.manage` (it feeds the SEO editor) plus `ai.chat`
+ * (it spends provider tokens). Length budgets ride the prompt so the
+ * suggestions fit the editor's meters without truncation.
+ */
+import { Type, type Static } from '@core/utils/typeboxHelpers'
+import { safeParseJson } from '@core/utils/jsonValidate'
+import { readBodyCell, readSeoCell, readTitleCell } from '@core/data/cells'
+import type { DbClient } from '../../db/client'
+import { badRequest, jsonResponse, readValidatedBody } from '../../http'
+import { requireCapability, userHasCapability } from '../../auth/authz'
+import { getDataRow } from '../../repositories/data'
+import { getDraftSite } from '../../repositories/site'
+import { readDefaultForScope } from '../../ai/defaults/store'
+import {
+  readCredentialForUser,
+  resolveCredentialForDriver,
+} from '../../ai/credentials/store'
+import { resolveDriver } from '../../ai/drivers'
+import type { AiBrowserBridge } from '../../ai/runtime/types'
+
+// ---------------------------------------------------------------------------
+// Request / response shapes
+// ---------------------------------------------------------------------------
+
+const GENERATABLE_FIELDS = [
+  'title',
+  'description',
+  'ogTitle',
+  'ogDescription',
+  'xTitle',
+  'xDescription',
+] as const
+
+const GenerateBodySchema = Type.Object({
+  kind: Type.Union([Type.Literal('page'), Type.Literal('template'), Type.Literal('post')]),
+  id: Type.String({ minLength: 1 }),
+  field: Type.Union(GENERATABLE_FIELDS.map((field) => Type.Literal(field))),
+  exclude: Type.Optional(Type.Array(Type.String())),
+})
+
+type GenerateBody = Static<typeof GenerateBodySchema>
+
+const SuggestionsSchema = Type.Array(Type.String(), { minItems: 1 })
+
+const SUGGESTION_COUNT = 3
+
+// ---------------------------------------------------------------------------
+// Prompt assembly
+// ---------------------------------------------------------------------------
+
+const FIELD_SPECS: Record<GenerateBody['field'], { label: string; budget: string }> = {
+  title: { label: 'SEO title', budget: 'at most 60 characters (~580px in search results)' },
+  description: { label: 'meta description', budget: 'at most 160 characters (~990px in search results)' },
+  ogTitle: { label: 'Open Graph title', budget: 'at most 60 characters' },
+  ogDescription: { label: 'Open Graph description', budget: 'at most 160 characters' },
+  xTitle: { label: 'X card title', budget: 'at most 60 characters' },
+  xDescription: { label: 'X card description', budget: 'at most 160 characters' },
+}
+
+const SYSTEM_PROMPT = [
+  'You are an expert SEO copywriter inside a CMS.',
+  `Respond with ONLY a JSON array of exactly ${SUGGESTION_COUNT} strings — no prose, no markdown fences, no keys.`,
+  'Each string is one complete suggestion. Vary the angle across suggestions (benefit-led, descriptive, curiosity).',
+  'Never stuff keywords; write for humans first. Match the language of the source content.',
+].join(' ')
+
+interface SuggestionContext {
+  field: GenerateBody['field']
+  pageTitle: string
+  bodyExcerpt: string
+  existingValue: string | undefined
+  siteName: string
+  siteDescription: string | undefined
+  exclude: string[]
+}
+
+function buildUserPrompt(ctx: SuggestionContext): string {
+  const spec = FIELD_SPECS[ctx.field]
+  const lines = [
+    `Write ${SUGGESTION_COUNT} ${spec.label} suggestions for the content below. Each must be ${spec.budget}.`,
+    '',
+    `Site: ${ctx.siteName}`,
+    ...(ctx.siteDescription ? [`Site description: ${ctx.siteDescription}`] : []),
+    `Content title: ${ctx.pageTitle}`,
+    ...(ctx.existingValue ? [`Current ${spec.label}: ${ctx.existingValue}`] : []),
+    ...(ctx.bodyExcerpt ? ['', 'Content excerpt:', ctx.bodyExcerpt] : []),
+  ]
+  if (ctx.exclude.length > 0) {
+    lines.push('', 'Do NOT repeat any of these already-shown suggestions:')
+    for (const item of ctx.exclude) lines.push(`- ${item}`)
+  }
+  return lines.join('\n')
+}
+
+// ---------------------------------------------------------------------------
+// Response parsing — tolerant of stray prose around the JSON array
+// ---------------------------------------------------------------------------
+
+export function parseSuggestionsText(text: string): string[] | null {
+  const start = text.indexOf('[')
+  const end = text.lastIndexOf(']')
+  if (start === -1 || end <= start) return null
+  const parsed = safeParseJson(text.slice(start, end + 1), SuggestionsSchema)
+  if (!parsed.ok) return null
+  const unique = [...new Set(parsed.value.map((item) => item.trim()).filter((item) => item !== ''))]
+  return unique.length > 0 ? unique.slice(0, SUGGESTION_COUNT) : null
+}
+
+// ---------------------------------------------------------------------------
+// Handler
+// ---------------------------------------------------------------------------
+
+/** Bridge for tool-less calls — never invoked because `tools` is empty. */
+const NOOP_BRIDGE: AiBrowserBridge = {
+  callBrowser: () => Promise.reject(new Error('seo/generate runs without tools')),
+}
+
+export async function handleSeoGenerate(req: Request, db: DbClient): Promise<Response> {
+  const user = await requireCapability(req, db, 'seo.manage')
+  if (user instanceof Response) return user
+  if (!userHasCapability(user, 'ai.chat')) {
+    return jsonResponse({ error: 'Forbidden' }, { status: 403 })
+  }
+
+  const body = await readValidatedBody(req, GenerateBodySchema)
+  if (!body) return badRequest('Invalid generate payload')
+
+  const row = await getDataRow(db, body.id)
+  if (!row) return jsonResponse({ error: 'Target not found' }, { status: 404 })
+
+  // Provider + model from the scope defaults — content first (SEO copy is
+  // content work), site as fallback. No default → actionable 409.
+  const aiDefault =
+    (await readDefaultForScope(db, 'content')) ?? (await readDefaultForScope(db, 'site'))
+  if (!aiDefault) {
+    return jsonResponse(
+      { error: 'No AI provider configured. Set a content or site default in the AI workspace.' },
+      { status: 409 },
+    )
+  }
+  const credential = await readCredentialForUser(db, user.id, aiDefault.credentialId)
+  if (!credential) {
+    return jsonResponse(
+      { error: 'The default AI credential is not accessible to your account. Configure one in the AI workspace.' },
+      { status: 409 },
+    )
+  }
+  let resolvedCredential
+  try {
+    resolvedCredential = await resolveCredentialForDriver(credential)
+  } catch (err) {
+    console.error('[seo-generate] credential resolution failed:', err)
+    return jsonResponse({ error: 'AI credential could not be resolved.' }, { status: 409 })
+  }
+
+  const site = await getDraftSite(db)
+  const prompt = buildUserPrompt({
+    field: body.field,
+    pageTitle: readTitleCell(row.cells) || row.slug,
+    bodyExcerpt: readBodyCell(row.cells).slice(0, 2000),
+    existingValue: readSeoCell(row.cells)?.[body.field],
+    siteName: site?.name ?? '',
+    siteDescription: site?.settings.seo?.description,
+    exclude: body.exclude ?? [],
+  })
+
+  const driver = resolveDriver(credential.providerId)
+  let text = ''
+  try {
+    const stream = driver.stream({
+      systemPrompt: [SYSTEM_PROMPT],
+      messages: [{ role: 'user', content: [{ kind: 'text', text: prompt }] }],
+      tools: [],
+      modelId: aiDefault.modelId,
+      modelCapabilities: driver.capabilities(aiDefault.modelId),
+      credentials: resolvedCredential,
+      signal: req.signal,
+      bridge: NOOP_BRIDGE,
+      toolContextBase: {
+        db,
+        userId: user.id,
+        scope: 'content',
+        conversationId: `seo-generate:${row.id}`,
+        snapshot: null,
+      },
+    })
+    for await (const event of stream) {
+      if (event.type === 'text') text += event.text
+      if (event.type === 'error') {
+        console.error('[seo-generate] driver error:', event.message)
+        return jsonResponse({ error: 'AI generation failed. Try again.' }, { status: 502 })
+      }
+    }
+  } catch (err) {
+    console.error('[seo-generate] driver call failed:', err)
+    return jsonResponse({ error: 'AI generation failed. Try again.' }, { status: 502 })
+  }
+
+  const suggestions = parseSuggestionsText(text)
+  if (!suggestions) {
+    console.error('[seo-generate] unparsable model output:', text.slice(0, 200))
+    return jsonResponse({ error: 'The model returned an unexpected format. Try again.' }, { status: 502 })
+  }
+
+  return jsonResponse({ suggestions })
+}
diff --git a/src/__tests__/server/seoGenerate.test.ts b/src/__tests__/server/seoGenerate.test.ts
new file mode 100644
index 000000000..48ff55280
--- /dev/null
+++ b/src/__tests__/server/seoGenerate.test.ts
@@ -0,0 +1,107 @@
+/**
+ * SEO AI-suggestion endpoint tests — POST /admin/api/cms/seo/generate.
+ *
+ * The driver call itself needs a live provider, so these tests cover the
+ * deterministic surface: capability gating (seo.manage + ai.chat), payload
+ * validation, the no-default 409, and the tolerant model-output parser.
+ */
+import { beforeAll, afterAll, describe, expect, it } from 'bun:test'
+import {
+  createCapabilityTestHarness,
+  expectForbidden,
+  readJson,
+  type CapabilityTestHarness,
+} from '../helpers/capabilityHarness'
+import { parseSuggestionsText } from '../../../server/handlers/cms/seoGenerate'
+
+let h: CapabilityTestHarness
+let owner: string
+let pageId: string
+
+beforeAll(async () => {
+  h = await createCapabilityTestHarness()
+  owner = await h.setupOwner()
+  const res = await h.cms('/admin/api/cms/seo/targets', { cookie: owner })
+  const body = await readJson<{ targets: { kind: string; id: string }[] }>(res)
+  pageId = body.targets.find((t) => t.kind === 'page')!.id
+})
+
+afterAll(async () => {
+  await h.cleanup()
+})
+
+describe('POST /admin/api/cms/seo/generate', () => {
+  it('rejects invalid payloads', async () => {
+    const res = await h.cms('/admin/api/cms/seo/generate', {
+      method: 'POST',
+      cookie: owner,
+      json: { kind: 'page', id: pageId, field: 'canonicalUrl' },
+    })
+    expect(res.status).toBe(400)
+  })
+
+  it('404s for unknown targets', async () => {
+    const res = await h.cms('/admin/api/cms/seo/generate', {
+      method: 'POST',
+      cookie: owner,
+      json: { kind: 'page', id: 'missing', field: 'title' },
+    })
+    expect(res.status).toBe(404)
+  })
+
+  it('409s with an actionable message when no AI default is configured', async () => {
+    const res = await h.cms('/admin/api/cms/seo/generate', {
+      method: 'POST',
+      cookie: owner,
+      json: { kind: 'page', id: pageId, field: 'title' },
+    })
+    expect(res.status).toBe(409)
+    const body = await readJson<{ error: string }>(res)
+    expect(body.error).toContain('No AI provider configured')
+  })
+
+  it('requires seo.manage AND ai.chat', async () => {
+    const noAi = await h.createRoleUser({
+      name: 'SEO no AI',
+      slug: 'seo-no-ai',
+      capabilities: ['seo.read', 'seo.manage'],
+    })
+    await expectForbidden(await h.cms('/admin/api/cms/seo/generate', {
+      method: 'POST',
+      cookie: noAi.cookie,
+      json: { kind: 'page', id: pageId, field: 'title' },
+    }))
+
+    const noSeo = await h.createRoleUser({
+      name: 'AI no SEO',
+      slug: 'ai-no-seo',
+      capabilities: ['ai.chat'],
+    })
+    await expectForbidden(await h.cms('/admin/api/cms/seo/generate', {
+      method: 'POST',
+      cookie: noSeo.cookie,
+      json: { kind: 'page', id: pageId, field: 'title' },
+    }))
+  })
+})
+
+describe('parseSuggestionsText', () => {
+  it('parses a clean JSON array', () => {
+    expect(parseSuggestionsText('["One", "Two", "Three"]')).toEqual(['One', 'Two', 'Three'])
+  })
+
+  it('extracts the array from surrounding prose and fences', () => {
+    const text = 'Here you go:\n```json\n["A", "B", "C"]\n```\nEnjoy!'
+    expect(parseSuggestionsText(text)).toEqual(['A', 'B', 'C'])
+  })
+
+  it('dedupes, trims, and caps at three', () => {
+    expect(parseSuggestionsText('[" A ", "A", "B", "C", "D"]')).toEqual(['A', 'B', 'C'])
+  })
+
+  it('returns null for garbage', () => {
+    expect(parseSuggestionsText('no array here')).toBeNull()
+    expect(parseSuggestionsText('[]')).toBeNull()
+    expect(parseSuggestionsText('[1, 2, 3]')).toBeNull()
+  })
+})

From 464be3c4fa50b4c117cdea0099ea9fa7f0a353f4 Mon Sep 17 00:00:00 2001
From: DavidBabinec <hello@davidbabinec.com>
Date: Fri, 12 Jun 2026 13:30:58 +0200
Subject: [PATCH 06/26] docs(seo): feature documentation and lint cleanup

New docs/features/seo.md covering the model, resolver, JSON-LD,
robots/sitemap endpoints, workspace UX, AI suggestions, and permissions.
Updated publisher/editor/content-storage/data-workspace/plugin-system/
site-shell/capabilities docs + the plugin template example for the
structured seo field. Lint: compiler-safe dirty-guard effects, redundant
setState removal, regex escape.

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
---
 docs/README.md                                |   1 +
 docs/editor.md                                |   4 +-
 docs/features/content-storage.md              |   9 +-
 docs/features/content-workspace.md            |   2 +-
 docs/features/data-workspace.md               |   2 +-
 docs/features/plugin-system.md                |   7 +-
 docs/features/publisher.md                    |  20 ++-
 docs/features/seo.md                          | 154 ++++++++++++++++++
 docs/features/site-shell.md                   |   3 +-
 docs/reference/capabilities.md                |  11 +-
 .../pages/seo/components/SeoTargetIndex.tsx   |   1 -
 .../seo/components/SiteDefaultsEditor.tsx     |   7 +-
 src/admin/pages/seo/hooks/useSeoDraft.ts      |   7 +-
 src/admin/pages/seo/hooks/useSeoWorkspace.ts  |   3 +-
 src/core/plugin-sdk/cli/init.ts               |   7 +-
 src/core/seo/__tests__/resolve.test.ts        |   2 -
 src/core/seo/lengthMeter.ts                   |   2 +-
 17 files changed, 203 insertions(+), 39 deletions(-)
 create mode 100644 docs/features/seo.md

diff --git a/docs/README.md b/docs/README.md
index 25ca21208..5d480d421 100644
--- a/docs/README.md
+++ b/docs/README.md
@@ -138,6 +138,7 @@ Three categories, three voices:
 |------------------------------------------------------------------|----------------------------------------------------------------------|
 | [features/plugin-system.md](features/plugin-system.md)           | The plugin system end-to-end: package shape, lifecycle, sandbox, SDK, permissions, CLI |
 | [features/publisher.md](features/publisher.md)                   | The page-tree-to-HTML/CSS renderer + server-side publishing wrappers |
+| [features/seo.md](features/seo.md)                                | SEO & AEO: metadata model, JSON-LD, robots/sitemap, the SEO workspace |
 | [features/visual-components.md](features/visual-components.md)   | VCs, slots, params, instantiation, recursion guard                   |
 | [features/content-storage.md](features/content-storage.md)       | `data_tables` + `data_rows` — the universal content store           |
 | [features/content-workspace.md](features/content-workspace.md)   | Content workspace UI: collections, entries, body editor, settings panel |
diff --git a/docs/editor.md b/docs/editor.md
index 60b3b7322..0008773be 100644
--- a/docs/editor.md
+++ b/docs/editor.md
@@ -240,7 +240,7 @@ src/admin/
 ### Cross-page primitives
 
 - **`SpotlightRoot`** — Cmd+K command palette. Owns its own command registry (`spotlight/commands/`), provider runner (`providers/`), scopes, keybindings, recents, telemetry. Available from every workspace.
-- **`AdminSectionNavigation`** — top-of-screen workspace switcher.
+- **`AdminSectionNavigation`** — top-of-screen workspace switcher. Ends with the **Tools** dropdown: first-party utility screens (SEO at `/admin/tools/seo`) plus plugin admin pages (their `/admin/plugins/:pluginId/:pageId` routes are unchanged — only the nav grouping moved).
 - **`AccountMenuButton`** — top-right avatar / account menu.
 - **`Panel`, `PanelHeader`, `SidebarResizeHandle`** — generic floating-panel chrome reused across the editor, content, and data workspaces.
 - **`StepUp`** — re-auth dialog gating sensitive actions.
@@ -582,7 +582,7 @@ The sidebar shell expands/collapses by animating `--*-panel-width`. The panel sl
 
 | Section       | What it contains                                                             |
 |---------------|------------------------------------------------------------------------------|
-| General       | Site name, meta title, meta description, language, favicon                   |
+| General       | Site name, language, favicon (site-wide SEO copy moved to `/admin/tools/seo`) |
 | Shortcuts     | Auto-rendered keyboard shortcut reference from the keybindings registry       |
 | Publishing    | Self-hosted runtime info + framework CSS tree-shaking toggle                 |
 | Preferences   | Catalog-driven editor preferences (auto-rendered from `PREFERENCE_CATALOG`)  |
diff --git a/docs/features/content-storage.md b/docs/features/content-storage.md
index 4dfd09447..d5fd7221d 100644
--- a/docs/features/content-storage.md
+++ b/docs/features/content-storage.md
@@ -80,7 +80,7 @@ Used to render the **currently-published** page (vs. the in-progress draft on th
 
 | `kind`       | Authored in                       | Built-in fields | Workflow | Notes                                          |
 |--------------|-----------------------------------|-----------------|----------|------------------------------------------------|
-| `postType`   | Content workspace (`/admin/content`) | `title`, `slug`, `body` (text), `featuredMedia`, `seoTitle`, `seoDescription` | `draft / published / unpublished / scheduled` + versions | Built-in fields cannot be renamed or deleted, only enabled / disabled. |
+| `postType`   | Content workspace (`/admin/content`) | `title`, `slug`, `body` (text), `featuredMedia`, `seo` (structured `SeoMetadata`) | `draft / published / unpublished / scheduled` + versions | Built-in fields cannot be renamed or deleted, only enabled / disabled. |
 | `data`       | Data workspace grid (`/admin/data`) | none           | none     | Pure user-defined fields. Like a database table.|
 | `page`       | Site workspace (`/admin/site`)    | `title`, `slug`, `body` (pageTree) | same as `postType` | Each row is a CMS page. `body` cell holds the `NodeTree<PageNode>`. |
 | `component`  | Site workspace, VC mode           | `name`, `tree` (pageTree), `params` (fieldSchema), `description` | none | Each row is a Visual Component. See [docs/features/visual-components.md](visual-components.md). |
@@ -252,7 +252,7 @@ The field appears in the postType's edit form and is queryable from loops.
 
 1. Open the Data workspace.
 2. Create a new `data_table` with `kind: 'postType'`.
-3. The system seeds the built-in fields (`title`, `slug`, `body`, `featuredMedia`, `seoTitle`, `seoDescription`) and a default entry template.
+3. The system seeds the built-in fields (`title`, `slug`, `body`, `featuredMedia`, `seo`) and a default entry template.
 4. Add custom fields as needed.
 5. Add posts via the Content workspace.
 
@@ -322,8 +322,9 @@ There's also one filter — `content.entry.cells` — that runs over the cell ba
 api.cms.hooks.filter('content.entry.cells', (cells, { tableSlug, entryId, actor }) => {
   if (tableSlug !== 'pages') return cells
   if (actor.kind === 'plugin' && actor.pluginId === api.plugin.id) return cells
-  if (!cells.metaDescription && typeof cells.body === 'string') {
-    return { ...cells, metaDescription: cells.body.slice(0, 160) }
+  const seo = (cells.seo ?? {}) as { description?: string }
+  if (!seo.description && typeof cells.body === 'string') {
+    return { ...cells, seo: { ...seo, description: cells.body.slice(0, 160) } }
   }
   return cells
 })
diff --git a/docs/features/content-workspace.md b/docs/features/content-workspace.md
index 4bbf5a00c..06d05a799 100644
--- a/docs/features/content-workspace.md
+++ b/docs/features/content-workspace.md
@@ -137,7 +137,7 @@ The mode switch is client-only. The markdown body is the source of truth in both
 | Hook | Source | Owns |
 |------|--------|------|
 | `useContentWorkspace` | `hooks/useContentWorkspace.ts` | Collection list, entry list, selection, CRUD operations, error state |
-| `useContentEntryDraft` | `hooks/useContentEntryDraft.ts` | In-memory field state (`title`, `body`, `slug`, `featuredMediaId`, `seoTitle`, `seoDescription`), save / publish / status-change handlers |
+| `useContentEntryDraft` | `hooks/useContentEntryDraft.ts` | In-memory field state (`title`, `body`, `slug`, `featuredMediaId`, `seoTitle`/`seoDescription` — merged into the structured `seo` cell on save), save / publish / status-change handlers |
 | `useContentMediaPicker` | `hooks/useContentMediaPicker.ts` | Media picker modal open/close, featured media asset hydration, body media insert |
 
 ---
diff --git a/docs/features/data-workspace.md b/docs/features/data-workspace.md
index b5fa3d270..218337441 100644
--- a/docs/features/data-workspace.md
+++ b/docs/features/data-workspace.md
@@ -89,7 +89,7 @@ Three tiers for postType tables, enforced by the guard functions:
 | Tier | Field IDs | Edit affordance | Delete affordance |
 |------|-----------|-----------------|-------------------|
 | Mandatory built-in | `title`, `slug` | None — locked row, no edit/delete buttons | Blocked |
-| Optional built-in | `body`, `featuredMedia`, `seoTitle`, `seoDescription` | Description + required only; label locked | Allowed |
+| Optional built-in | `body`, `featuredMedia`, `seo` | Description + required only; label locked | Allowed |
 | Custom | all others | Fully editable | Allowed if not the primary field |
 
 ```ts
diff --git a/docs/features/plugin-system.md b/docs/features/plugin-system.md
index 2e3d96aca..8c5220653 100644
--- a/docs/features/plugin-system.md
+++ b/docs/features/plugin-system.md
@@ -542,7 +542,7 @@ const pagesTable = await api.cms.content.tables.get('pages')
 const pages = api.cms.content.table('pages')
 const result = await pages.list({ status: 'published', limit: 50 })
 const entry = await pages.get(entryId)
-await pages.update(entryId, { cells: { seoTitle: 'New title' } })
+await pages.update(entryId, { cells: { seo: { title: 'New title' } } })
 await pages.publish(entryId)
 await pages.delete(entryId)
 
@@ -585,8 +585,9 @@ Filter that runs before persistence — validate, normalize, auto-fill:
 ```js
 api.cms.hooks.filter('content.entry.cells', (cells, { tableSlug, entryId, actor }) => {
   if (tableSlug !== 'pages') return cells
-  if (!cells.metaDescription && typeof cells.body === 'string') {
-    return { ...cells, metaDescription: cells.body.slice(0, 160) }
+  const seo = (cells.seo ?? {}) as { description?: string }
+  if (!seo.description && typeof cells.body === 'string') {
+    return { ...cells, seo: { ...seo, description: cells.body.slice(0, 160) } }
   }
   return cells
 })
diff --git a/docs/features/publisher.md b/docs/features/publisher.md
index 4e3368c82..d54853214 100644
--- a/docs/features/publisher.md
+++ b/docs/features/publisher.md
@@ -299,14 +299,18 @@ The publisher emits `<head>` in this order:
 
 1. `<meta charset="utf-8">`
 2. `<meta name="viewport" content="width=device-width, initial-scale=1">`
-3. `<title>` from `page.title`
-4. `<meta name="description">` if present in page settings
-5. `<link rel="icon">` if a favicon is configured
-6. `<script type="importmap">` mapping bare specifiers (e.g. `three`) to `/_instatic/runtime/cache/<hash>/...` URLs
-7. Runtime asset `<script>` tags (`scriptTagsForRuntimeAssets`)
-8. `<link rel="stylesheet" href="/_instatic/css/<bundle>-<hash>.css">` per bundle
-9. **`head` placement** plugin-injected tags (after the publisher's own head, before custom user head content)
-10. `<meta http-equiv="Content-Security-Policy" content="...">` — assembled based on what's actually in the page
+3. The resolved SEO block (`src/core/publisher/seoHead.ts`): `<title>`,
+   description, canonical, robots, Open Graph + X card tags, and one
+   `<script type="application/ld+json">` per JSON-LD entity. Values come from
+   the shared `@core/seo` resolver — the server pre-resolves page/row SEO
+   (incl. the configured public origin); previews/exports use `publishPage`'s
+   internal fallback. See [docs/features/seo.md](seo.md).
+4. `<link rel="icon">` if a favicon is configured
+5. `<script type="importmap">` mapping bare specifiers (e.g. `three`) to `/_instatic/runtime/cache/<hash>/...` URLs
+6. Runtime asset `<script>` tags (`scriptTagsForRuntimeAssets`)
+7. `<link rel="stylesheet" href="/_instatic/css/<bundle>-<hash>.css">` per bundle
+8. **`head` placement** plugin-injected tags (after the publisher's own head, before custom user head content)
+9. `<meta http-equiv="Content-Security-Policy" content="...">` — assembled based on what's actually in the page
 
 Installed fonts are emitted through the CSS bundle, not external `<link>` tags. The font CSS includes self-hosted `@font-face` rules for `site.settings.fonts.items` plus `:root` declarations for editable tokens such as `--font-primary`. A page rule can therefore keep `font-family: var(--font-primary)` while the token assignment changes site-wide.
 
diff --git a/docs/features/seo.md b/docs/features/seo.md
new file mode 100644
index 000000000..56623ba77
--- /dev/null
+++ b/docs/features/seo.md
@@ -0,0 +1,154 @@
+# SEO & AEO
+
+Search and answer-engine optimization is a core publishing capability:
+structured metadata per page/post, site-wide defaults with title patterns,
+Open Graph + X cards, schema.org JSON-LD, generated `robots.txt` with
+AI-crawler controls, `sitemap.xml`, and an admin workspace at
+`/admin/tools/seo` with AI-assisted copy suggestions.
+
+Spec history: `docs/superpowers/specs/2026-06-12-seo-workspace-design.md` (local).
+
+---
+
+## The model
+
+One engine module owns everything: **`src/core/seo/`** (barrel-gated).
+
+| File | Responsibility |
+| --- | --- |
+| `schema.ts` | `SeoMetadataSchema` (per-target object stored in `cells_json.seo`), `SiteSeoSettingsSchema` (`site.settings.seo`: title pattern, description, default social image, X handle/card, organization, robots, sitemap) |
+| `resolve.ts` | `resolveSeoMetadata` — the single fallback engine (see below) |
+| `jsonLd.ts` | `buildJsonLdEntities` (`WebSite`, `Organization`, `Article`, `BreadcrumbList`) + `serializeJsonLd` (escapes `</script`, `<!--`) |
+| `robots.ts` | `generateRobotsTxt` — shared by the server endpoint and the admin live preview (byte-identical) |
+| `aiCrawlers.ts` | The AI-crawler user-agent lists behind the Robots tab's two toggles |
+| `health.ts` | `computeSeoHealth` — the index dots / issue chips |
+| `lengthMeter.ts` | Approximate pixel-width metering (~580px title / ~990px description budgets) |
+
+### Storage
+
+- **Targets** (`page` + `postType` rows): one built-in `seoMetadata` field with
+  id `seo`; the structured object lives in `cells_json.seo`. Not offered as a
+  user-created custom field type; not bindable; not form-submittable.
+- **Site defaults**: `site.settings.seo` (replaced the legacy
+  `metaTitle`/`metaDescription` settings).
+- **Templates**: an entry template page row's `seo.title`/`seo.description`
+  act as token patterns for every matching post.
+
+### Resolution — two-stage title
+
+`resolveSeoMetadata` is shared by the publisher, the admin previews, and the
+health indicators — what the editor shows IS what gets emitted.
+
+```
+baseTitle  = target.seo.title ?? row/page title
+pattern    = template.seo.title ?? site.seo.titlePattern      // {source.field} tokens
+title      = explicit target title (pattern skipped)
+           | interpolate(pattern)                              // shared token engine
+           | baseTitle ?? site.name
+```
+
+Patterns use the existing `{source.field}` token engine
+(`src/core/templates/tokenInterpolation.ts`) — `{page.title}`, `{site.name}`,
+`{currentEntry.title}`. There is no second token grammar.
+
+Social fields fall back search → OG → X. `noindex` emits `noindex` only
+(never a silent `nofollow`).
+
+### Absolute URLs
+
+Canonical, `og:url`, sitemap `<loc>`, and origin-dependent JSON-LD use the
+configured public origin (`PUBLIC_ORIGINS` env → `canonicalPublicOrigin()` in
+`server/auth/security.ts`). Static HTML is baked at publish time, so with no
+origin configured those tags are **omitted** — never a guessed host. The
+dynamic `robots.txt`/`sitemap.xml` endpoints fall back to the request origin.
+
+## Published output
+
+`src/core/publisher/seoHead.ts` builds the head: title, description,
+canonical, robots, OG (incl. `og:locale`, `og:site_name`, `article:*_time`),
+X cards (`twitter:*` tag names), and one
+`<script type="application/ld+json">` per entity. The server resolves the
+payload per route in `server/publish/publicRenderer.ts` (page SEO from the
+snapshot, row SEO from the published version's cells + entry-template
+patterns); `publishPage` has an internal fallback so previews/exports run the
+same resolver.
+
+JSON-LD (zero-config in v1): `WebSite` + `Organization` on the homepage,
+`Article` on row routes, `BreadcrumbList` on routes deeper than one segment.
+Noindex targets emit none.
+
+## robots.txt and sitemap.xml
+
+`server/publish/seoEndpoints.ts`, dispatched by `server/router.ts` BEFORE
+static assets and public rendering. Both generate from the **published
+snapshot** and cache keyed by `publishVersion` — SEO follows the publish
+lifecycle (edit → publish → live).
+
+- `robots.txt` (`text/plain`): default allow + optional per-bot `Disallow`
+  blocks from the two AI-crawler toggles (training bots: GPTBot,
+  Google-Extended, CCBot, Applebot-Extended, meta-externalagent; answer bots:
+  OAI-SearchBot, PerplexityBot, ChatGPT-User, Claude-SearchBot), plus a
+  `Sitemap:` line.
+- `sitemap.xml` (`application/xml`): published routable pages + post rows,
+  excluding templates, `noindex` targets, and
+  `site.settings.seo.sitemap.excludedTargets`; `<lastmod>` from publish
+  timestamps. Disabled ⇒ 404.
+
+## Admin workspace — `/admin/tools/seo`
+
+`src/admin/pages/seo/`. Reached from the **Tools** nav dropdown
+(`AdminSectionNavigation`), which also hosts plugin admin pages (their
+`/admin/plugins/:pluginId/:pageId` routes are unchanged — only nav grouping
+moved).
+
+- **Meta tab** — right: target index (search, All/Pages/Posts/Templates/Issues
+  filters, issue summary chips, per-field health dots, ↑/↓/Enter + `/`
+  keyboard nav, pinned Site defaults row). Left: sticky preview editor with
+  Search / Open Graph / X / Schema platform views. Controlled
+  `Input`/`Textarea` primitives (no contentEditable); empty fields show their
+  RESOLVED fallback as placeholder; title/description carry pixel meters;
+  images pick from the media library; X fields hide behind "Customize X
+  preview" until set; switching targets while dirty asks via an in-app
+  dialog. The Schema view pretty-prints the exact JSON-LD the publisher will
+  emit.
+- **Robots.txt tab** — indexing + AI-crawler toggles over a live preview
+  generated by the same `generateRobotsTxt` the endpoint serves.
+- **Sitemap tab** — enable/disable, inclusion counts, per-target
+  include/exclude switches (noindex targets shown as auto-excluded).
+
+### AI suggestions
+
+The sparkle on title/description/OG/X inputs calls
+`POST /admin/api/cms/seo/generate` (`server/handlers/cms/seoGenerate.ts`):
+one tool-less driver call through the existing `server/ai` stack (provider +
+model from the `content`, falling back to `site`, scope default), returning
+three suggestions rendered as tappable bubbles with **More options**
+(exclude-aware regenerate) and **Reject**. Length budgets ride the prompt.
+Suggestions fill the input through the normal dirty/save flow — nothing
+auto-saves.
+
+## API and permissions
+
+`server/handlers/cms/seo.ts` — `/admin/api/cms/seo/*`:
+
+| Route | Capability | Notes |
+| --- | --- | --- |
+| `GET /seo/targets` | `seo.read` | Full target index + site SEO + configured origin (draft cells) |
+| `PUT /seo/targets/:kind/:id` | `seo.manage` + target ownership | `pages.edit` for page/template rows; `content.edit.any`/`content.manage` for post rows |
+| `PUT /seo/site` | `seo.manage` | Site defaults + robots + sitemap settings (one object) |
+| `POST /seo/generate` | `seo.manage` + `ai.chat` | AI suggestions |
+
+`seo.read` gates the workspace; `seo.manage` gates writes. Health indicators
+are computed client-side with the shared core resolver, so the index, the
+editor, and the published output agree by construction.
+
+## Tests
+
+- `src/core/seo/__tests__/` — resolver fallback chains, JSON-LD building +
+  escaping, robots generation, health.
+- `src/__tests__/publisher/render.test.ts` — emitted head tags.
+- `src/__tests__/server/seoEndpoints.test.ts` — robots/sitemap endpoints +
+  version caching.
+- `src/__tests__/server/seoHandler.test.ts` / `seoGenerate.test.ts` —
+  API + capability gates (real SQLite via the capability harness).
+- `src/__tests__/admin/seoWorkspace.test.tsx` — Meta/Robots tabs + Tools nav.
diff --git a/docs/features/site-shell.md b/docs/features/site-shell.md
index e1e15ea2c..cf4314203 100644
--- a/docs/features/site-shell.md
+++ b/docs/features/site-shell.md
@@ -121,12 +121,11 @@ CRUD actions on `classSlice`: `addCondition`, `updateCondition`, `removeConditio
 
 ```ts
 type SiteSettings = {
-  metaTitle?:       string
-  metaDescription?: string
   faviconUrl?:      string
   language?:        string
   framework?:       FrameworkSettings       // colors, typography, spacing, preferences — absent when disabled
   fonts?:           SiteFontsSettings       // installed font library + editable font tokens
+  seo?:             SiteSeoSettings         // site-wide SEO defaults — see docs/features/seo.md
   shortcuts:        Record<string, string>  // keyboard shortcut overrides
 }
 ```
diff --git a/docs/reference/capabilities.md b/docs/reference/capabilities.md
index 5ffb566ef..249f38606 100644
--- a/docs/reference/capabilities.md
+++ b/docs/reference/capabilities.md
@@ -8,7 +8,7 @@ For the broader auth flow (sessions, MFA, step-up), see [docs/features/auth-and-
 
 ## TL;DR
 
-- Defined as a `const` array in `src/core/capabilities.ts` (`@core/capabilities`); `CoreCapability` is derived via `typeof CORE_CAPABILITIES[number]`. **36 capabilities.**
+- Defined as a `const` array in `src/core/capabilities.ts` (`@core/capabilities`); `CoreCapability` is derived via `typeof CORE_CAPABILITIES[number]`. **38 capabilities.**
 - Handlers gate on capability, not on role: `requireCapability(req, db, 'site.read')`.
 - The **Owner AND Admin** roles get their capability lists force-resynced from `SYSTEM_ROLES` on every server boot. Hand-edits to either built-in role through the admin UI are restored at next boot — they are code-level decisions, not runtime ones.
 - Adding a capability: append the literal to `CORE_CAPABILITIES` in `src/core/capabilities.ts` (one place — server imports it), add it to the relevant `SYSTEM_ROLES` entries, wire `requireCapability(...)` at the gate point, and add picker meta + groups for the role-edit dialog. The two architecture tests (`capability-picker-coverage.test.ts`, `cms-handlers-capability-gated.test.ts`) catch missing pieces.
@@ -16,7 +16,7 @@ For the broader auth flow (sessions, MFA, step-up), see [docs/features/auth-and-
 
 ---
 
-## The 36 core capabilities
+## The 38 core capabilities
 
 ### Read
 
@@ -123,6 +123,13 @@ Was a single `ai.use`. Split so a Client persona can have chat assistance withou
 | `ai.providers.manage`  | Create / update / delete AI provider credentials + per-scope defaults | Owner, Admin |
 | `ai.audit.read`        | Read site-wide AI usage, cost, and error events across all users    | Owner, Admin |
 
+### SEO
+
+| Capability    | Grants                                                                | Roles        |
+|---------------|------------------------------------------------------------------------|--------------|
+| `seo.read`    | Open the SEO workspace (`/admin/tools/seo`); read metadata, robots, sitemap settings | Owner, Admin |
+| `seo.manage`  | Edit target metadata, site SEO defaults, robots.txt, sitemap settings. Target writes additionally require the owning persona (`pages.edit` / content edit). `POST /seo/generate` additionally requires `ai.chat`. | Owner, Admin |
+
 ---
 
 ## Roles
diff --git a/src/admin/pages/seo/components/SeoTargetIndex.tsx b/src/admin/pages/seo/components/SeoTargetIndex.tsx
index 8948707cc..b85078b76 100644
--- a/src/admin/pages/seo/components/SeoTargetIndex.tsx
+++ b/src/admin/pages/seo/components/SeoTargetIndex.tsx
@@ -123,7 +123,6 @@ export function SeoTargetIndex({ workspace, selectedId, siteDefaultsId, onSelect
         </div>
       )}
 
-      {/* eslint-disable-next-line jsx-a11y/no-noninteractive-element-interactions -- keyboard list navigation; rows themselves are buttons */}
       <div
         ref={listRef}
         className={styles.list}
diff --git a/src/admin/pages/seo/components/SiteDefaultsEditor.tsx b/src/admin/pages/seo/components/SiteDefaultsEditor.tsx
index 5f6ad8b2e..6552d62fb 100644
--- a/src/admin/pages/seo/components/SiteDefaultsEditor.tsx
+++ b/src/admin/pages/seo/components/SiteDefaultsEditor.tsx
@@ -65,12 +65,11 @@ export function SiteDefaultsEditor({ workspace, canManage, onDirtyChange }: Site
 
   const isDirty = !sameSiteSeo(draft, baseline)
 
-  // Exception #1 (React Compiler rules): parent dirty-guard consumes this
-  // through an effect so it tracks every dirtiness flip.
+  // Parent dirty-guard notification. `onDirtyChange` is a useState setter at
+  // every call site, so including it in the deps adds no extra firings.
   useEffect(() => {
     onDirtyChange(isDirty)
-    // eslint-disable-next-line react-hooks/exhaustive-deps -- notify only when dirtiness flips
-  }, [isDirty])
+  }, [isDirty, onDirtyChange])
 
   function setField(field: SiteStringField, value: string): void {
     setDraft((current) => {
diff --git a/src/admin/pages/seo/hooks/useSeoDraft.ts b/src/admin/pages/seo/hooks/useSeoDraft.ts
index 9c38a24de..85a2b07f8 100644
--- a/src/admin/pages/seo/hooks/useSeoDraft.ts
+++ b/src/admin/pages/seo/hooks/useSeoDraft.ts
@@ -82,12 +82,11 @@ export function useSeoDraft(
 
   const isDirty = !sameSeo(draft, baseline)
 
-  // Exception #1 (React Compiler rules): the parent's dirty-guard reads this
-  // via effect so it stays correct even when dirtiness changes from saves.
+  // Parent dirty-guard notification. `onDirtyChange` is a useState setter at
+  // every call site, so including it in the deps adds no extra firings.
   useEffect(() => {
     onDirtyChange(isDirty)
-    // eslint-disable-next-line react-hooks/exhaustive-deps -- notify only when dirtiness flips
-  }, [isDirty])
+  }, [isDirty, onDirtyChange])
 
   function update(mutate: (next: SeoMetadata) => void): void {
     setDraft((current) => {
diff --git a/src/admin/pages/seo/hooks/useSeoWorkspace.ts b/src/admin/pages/seo/hooks/useSeoWorkspace.ts
index b8bb239bb..cd2305a0c 100644
--- a/src/admin/pages/seo/hooks/useSeoWorkspace.ts
+++ b/src/admin/pages/seo/hooks/useSeoWorkspace.ts
@@ -44,8 +44,9 @@ export function useSeoWorkspace(): SeoWorkspace {
   const [targets, setTargets] = useState<SeoTarget[]>([])
 
   useEffect(() => {
+    // `loading` initialises true and this effect runs once on mount, so no
+    // synchronous setState is needed before the fetch resolves.
     const controller = new AbortController()
-    setLoading(true)
     fetchSeoTargets(controller.signal)
       .then((payload) => {
         setSiteName(payload.siteName)
diff --git a/src/core/plugin-sdk/cli/init.ts b/src/core/plugin-sdk/cli/init.ts
index 78f4056f8..ea9e79918 100644
--- a/src/core/plugin-sdk/cli/init.ts
+++ b/src/core/plugin-sdk/cli/init.ts
@@ -159,11 +159,12 @@ const mod: ServerPluginModule = {
       const entry = await api.cms.content.table('pages').get(entryId)
       if (!entry) return
 
-      // …react to the user's change here. Example: auto-fill a meta
+      // …react to the user's change here. Example: auto-fill the SEO
       // description from the page body if the user hasn't set one.
-      if (!entry.cells.metaDescription && typeof entry.cells.body === 'string') {
+      const seo = (entry.cells.seo ?? {}) as { description?: string }
+      if (!seo.description && typeof entry.cells.body === 'string') {
         await api.cms.content.table('pages').update(entryId, {
-          cells: { metaDescription: entry.cells.body.slice(0, 160) },
+          cells: { seo: { ...seo, description: entry.cells.body.slice(0, 160) } },
         })
       }
     })
diff --git a/src/core/seo/__tests__/resolve.test.ts b/src/core/seo/__tests__/resolve.test.ts
index 8f25c9635..5b3fc0b45 100644
--- a/src/core/seo/__tests__/resolve.test.ts
+++ b/src/core/seo/__tests__/resolve.test.ts
@@ -89,7 +89,6 @@ describe('resolveSeoMetadata — canonical / absolute URLs', () => {
     expect(
       resolveSeoMetadata({
         ...BASE,
-        // eslint-disable-next-line no-script-url
         target: { canonicalUrl: 'javascript:void(0)' },
         origin: 'https://acme.com',
       }).canonicalUrl,
@@ -162,7 +161,6 @@ describe('url helpers', () => {
   test('isSafeCanonicalUrl', () => {
     expect(isSafeCanonicalUrl('https://a.com/x')).toBe(true)
     expect(isSafeCanonicalUrl('http://a.com')).toBe(true)
-    // eslint-disable-next-line no-script-url
     expect(isSafeCanonicalUrl('javascript:void(0)')).toBe(false)
     expect(isSafeCanonicalUrl('/relative')).toBe(false)
   })
diff --git a/src/core/seo/lengthMeter.ts b/src/core/seo/lengthMeter.ts
index 2c553553c..f6e224f83 100644
--- a/src/core/seo/lengthMeter.ts
+++ b/src/core/seo/lengthMeter.ts
@@ -17,7 +17,7 @@ export const DESCRIPTION_PIXEL_BUDGET = 990
 export const TITLE_CHAR_GUIDE = 60
 export const DESCRIPTION_CHAR_GUIDE = 160
 
-const NARROW = /[iljtf.,:;'!|()\[\]{} ]/
+const NARROW = /[iljtf.,:;'!|()[\]{} ]/
 const WIDE = /[mwMW@%]/
 const UPPER = /[A-Z0-9]/
 

From 7fbbdee399dc7abf81be5a591d6999c5cd73a3c2 Mon Sep 17 00:00:00 2001
From: DavidBabinec <hello@davidbabinec.com>
Date: Fri, 12 Jun 2026 14:06:01 +0200
Subject: [PATCH 07/26] =?UTF-8?q?feat(seo):=20redesign=20Meta=20workbench?=
 =?UTF-8?q?=20=E2=80=94=20sticky=20preview=20rail,=20grouped=20index?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Complete Meta-tab redesign: a sticky left rail stacks the live 1:1
platform previews (Google SERP, Open Graph card, X card — real platform
dark-theme palettes via new --seo-* tokens — plus a collapsible JSON-LD
block), next to a sectioned metadata form (Search appearance / Social
card / X card) capped at sane widths. Site defaults preview the homepage
with the draft defaults applied live. Target index regrouped under
Pages/Templates/Posts headers with a pinned Site defaults card, mono
routes, and breathing room. Header tabs match the AiPage Button-row
pattern (§T.6); robots/sitemap/schema code surfaces render through a
read-only CodeMirror viewer (new readOnly mode on CodeMirrorEditor);
switches ride the FormField primitive.

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
---
 src/__tests__/admin/seoWorkspace.test.tsx     |  12 +-
 .../architecture/no-plugin-tab-shells.test.ts |   6 +-
 src/admin/pages/seo/SeoPage.tsx               |  95 +++---
 .../components/OpenGraphPreview.module.css    |  86 +++---
 .../pages/seo/components/OpenGraphPreview.tsx |  24 +-
 .../pages/seo/components/SchemaPreview.tsx    |  17 +-
 .../SearchSnippetPreview.module.css           | 113 +++++--
 .../seo/components/SearchSnippetPreview.tsx   |  37 ++-
 .../seo/components/SeoCodeViewer.module.css   |  11 +
 .../pages/seo/components/SeoCodeViewer.tsx    |  50 +++
 .../seo/components/SeoImageField.module.css   |  24 +-
 .../components/SeoPreviewEditor.module.css    | 163 +++++-----
 .../pages/seo/components/SeoPreviewEditor.tsx | 284 ++++++++----------
 .../seo/components/SeoPreviewRail.module.css  |  33 ++
 .../pages/seo/components/SeoPreviewRail.tsx   |  80 +++++
 .../seo/components/SeoTargetIndex.module.css  | 178 ++++++-----
 .../pages/seo/components/SeoTargetIndex.tsx   | 131 ++++----
 .../seo/components/SiteDefaultsEditor.tsx     |  88 ++++--
 .../seo/components/XCardPreview.module.css    | 147 ++++++---
 .../pages/seo/components/XCardPreview.tsx     |  62 ++--
 .../pages/seo/components/previewDomain.ts     |  28 ++
 src/admin/pages/seo/tabs/MetaTab.module.css   |  30 +-
 src/admin/pages/seo/tabs/MetaTab.tsx          |  28 +-
 src/admin/pages/seo/tabs/RobotsTab.tsx        |  99 +++---
 .../pages/seo/tabs/SettingsTabs.module.css    | 143 ++++-----
 src/admin/pages/seo/tabs/SitemapTab.tsx       |  39 +--
 .../site/code-editor/CodeMirrorEditor.tsx     |  19 +-
 src/styles/globals.css                        |  24 ++
 28 files changed, 1246 insertions(+), 805 deletions(-)
 create mode 100644 src/admin/pages/seo/components/SeoCodeViewer.module.css
 create mode 100644 src/admin/pages/seo/components/SeoCodeViewer.tsx
 create mode 100644 src/admin/pages/seo/components/SeoPreviewRail.module.css
 create mode 100644 src/admin/pages/seo/components/SeoPreviewRail.tsx
 create mode 100644 src/admin/pages/seo/components/previewDomain.ts

diff --git a/src/__tests__/admin/seoWorkspace.test.tsx b/src/__tests__/admin/seoWorkspace.test.tsx
index e1ba7b58a..865ee9cf0 100644
--- a/src/__tests__/admin/seoWorkspace.test.tsx
+++ b/src/__tests__/admin/seoWorkspace.test.tsx
@@ -227,8 +227,7 @@ describe('SEO Meta tab', () => {
     fireEvent.click(await screen.findByTestId('seo-target-page_about'))
     const editor = await screen.findByRole('region', { name: 'SEO for About' })
 
-    // Switch to the X platform view.
-    fireEvent.click(within(editor).getByRole('button', { name: 'X' }))
+    // The X section starts collapsed behind the customize gate.
     expect(within(editor).queryByLabelText('X title')).toBeNull()
 
     fireEvent.click(screen.getByTestId('seo-customize-x'))
@@ -259,12 +258,17 @@ describe('SEO Robots tab', () => {
     mockSeoFetch()
     renderWithSession(<RobotsHarness />)
 
+    // Newline-agnostic assertions: the preview renders through the lazy
+    // CodeMirror viewer when its chunk is already loaded (full-suite runs)
+    // and through the plain <Code> fallback otherwise — CM6's per-line DOM
+    // drops newlines from textContent.
     const preview = await screen.findByTestId('seo-robots-preview')
-    expect(preview.textContent).toContain('User-agent: *\nAllow: /')
+    expect(preview.textContent).toContain('User-agent: *')
+    expect(preview.textContent).toContain('Allow: /')
     expect(preview.textContent).not.toContain('GPTBot')
 
     fireEvent.click(screen.getByTestId('seo-robots-ai-training'))
-    expect(screen.getByTestId('seo-robots-preview').textContent).toContain('User-agent: GPTBot\nDisallow: /')
+    expect(screen.getByTestId('seo-robots-preview').textContent).toContain('User-agent: GPTBot')
   })
 })
 
diff --git a/src/__tests__/architecture/no-plugin-tab-shells.test.ts b/src/__tests__/architecture/no-plugin-tab-shells.test.ts
index 026866f00..f1480a376 100644
--- a/src/__tests__/architecture/no-plugin-tab-shells.test.ts
+++ b/src/__tests__/architecture/no-plugin-tab-shells.test.ts
@@ -74,7 +74,7 @@ function collectAllFiles(): string[] {
 /** §T.0 — every file under the Tabs primitive directory is allowed. */
 const TABS_PRIMITIVE_DIR = join(PROJECT_ROOT, 'src/ui/components/Tabs')
 
-/** §T.1–§T.5 — pre-existing custom tablist implementations. */
+/** §T.1–§T.6 — Button-row / compact tablist implementations. */
 const EXACT_ALLOWLIST = new Set<string>([
   // §T.1 — capability-gated Button row in UsersPage predates the Tabs primitive.
   join(PROJECT_ROOT, 'src/admin/pages/users/UsersPage.tsx'),
@@ -89,6 +89,10 @@ const EXACT_ALLOWLIST = new Set<string>([
   // pattern: icon-only, compact fixed layout that the full-width Tabs
   // style cannot represent.
   join(PROJECT_ROOT, 'src/admin/pages/content/components/ContentModeToggle/ContentModeToggle.tsx'),
+  // §T.6 — SeoPage matches the §T.1/§T.4 Button-row pattern so the SEO
+  // workspace's header tabs look identical to the sibling AI/Users/Account
+  // pages it sits next to in the admin nav.
+  join(PROJECT_ROOT, 'src/admin/pages/seo/SeoPage.tsx'),
 ])
 
 function isAllowlisted(file: string): boolean {
diff --git a/src/admin/pages/seo/SeoPage.tsx b/src/admin/pages/seo/SeoPage.tsx
index 69e591d47..7fd18f858 100644
--- a/src/admin/pages/seo/SeoPage.tsx
+++ b/src/admin/pages/seo/SeoPage.tsx
@@ -1,13 +1,13 @@
 /**
  * SeoPage — `/admin/tools/seo`.
  *
- * The SEO & AEO workspace: per-target metadata editing with live platform
- * previews (Meta tab), generated robots.txt with AI-crawler controls
- * (Robots.txt tab), and sitemap generation settings (Sitemap tab).
+ * The SEO & AEO workspace: per-target metadata editing with live 1:1
+ * platform previews (Meta tab), generated robots.txt with AI-crawler
+ * controls (Robots.txt tab), and sitemap generation settings (Sitemap tab).
  *
- * Tab chrome uses the shared `Tabs` compound primitive (ARIA tabs with
- * automatic activation); the page owns the active value and the shared
- * workspace data (one `GET /seo/targets` load).
+ * Tab chrome matches the sibling AI / Users / Account pages: the same
+ * capability-gated Button row passed through AdminPageLayout's `tabs` slot
+ * (§T.6 in `no-plugin-tab-shells.test.ts`).
  *
  * Capabilities: `seo.read` gates the workspace (enforced by
  * `canAccessWorkspace`); `seo.manage` gates every write — tabs receive
@@ -15,7 +15,7 @@
  */
 
 import { useState } from 'react'
-import { Tabs, TabList, Tab, TabPanel } from '@ui/components/Tabs'
+import { Button } from '@ui/components/Button'
 import { AdminPageLayout } from '@admin/layouts/AdminPageLayout'
 import { hasCapability } from '@admin/access'
 import { useCurrentAdminUser } from '@admin/sessionContext'
@@ -25,48 +25,61 @@ import { SitemapTab } from './tabs/SitemapTab'
 import { useSeoWorkspace } from './hooks/useSeoWorkspace'
 import styles from './SeoPage.module.css'
 
-type TabValue = 'meta' | 'robots' | 'sitemap'
+type Tab = 'meta' | 'robots' | 'sitemap'
+
+const TAB_LABELS: Record<Tab, string> = {
+  meta: 'Meta',
+  robots: 'Robots.txt',
+  sitemap: 'Sitemap',
+}
+
+const ALL_TABS: Tab[] = ['meta', 'robots', 'sitemap']
 
 export function SeoPage() {
   const currentUser = useCurrentAdminUser()
   const unrestricted = !currentUser
   const canManage = unrestricted || hasCapability(currentUser, 'seo.manage')
 
-  const [tab, setTab] = useState<TabValue>('meta')
+  const [tab, setTab] = useState<Tab>('meta')
   const workspace = useSeoWorkspace()
 
+  const tabs = (
+    <div role="tablist" aria-label="SEO sections" className={styles.tabsRow}>
+      {ALL_TABS.map((item) => (
+        <Button
+          key={item}
+          type="button"
+          variant={tab === item ? 'primary' : 'secondary'}
+          size="sm"
+          onClick={() => setTab(item)}
+          role="tab"
+          aria-selected={tab === item}
+          data-testid={`seo-tab-${item}`}
+        >
+          <span>{TAB_LABELS[item]}</span>
+        </Button>
+      ))}
+    </div>
+  )
+
   return (
-    <Tabs value={tab} onChange={setTab}>
-      <AdminPageLayout
-        workspace="seo"
-        title="SEO"
-        titleId="seo-title"
-        description="Search and answer-engine optimization: metadata, social cards, structured data, robots, and sitemap."
-        tabs={
-          <TabList ariaLabel="SEO sections">
-            <Tab value="meta">Meta</Tab>
-            <Tab value="robots">Robots.txt</Tab>
-            <Tab value="sitemap">Sitemap</Tab>
-          </TabList>
-        }
-        loading={workspace.loading}
-      >
-        {workspace.error ? (
-          <p className={styles.loadError} role="alert">{workspace.error}</p>
-        ) : (
-          <div className={styles.body}>
-            <TabPanel value="meta">
-              <MetaTab workspace={workspace} canManage={canManage} />
-            </TabPanel>
-            <TabPanel value="robots">
-              <RobotsTab workspace={workspace} canManage={canManage} />
-            </TabPanel>
-            <TabPanel value="sitemap">
-              <SitemapTab workspace={workspace} canManage={canManage} />
-            </TabPanel>
-          </div>
-        )}
-      </AdminPageLayout>
-    </Tabs>
+    <AdminPageLayout
+      workspace="seo"
+      title="SEO"
+      titleId="seo-title"
+      description="Search and answer-engine optimization: metadata, social cards, structured data, robots, and sitemap."
+      tabs={tabs}
+      loading={workspace.loading}
+    >
+      {workspace.error ? (
+        <p className={styles.loadError} role="alert">{workspace.error}</p>
+      ) : (
+        <div className={styles.body}>
+          {tab === 'meta' && <MetaTab workspace={workspace} canManage={canManage} />}
+          {tab === 'robots' && <RobotsTab workspace={workspace} canManage={canManage} />}
+          {tab === 'sitemap' && <SitemapTab workspace={workspace} canManage={canManage} />}
+        </div>
+      )}
+    </AdminPageLayout>
   )
 }
diff --git a/src/admin/pages/seo/components/OpenGraphPreview.module.css b/src/admin/pages/seo/components/OpenGraphPreview.module.css
index 7171e574b..b601faa46 100644
--- a/src/admin/pages/seo/components/OpenGraphPreview.module.css
+++ b/src/admin/pages/seo/components/OpenGraphPreview.module.css
@@ -1,54 +1,68 @@
+/* 1:1 Facebook dark-theme link card. */
+
 .card {
-  display: flex;
-  flex-direction: column;
-  margin: 0;
-  border-radius: var(--panel-radius);
-  overflow: hidden;
-  background: var(--editor-surface);
+    display: flex;
+    flex-direction: column;
+    margin: 0;
+    border-radius: var(--editor-radius);
+    overflow: hidden;
+    background: var(--seo-og-bg);
+    font-family: Helvetica, arial, sans-serif;
 }
 
 .image {
-  width: 100%;
-  aspect-ratio: 1.91 / 1;
-  object-fit: cover;
+    width: 100%;
+    aspect-ratio: 1.91 / 1;
+    object-fit: cover;
+    display: block;
 }
 
 .imagePlaceholder {
-  width: 100%;
-  aspect-ratio: 1.91 / 1;
-  display: flex;
-  align-items: center;
-  justify-content: center;
-  background: var(--editor-surface-3);
-  color: var(--editor-text-muted);
-  font-size: 12px;
+    width: 100%;
+    aspect-ratio: 1.91 / 1;
+    display: flex;
+    align-items: center;
+    justify-content: center;
+    background: var(--seo-og-placeholder);
+    color: var(--seo-og-domain);
+    font-size: 13px;
 }
 
-.meta {
-  display: flex;
-  flex-direction: column;
-  gap: 2px;
-  padding: 10px 14px;
+.strip {
+    display: flex;
+    flex-direction: column;
+    gap: 2px;
+    padding: 10px 12px;
+    background: var(--seo-og-strip);
 }
 
-.site {
-  font-size: 10px;
-  text-transform: uppercase;
-  letter-spacing: 0.04em;
-  color: var(--editor-text-muted);
+.domain {
+    color: var(--seo-og-domain);
+    font-size: 12px;
+    line-height: 16px;
+    text-transform: uppercase;
+    white-space: nowrap;
+    overflow: hidden;
+    text-overflow: ellipsis;
 }
 
 .title {
-  font-size: 13px;
-  font-weight: 700;
-  color: var(--editor-text-bright);
+    color: var(--seo-og-title);
+    font-size: 16px;
+    line-height: 20px;
+    font-weight: 600;
+    overflow: hidden;
+    display: -webkit-box;
+    -webkit-line-clamp: 2;
+    -webkit-box-orient: vertical;
 }
 
 .description {
-  font-size: 12px;
-  color: var(--editor-text);
-  display: -webkit-box;
-  -webkit-line-clamp: 2;
-  -webkit-box-orient: vertical;
-  overflow: hidden;
+    color: var(--seo-og-text);
+    font-size: 14px;
+    line-height: 18px;
+    overflow: hidden;
+    display: -webkit-box;
+    -webkit-line-clamp: 1;
+    -webkit-box-orient: vertical;
 }
diff --git a/src/admin/pages/seo/components/OpenGraphPreview.tsx b/src/admin/pages/seo/components/OpenGraphPreview.tsx
index c606516f8..7f81e7b5c 100644
--- a/src/admin/pages/seo/components/OpenGraphPreview.tsx
+++ b/src/admin/pages/seo/components/OpenGraphPreview.tsx
@@ -1,20 +1,30 @@
 /**
- * OpenGraphPreview — link-card mock (Facebook/LinkedIn-style) rendered from
- * resolved values: image area, site name, OG title + description.
+ * OpenGraphPreview — 1:1 mock of a Facebook dark-theme link card: the
+ * 1.91:1 image, then the grey meta strip with the uppercase domain, bold
+ * title, and one-line description. Colours live in the `--seo-og-*`
+ * palette (globals.css).
  */
 import type { ResolvedSeoMetadata } from '@core/seo'
 import styles from './OpenGraphPreview.module.css'
+import { previewDomain } from './previewDomain'
 
-export function OpenGraphPreview({ resolved, siteName }: { resolved: ResolvedSeoMetadata; siteName: string }) {
+interface OpenGraphPreviewProps {
+  resolved: ResolvedSeoMetadata
+  origin: string | null
+}
+
+export function OpenGraphPreview({ resolved, origin }: OpenGraphPreviewProps) {
   return (
-    <figure className={styles.card} aria-label="Open Graph preview">
+    <figure className={styles.card} aria-label="Open Graph link preview">
       {resolved.ogImage ? (
         <img className={styles.image} src={resolved.ogImage} alt={resolved.ogImageAlt ?? ''} />
       ) : (
-        <div className={styles.imagePlaceholder} aria-hidden="true">No social image</div>
+        <div className={styles.imagePlaceholder} aria-hidden="true">
+          <span>No social image</span>
+        </div>
       )}
-      <div className={styles.meta}>
-        <span className={styles.site}>{siteName}</span>
+      <div className={styles.strip}>
+        <span className={styles.domain}>{previewDomain(origin, resolved.canonicalUrl)}</span>
         <span className={styles.title}>{resolved.ogTitle}</span>
         {resolved.ogDescription && <span className={styles.description}>{resolved.ogDescription}</span>}
       </div>
diff --git a/src/admin/pages/seo/components/SchemaPreview.tsx b/src/admin/pages/seo/components/SchemaPreview.tsx
index cddf81044..24ee21355 100644
--- a/src/admin/pages/seo/components/SchemaPreview.tsx
+++ b/src/admin/pages/seo/components/SchemaPreview.tsx
@@ -1,12 +1,13 @@
 /**
- * SchemaPreview — read-only, pretty-printed JSON-LD exactly as the publisher
- * will emit it for the selected target (same `buildJsonLdEntities` call).
- * Makes the AEO output inspectable instead of invisible.
+ * SchemaPreview — read-only, syntax-highlighted JSON-LD exactly as the
+ * publisher will emit it for the selected target (same `buildJsonLdEntities`
+ * call). Rendered through the shared CodeMirror viewer so the AEO output is
+ * inspectable with real JSON highlighting.
  */
 import { buildJsonLdEntities, type ResolvedSeoMetadata } from '@core/seo'
-import { Code } from '@ui/components/Code'
 import type { SeoTarget } from '../lib/seoApi'
 import type { SeoWorkspace } from '../hooks/useSeoWorkspace'
+import { SeoCodeViewer } from './SeoCodeViewer'
 import styles from './SchemaPreview.module.css'
 
 export function SchemaPreview({
@@ -40,9 +41,11 @@ export function SchemaPreview({
 
   return (
     <div className={styles.schema} aria-label="JSON-LD structured data preview">
-      {entities.map((entity, index) => (
-        <Code key={index}>{JSON.stringify(entity, null, 2)}</Code>
-      ))}
+      <SeoCodeViewer
+        docKey={`schema:${target.id}`}
+        value={entities.map((entity) => JSON.stringify(entity, null, 2)).join('\n\n')}
+        language="json"
+      />
     </div>
   )
 }
diff --git a/src/admin/pages/seo/components/SearchSnippetPreview.module.css b/src/admin/pages/seo/components/SearchSnippetPreview.module.css
index 1b051d9b3..b0674eb25 100644
--- a/src/admin/pages/seo/components/SearchSnippetPreview.module.css
+++ b/src/admin/pages/seo/components/SearchSnippetPreview.module.css
@@ -1,42 +1,97 @@
-.snippet {
-  display: flex;
-  flex-direction: column;
-  gap: 2px;
-  margin: 0;
-  padding: 14px 16px;
-  border-radius: var(--panel-radius);
-  background: var(--editor-surface);
+/* 1:1 Google dark-theme desktop result. Fonts/sizes/colours mirror the
+ * real SERP (arial, 20px blue title, 14px grey snippet). */
+
+.serp {
+    display: flex;
+    flex-direction: column;
+    gap: 4px;
+    margin: 0;
+    padding: 18px 20px;
+    border-radius: var(--panel-radius);
+    background: var(--seo-serp-bg);
+    font-family: arial, sans-serif;
+}
+
+.head {
+    display: flex;
+    align-items: center;
+    gap: 12px;
+    margin-bottom: 4px;
+}
+
+.favicon {
+    display: flex;
+    align-items: center;
+    justify-content: center;
+    width: 28px;
+    height: 28px;
+    border-radius: 50%;
+    background: var(--seo-serp-chip);
+    color: var(--seo-serp-site);
+    font-size: 13px;
+    font-weight: 700;
+    flex-shrink: 0;
+}
+
+.headText {
+    display: flex;
+    flex-direction: column;
+    min-width: 0;
+}
+
+.site {
+    color: var(--seo-serp-site);
+    font-size: 14px;
+    line-height: 20px;
+    white-space: nowrap;
+    overflow: hidden;
+    text-overflow: ellipsis;
 }
 
 .url {
-  font-size: 11px;
-  color: var(--editor-text-muted);
-  white-space: nowrap;
-  overflow: hidden;
-  text-overflow: ellipsis;
+    color: var(--seo-serp-url);
+    font-size: 12px;
+    line-height: 18px;
+    white-space: nowrap;
+    overflow: hidden;
+    text-overflow: ellipsis;
 }
 
 .title {
-  font-size: 16px;
-  font-weight: 500;
-  color: var(--editor-info-text);
-  overflow-wrap: break-word;
+    color: var(--seo-serp-title);
+    font-size: 20px;
+    line-height: 26px;
+    font-weight: 400;
+    overflow: hidden;
+    display: -webkit-box;
+    -webkit-line-clamp: 1;
+    -webkit-box-orient: vertical;
+    cursor: pointer;
+}
+
+.title:hover {
+    text-decoration: underline;
 }
 
 .description {
-  font-size: 12px;
-  line-height: 1.5;
-  color: var(--editor-text);
+    color: var(--seo-serp-text);
+    font-size: 14px;
+    line-height: 22px;
+    overflow: hidden;
+    display: -webkit-box;
+    -webkit-line-clamp: 2;
+    -webkit-box-orient: vertical;
 }
 
 .noindexBadge {
-  align-self: flex-start;
-  margin-top: 6px;
-  font-size: 10px;
-  text-transform: uppercase;
-  letter-spacing: 0.04em;
-  padding: 2px 6px;
-  border-radius: var(--editor-radius-sm);
-  background: var(--editor-danger-bg);
-  color: var(--editor-danger-text);
+    align-self: flex-start;
+    margin-top: 8px;
+    font-family: var(--font-sans);
+    font-size: 10px;
+    text-transform: uppercase;
+    letter-spacing: 0.04em;
+    padding: 2px 6px;
+    border-radius: var(--editor-radius-sm);
+    background: var(--editor-danger-bg);
+    color: var(--editor-danger-text);
 }
diff --git a/src/admin/pages/seo/components/SearchSnippetPreview.tsx b/src/admin/pages/seo/components/SearchSnippetPreview.tsx
index 09e26e827..51492367f 100644
--- a/src/admin/pages/seo/components/SearchSnippetPreview.tsx
+++ b/src/admin/pages/seo/components/SearchSnippetPreview.tsx
@@ -1,20 +1,39 @@
 /**
- * SearchSnippetPreview — Google-style result snippet rendered from the
- * RESOLVED metadata, so what the user sees is what the publisher emits.
- * Pure display; editing happens in the controlled inputs below it.
+ * SearchSnippetPreview — 1:1 mock of a Google dark-theme desktop result.
+ *
+ * Layout mirrors the real SERP: favicon circle + site-name/breadcrumb
+ * header row, the blue 20px title, then the grey snippet. Values come from
+ * the RESOLVED metadata, so what's shown is exactly what the publisher
+ * emits. Colours live in the `--seo-serp-*` palette (globals.css) — the
+ * preview must look like Google, not like the editor.
  */
 import type { ResolvedSeoMetadata } from '@core/seo'
 import styles from './SearchSnippetPreview.module.css'
+import { serpBreadcrumb, serpSiteLabel } from './previewDomain'
 
-export function SearchSnippetPreview({ resolved }: { resolved: ResolvedSeoMetadata }) {
+interface SearchSnippetPreviewProps {
+  resolved: ResolvedSeoMetadata
+  siteName: string
+  origin: string | null
+  routePath: string
+}
+
+export function SearchSnippetPreview({ resolved, siteName, origin, routePath }: SearchSnippetPreviewProps) {
+  const siteLabel = serpSiteLabel(siteName, origin)
   return (
-    <figure className={styles.snippet} aria-label="Search result preview">
-      <span className={styles.url}>
-        {resolved.canonicalUrl ?? 'example.com — set PUBLIC_ORIGINS for absolute URLs'}
-      </span>
+    <figure className={styles.serp} aria-label="Google search result preview">
+      <div className={styles.head}>
+        <span className={styles.favicon} aria-hidden="true">
+          {siteLabel.slice(0, 1).toUpperCase()}
+        </span>
+        <span className={styles.headText}>
+          <span className={styles.site}>{siteLabel}</span>
+          <span className={styles.url}>{serpBreadcrumb(origin, routePath, resolved.canonicalUrl)}</span>
+        </span>
+      </div>
       <span className={styles.title}>{resolved.title}</span>
       <span className={styles.description}>
-        {resolved.description ?? 'Search engines will generate a description from page content.'}
+        {resolved.description ?? 'Google will generate a snippet from page content — add a description to control it.'}
       </span>
       {resolved.noindex && (
         <span className={styles.noindexBadge} role="status">noindex — hidden from search</span>
diff --git a/src/admin/pages/seo/components/SeoCodeViewer.module.css b/src/admin/pages/seo/components/SeoCodeViewer.module.css
new file mode 100644
index 000000000..44f305e91
--- /dev/null
+++ b/src/admin/pages/seo/components/SeoCodeViewer.module.css
@@ -0,0 +1,11 @@
+.viewer {
+    border-radius: var(--editor-radius);
+    overflow: hidden;
+    background: var(--editor-surface);
+    max-height: 420px;
+    overflow-y: auto;
+}
+
+.fallback {
+    font-size: 11px;
+}
diff --git a/src/admin/pages/seo/components/SeoCodeViewer.tsx b/src/admin/pages/seo/components/SeoCodeViewer.tsx
new file mode 100644
index 000000000..acd395c1c
--- /dev/null
+++ b/src/admin/pages/seo/components/SeoCodeViewer.tsx
@@ -0,0 +1,50 @@
+/**
+ * SeoCodeViewer — read-only, syntax-highlighted code display for the SEO
+ * workspace (robots.txt preview, sitemap entry sample, JSON-LD schema).
+ *
+ * Mounts the shared CodeMirror 6 editor in `readOnly` mode. CM6 is ~150 kB
+ * min+gz, so it stays behind React.lazy — the plain <Code> block renders as
+ * the Suspense fallback, which also keeps tests and first paint cheap.
+ */
+import { lazy, Suspense } from 'react'
+import { Code } from '@ui/components/Code'
+import type { CodeLanguage } from '@site/code-editor/CodeMirrorEditor'
+import styles from './SeoCodeViewer.module.css'
+
+const CodeMirrorEditor = lazy(() => import('@site/code-editor/CodeMirrorEditor'))
+
+interface SeoCodeViewerProps {
+  /** Stable identity — remounts the CM6 view when it changes. */
+  docKey: string
+  value: string
+  language: CodeLanguage
+  'data-testid'?: string
+}
+
+export function SeoCodeViewer({ docKey, value, language, 'data-testid': testId }: SeoCodeViewerProps) {
+  return (
+    <div className={styles.viewer} data-testid={testId}>
+      <Suspense fallback={<Code className={styles.fallback}>{value}</Code>}>
+        <CodeMirrorEditor
+          docKey={`${docKey}:${value.length}:${hashText(value)}`}
+          value={value}
+          language={language}
+          readOnly
+          changeDelayMs={0}
+        />
+      </Suspense>
+    </div>
+  )
+}
+
+/**
+ * Tiny content hash folded into the docKey so the read-only view remounts
+ * when the displayed text changes (CM6 only reads `value` on mount).
+ */
+function hashText(text: string): number {
+  let hash = 0
+  for (let i = 0; i < text.length; i += 1) {
+    hash = (hash * 31 + text.charCodeAt(i)) | 0
+  }
+  return hash
+}
diff --git a/src/admin/pages/seo/components/SeoImageField.module.css b/src/admin/pages/seo/components/SeoImageField.module.css
index 58384ebae..ed09d6025 100644
--- a/src/admin/pages/seo/components/SeoImageField.module.css
+++ b/src/admin/pages/seo/components/SeoImageField.module.css
@@ -1,24 +1,22 @@
 .field {
-  display: flex;
-  flex-direction: column;
-  gap: 4px;
+    display: flex;
+    flex-direction: column;
+    gap: 6px;
 }
 
 .label {
-  font-size: 11px;
-  font-weight: 600;
-  text-transform: uppercase;
-  letter-spacing: 0.04em;
-  color: var(--editor-text-muted);
+    font-size: 12px;
+    font-weight: 600;
+    color: var(--editor-text);
 }
 
 .controls {
-  display: flex;
-  align-items: center;
-  gap: 6px;
+    display: flex;
+    align-items: center;
+    gap: 6px;
 }
 
 .controls > :first-child {
-  flex: 1;
-  min-width: 0;
+    flex: 1;
+    min-width: 0;
 }
diff --git a/src/admin/pages/seo/components/SeoPreviewEditor.module.css b/src/admin/pages/seo/components/SeoPreviewEditor.module.css
index 276b5f56d..825f1b0ac 100644
--- a/src/admin/pages/seo/components/SeoPreviewEditor.module.css
+++ b/src/admin/pages/seo/components/SeoPreviewEditor.module.css
@@ -1,126 +1,129 @@
-.editor {
-  display: flex;
-  flex-direction: column;
-  gap: 14px;
-  background: var(--editor-surface-2);
-  border-radius: 16px;
-  padding: 16px;
+/* Workbench: sticky preview rail (left) + sectioned form (right). */
+.workbench {
+    display: grid;
+    grid-template-columns: minmax(320px, 400px) minmax(0, 1fr);
+    gap: 24px;
+    align-items: start;
+    min-width: 0;
+}
+
+@media (max-width: 1100px) {
+    .workbench {
+        grid-template-columns: 1fr;
+    }
+}
+
+.form {
+    display: flex;
+    flex-direction: column;
+    gap: 14px;
+    background: var(--editor-surface-2);
+    border-radius: 16px;
+    padding: 20px;
+    min-width: 0;
 }
 
 .header {
-  display: flex;
-  align-items: flex-start;
-  justify-content: space-between;
-  gap: 12px;
+    display: flex;
+    align-items: flex-start;
+    justify-content: space-between;
+    gap: 12px;
 }
 
 .headerText {
-  display: flex;
-  flex-direction: column;
-  gap: 2px;
-  min-width: 0;
+    display: flex;
+    flex-direction: column;
+    gap: 2px;
+    min-width: 0;
 }
 
 .headerTitle {
-  margin: 0;
-  font-size: 15px;
-  font-weight: 700;
-  color: var(--editor-text-bright);
-  white-space: nowrap;
-  overflow: hidden;
-  text-overflow: ellipsis;
+    margin: 0;
+    font-size: 16px;
+    font-weight: 700;
+    color: var(--editor-text-bright);
+    white-space: nowrap;
+    overflow: hidden;
+    text-overflow: ellipsis;
 }
 
 .headerRoute {
-  font-size: 11px;
-  color: var(--editor-text-muted);
+    font-size: 11px;
+    color: var(--editor-text-muted);
+    font-family: var(--font-mono);
 }
 
 .saveControls {
-  display: flex;
-  align-items: center;
-  gap: 8px;
-  flex-shrink: 0;
+    display: flex;
+    align-items: center;
+    gap: 10px;
+    flex-shrink: 0;
 }
 
 .saveStatus {
-  font-size: 11px;
-  color: var(--editor-text-muted);
+    font-size: 11px;
+    color: var(--editor-text-muted);
 }
 
 .error {
-  margin: 0;
-  font-size: 12px;
-  color: var(--editor-danger-text);
+    margin: 0;
+    font-size: 12px;
+    color: var(--editor-danger-text);
 }
 
 .readOnlyNote,
 .templateNote {
-  margin: 0;
-  font-size: 12px;
-  color: var(--editor-info-text);
+    margin: 0;
+    font-size: 12px;
+    color: var(--editor-info-text);
 }
 
-.platformBody {
-  display: flex;
-  flex-direction: column;
-  gap: 12px;
+.sectionHeading {
+    margin: 2px 0 0;
+    font-size: 13px;
+    font-weight: 700;
+    color: var(--editor-text-bright);
 }
 
+/* Field shell — mirrors the FormField primitive's stacked layout. The
+ * sparkle action rides the label row, which FormField's single label slot
+ * can't host, hence the local mirror instead of the wrapper. */
 .field {
-  display: flex;
-  flex-direction: column;
-  gap: 4px;
+    display: flex;
+    flex-direction: column;
+    gap: 6px;
 }
 
 .fieldLabelRow {
-  display: flex;
-  align-items: center;
-  justify-content: space-between;
-  gap: 8px;
+    display: flex;
+    align-items: center;
+    justify-content: space-between;
+    gap: 8px;
+    min-height: 20px;
 }
 
 .fieldLabel {
-  font-size: 11px;
-  font-weight: 600;
-  text-transform: uppercase;
-  letter-spacing: 0.04em;
-  color: var(--editor-text-muted);
+    font-size: 12px;
+    font-weight: 600;
+    color: var(--editor-text);
 }
 
 .fieldHint {
-  margin: 0;
-  font-size: 11px;
-  color: var(--editor-text-muted);
-}
-
-.switchRow {
-  display: flex;
-  align-items: center;
-  gap: 8px;
-}
-
-.switchLabel {
-  font-size: 12px;
-  color: var(--editor-text);
+    margin: 0;
+    font-size: 11px;
+    color: var(--editor-text-muted);
+    line-height: 1.4;
 }
 
 .customizeRow {
-  display: flex;
-  align-items: center;
-  justify-content: space-between;
-  gap: 12px;
+    display: flex;
+    align-items: center;
+    justify-content: space-between;
+    gap: 12px;
 }
 
 .customizeHint {
-  margin: 0;
-  font-size: 12px;
-  color: var(--editor-text-muted);
-}
-
-.sectionHeading {
-  margin: 8px 0 0;
-  font-size: 12px;
-  font-weight: 700;
-  color: var(--editor-text-bright);
+    margin: 0;
+    font-size: 12px;
+    color: var(--editor-text-muted);
 }
diff --git a/src/admin/pages/seo/components/SeoPreviewEditor.tsx b/src/admin/pages/seo/components/SeoPreviewEditor.tsx
index b4d1ef772..2f9a4d4be 100644
--- a/src/admin/pages/seo/components/SeoPreviewEditor.tsx
+++ b/src/admin/pages/seo/components/SeoPreviewEditor.tsx
@@ -1,44 +1,33 @@
 /**
- * SeoPreviewEditor — the Meta tab's left column for page / template / post
- * targets.
+ * SeoPreviewEditor — the Meta tab's workbench for one page / template / post
+ * target: a sticky rail of live 1:1 platform previews on the left (Google,
+ * Open Graph, X, collapsible JSON-LD) and the sectioned metadata form on the
+ * right. One draft, one resolver — every keystroke re-resolves and the rail
+ * re-renders, so what's previewed is exactly what the publisher will emit.
  *
- * Platform switcher (Search / Open Graph / X / Schema) over an editable
- * snippet: controlled Input/Textarea primitives styled as the platform
- * preview, never raw contentEditable. Every empty field shows its RESOLVED
- * fallback as placeholder text (the shared `@core/seo` resolver), so the
- * user always sees exactly what will be emitted. Title/description carry
- * live pixel meters. Save is quiet and local.
+ * Form sections: Search appearance → Social card (Open Graph) → X card
+ * (behind the customize gate while inheriting). Controlled Input/Textarea
+ * primitives only; empty fields show their resolved fallback as placeholder.
  */
 import { useId, useState } from 'react'
 import { Button } from '@ui/components/Button'
 import { Input, Textarea } from '@ui/components/Input'
 import { Select } from '@ui/components/Select'
 import { Switch } from '@ui/components/Switch'
-import { SegmentedControl } from '@ui/components/SegmentedControl'
+import { FormField } from '@ui/components/FormField'
+import { Separator } from '@ui/components/Separator'
 import { getErrorMessage } from '@core/utils/errorMessage'
 import { isSafeCanonicalUrl } from '@core/seo'
 import type { SeoTarget } from '../lib/seoApi'
 import { resolveTargetSeo, templateForPost } from '../lib/resolveTargetSeo'
 import type { SeoWorkspace } from '../hooks/useSeoWorkspace'
 import { useSeoDraft, normalizeSeoDraft, type SeoDraftField } from '../hooks/useSeoDraft'
-import { SearchSnippetPreview } from './SearchSnippetPreview'
-import { OpenGraphPreview } from './OpenGraphPreview'
-import { XCardPreview } from './XCardPreview'
-import { SchemaPreview } from './SchemaPreview'
+import { SeoPreviewRail } from './SeoPreviewRail'
 import { MetaLengthMeter } from './MetaLengthMeter'
 import { SeoImageField } from './SeoImageField'
 import { AiSuggestionSparkle } from './AiSuggestionBubbles'
 import styles from './SeoPreviewEditor.module.css'
 
-type Platform = 'search' | 'og' | 'x' | 'schema'
-
-const PLATFORM_OPTIONS: { value: Platform; label: string }[] = [
-  { value: 'search', label: 'Search' },
-  { value: 'og', label: 'Open Graph' },
-  { value: 'x', label: 'X' },
-  { value: 'schema', label: 'Schema' },
-]
-
 interface SeoPreviewEditorProps {
   target: SeoTarget
   workspace: SeoWorkspace
@@ -47,7 +36,6 @@ interface SeoPreviewEditorProps {
 }
 
 export function SeoPreviewEditor({ target, workspace, canManage, onDirtyChange }: SeoPreviewEditorProps) {
-  const [platform, setPlatform] = useState<Platform>('search')
   const draft = useSeoDraft(target.seo, onDirtyChange)
   const fieldIdBase = useId()
 
@@ -55,6 +43,7 @@ export function SeoPreviewEditor({ target, workspace, canManage, onDirtyChange }
   const template = templateForPost(target, workspace.targets)
   const canonicalValue = draft.draft.canonicalUrl ?? ''
   const canonicalInvalid = canonicalValue !== '' && !isSafeCanonicalUrl(canonicalValue)
+  const routePath = target.route ?? '/'
 
   async function handleSave(): Promise<void> {
     if (canonicalInvalid) {
@@ -147,149 +136,134 @@ export function SeoPreviewEditor({ target, workspace, canManage, onDirtyChange }
   }
 
   return (
-    <section className={styles.editor} aria-label={`SEO for ${target.title}`}>
-      <header className={styles.header}>
-        <div className={styles.headerText}>
-          <h2 className={styles.headerTitle}>{target.title}</h2>
-          <span className={styles.headerRoute}>
-            {target.route ?? (target.kind === 'template' ? `Entry template${target.tableSlug ? ` · ${target.tableSlug}` : ''}` : '')}
-          </span>
-        </div>
-        <SaveControls
-          dirty={draft.isDirty}
-          state={draft.saveState}
-          canManage={canManage}
-          onSave={() => void handleSave()}
-        />
-      </header>
-      {draft.saveError && <p className={styles.error} role="alert">{draft.saveError}</p>}
-      {!canManage && (
-        <p className={styles.readOnlyNote} role="status">
-          Read-only — your role does not include Manage SEO.
-        </p>
-      )}
-      {target.kind === 'template' && (
-        <p className={styles.templateNote} role="status">
-          Template defaults — title and description act as patterns
-          (<code>{'{currentEntry.title}'}</code>, <code>{'{site.name}'}</code>) for every matching post.
-        </p>
-      )}
-
-      <SegmentedControl
-        value={platform}
-        options={PLATFORM_OPTIONS}
-        onChange={setPlatform}
-        size="sm"
-        aria-label="Preview platform"
-        data-testid="seo-platform-switcher"
+    <div className={styles.workbench}>
+      <SeoPreviewRail
+        resolved={resolved}
+        workspace={workspace}
+        routePath={routePath}
+        schemaTarget={target}
       />
 
-      {platform === 'search' && (
-        <div className={styles.platformBody}>
-          <SearchSnippetPreview resolved={resolved} />
-          {field('title', 'Title', { meterBudget: 'title', sparkle: true })}
-          {field('description', 'Description', { textarea: true, meterBudget: 'description', sparkle: true })}
-          {field('canonicalUrl', 'Canonical URL', { invalid: canonicalInvalid })}
-          {canonicalInvalid && (
-            <p className={styles.error} role="alert">Canonical URL must be an absolute http(s) URL.</p>
-          )}
-          <div className={styles.switchRow}>
-            <Switch
-              checked={draft.draft.noindex === true}
-              onCheckedChange={draft.setNoindex}
-              disabled={!canManage}
-              aria-label="Exclude from search engines (noindex)"
-              switchSize="sm"
-            />
-            <span className={styles.switchLabel}>
-              Exclude from search engines (<code>noindex</code>)
+      <section className={styles.form} aria-label={`SEO for ${target.title}`}>
+        <header className={styles.header}>
+          <div className={styles.headerText}>
+            <h2 className={styles.headerTitle}>{target.title}</h2>
+            <span className={styles.headerRoute}>
+              {target.route ?? (target.kind === 'template' ? `Entry template${target.tableSlug ? ` · ${target.tableSlug}` : ''}` : '')}
             </span>
           </div>
-        </div>
-      )}
+          <SaveControls
+            dirty={draft.isDirty}
+            state={draft.saveState}
+            canManage={canManage}
+            onSave={() => void handleSave()}
+          />
+        </header>
+        {draft.saveError && <p className={styles.error} role="alert">{draft.saveError}</p>}
+        {!canManage && (
+          <p className={styles.readOnlyNote} role="status">
+            Read-only — your role does not include Manage SEO.
+          </p>
+        )}
+        {target.kind === 'template' && (
+          <p className={styles.templateNote} role="status">
+            Template defaults — title and description act as patterns
+            (<code>{'{currentEntry.title}'}</code>, <code>{'{site.name}'}</code>) for every matching post.
+          </p>
+        )}
+        {template && (
+          <p className={styles.templateNote} role="status">
+            Inherits patterns from the “{template.title}” entry template.
+          </p>
+        )}
 
-      {platform === 'og' && (
-        <div className={styles.platformBody}>
-          <OpenGraphPreview resolved={resolved} siteName={workspace.siteName} />
-          {field('ogTitle', 'OG title', { sparkle: true })}
-          {field('ogDescription', 'OG description', { textarea: true, sparkle: true })}
-          <SeoImageField
-            label="OG image"
-            value={draft.draft.ogImage ?? ''}
-            inheritedValue={resolved.ogImage ?? null}
+        <h3 className={styles.sectionHeading}>Search appearance</h3>
+        {field('title', 'Title', { meterBudget: 'title', sparkle: true })}
+        {field('description', 'Description', { textarea: true, meterBudget: 'description', sparkle: true })}
+        {field('canonicalUrl', 'Canonical URL', { invalid: canonicalInvalid })}
+        {canonicalInvalid && (
+          <p className={styles.error} role="alert">Canonical URL must be an absolute http(s) URL.</p>
+        )}
+        <FormField
+          layout="inline-end"
+          label="Exclude from search engines"
+          description="Emits noindex — the page disappears from search and answer engines."
+        >
+          <Switch
+            checked={draft.draft.noindex === true}
+            onCheckedChange={draft.setNoindex}
             disabled={!canManage}
-            onChange={(next) => draft.setField('ogImage', next)}
+            aria-label="Exclude from search engines (noindex)"
+            switchSize="sm"
           />
-          {field('ogImageAlt', 'OG image alt')}
-          <div className={styles.field}>
-            <label htmlFor={`${fieldIdBase}-ogType`} className={styles.fieldLabel}>OG type</label>
-            <Select
-              id={`${fieldIdBase}-ogType`}
-              value={draft.draft.ogType ?? ''}
-              disabled={!canManage}
-              onChange={(e) => draft.setOgType(e.target.value === '' ? undefined : (e.target.value as 'website' | 'article'))}
-            >
-              <option value="">Auto ({resolved.ogType})</option>
-              <option value="website">website</option>
-              <option value="article">article</option>
-            </Select>
-          </div>
-        </div>
-      )}
+        </FormField>
 
-      {platform === 'x' && (
-        <div className={styles.platformBody}>
-          <XCardPreview resolved={resolved} />
-          {!showXFields ? (
-            <div className={styles.customizeRow}>
-              <p className={styles.customizeHint}>
-                X uses the Open Graph values until customized.
-              </p>
-              <Button variant="secondary" size="sm" disabled={!canManage} onClick={() => setXExpanded(true)} data-testid="seo-customize-x">
-                Customize X preview
-              </Button>
-            </div>
-          ) : (
-            <>
-              {field('xTitle', 'X title', { sparkle: true })}
-              {field('xDescription', 'X description', { textarea: true, sparkle: true })}
-              <SeoImageField
-                label="X image"
-                value={draft.draft.xImage ?? ''}
-                inheritedValue={resolved.xImage ?? null}
-                disabled={!canManage}
-                onChange={(next) => draft.setField('xImage', next)}
-              />
-              {field('xImageAlt', 'X image alt')}
-              <div className={styles.field}>
-                <label htmlFor={`${fieldIdBase}-xCard`} className={styles.fieldLabel}>Card type</label>
-                <Select
-                  id={`${fieldIdBase}-xCard`}
-                  value={draft.draft.xCard ?? ''}
-                  disabled={!canManage}
-                  onChange={(e) => draft.setXCard(e.target.value === '' ? undefined : (e.target.value as 'summary' | 'summary_large_image'))}
-                >
-                  <option value="">Auto ({resolved.xCard})</option>
-                  <option value="summary">summary</option>
-                  <option value="summary_large_image">summary_large_image</option>
-                </Select>
-              </div>
-            </>
-          )}
+        <Separator />
+        <h3 className={styles.sectionHeading}>Social card (Open Graph)</h3>
+        {field('ogTitle', 'OG title', { sparkle: true })}
+        {field('ogDescription', 'OG description', { textarea: true, sparkle: true })}
+        <SeoImageField
+          label="OG image"
+          value={draft.draft.ogImage ?? ''}
+          inheritedValue={resolved.ogImage ?? null}
+          disabled={!canManage}
+          onChange={(next) => draft.setField('ogImage', next)}
+        />
+        {field('ogImageAlt', 'OG image alt')}
+        <div className={styles.field}>
+          <label htmlFor={`${fieldIdBase}-ogType`} className={styles.fieldLabel}>OG type</label>
+          <Select
+            id={`${fieldIdBase}-ogType`}
+            value={draft.draft.ogType ?? ''}
+            disabled={!canManage}
+            onChange={(e) => draft.setOgType(e.target.value === '' ? undefined : (e.target.value as 'website' | 'article'))}
+          >
+            <option value="">Auto ({resolved.ogType})</option>
+            <option value="website">website</option>
+            <option value="article">article</option>
+          </Select>
         </div>
-      )}
 
-      {platform === 'schema' && (
-        <div className={styles.platformBody}>
-          <SchemaPreview target={target} resolved={resolved} workspace={workspace} />
-          {template && (
-            <p className={styles.templateNote} role="status">
-              Patterns inherit from the “{template.title}” entry template.
+        <Separator />
+        <h3 className={styles.sectionHeading}>X card</h3>
+        {!showXFields ? (
+          <div className={styles.customizeRow}>
+            <p className={styles.customizeHint}>
+              X uses the Open Graph values until customized.
             </p>
-          )}
-        </div>
-      )}
-    </section>
+            <Button variant="secondary" size="sm" disabled={!canManage} onClick={() => setXExpanded(true)} data-testid="seo-customize-x">
+              Customize X preview
+            </Button>
+          </div>
+        ) : (
+          <>
+            {field('xTitle', 'X title', { sparkle: true })}
+            {field('xDescription', 'X description', { textarea: true, sparkle: true })}
+            <SeoImageField
+              label="X image"
+              value={draft.draft.xImage ?? ''}
+              inheritedValue={resolved.xImage ?? null}
+              disabled={!canManage}
+              onChange={(next) => draft.setField('xImage', next)}
+            />
+            {field('xImageAlt', 'X image alt')}
+            <div className={styles.field}>
+              <label htmlFor={`${fieldIdBase}-xCard`} className={styles.fieldLabel}>Card type</label>
+              <Select
+                id={`${fieldIdBase}-xCard`}
+                value={draft.draft.xCard ?? ''}
+                disabled={!canManage}
+                onChange={(e) => draft.setXCard(e.target.value === '' ? undefined : (e.target.value as 'summary' | 'summary_large_image'))}
+              >
+                <option value="">Auto ({resolved.xCard})</option>
+                <option value="summary">summary</option>
+                <option value="summary_large_image">summary_large_image</option>
+              </Select>
+            </div>
+          </>
+        )}
+      </section>
+    </div>
   )
 }
 
diff --git a/src/admin/pages/seo/components/SeoPreviewRail.module.css b/src/admin/pages/seo/components/SeoPreviewRail.module.css
new file mode 100644
index 000000000..1a91b3634
--- /dev/null
+++ b/src/admin/pages/seo/components/SeoPreviewRail.module.css
@@ -0,0 +1,33 @@
+.rail {
+    position: sticky;
+    top: 0;
+    align-self: start;
+    display: flex;
+    flex-direction: column;
+    gap: 20px;
+    min-width: 0;
+}
+
+.block {
+    display: flex;
+    flex-direction: column;
+    gap: 8px;
+}
+
+.blockLabel {
+    margin: 0;
+    font-size: 10px;
+    font-weight: 620;
+    letter-spacing: 0.08em;
+    text-transform: uppercase;
+    color: var(--editor-text-secondary);
+}
+
+.schemaToggle {
+    align-self: flex-start;
+    font-size: 10px;
+    font-weight: 620;
+    letter-spacing: 0.08em;
+    text-transform: uppercase;
+    color: var(--editor-text-secondary);
+}
diff --git a/src/admin/pages/seo/components/SeoPreviewRail.tsx b/src/admin/pages/seo/components/SeoPreviewRail.tsx
new file mode 100644
index 000000000..5b55f8714
--- /dev/null
+++ b/src/admin/pages/seo/components/SeoPreviewRail.tsx
@@ -0,0 +1,80 @@
+/**
+ * SeoPreviewRail — the Meta tab's sticky left rail: every platform preview
+ * stacked and live. Google snippet, Open Graph card, and X card update on
+ * each keystroke from the SAME resolved metadata the publisher emits; the
+ * JSON-LD schema block sits at the bottom behind a toggle (it's inspection,
+ * not glanceable).
+ */
+import { useState } from 'react'
+import { Button } from '@ui/components/Button'
+import { ChevronDownIcon } from 'pixel-art-icons/icons/chevron-down'
+import { ChevronRightIcon } from 'pixel-art-icons/icons/chevron-right'
+import type { ResolvedSeoMetadata } from '@core/seo'
+import type { SeoTarget } from '../lib/seoApi'
+import type { SeoWorkspace } from '../hooks/useSeoWorkspace'
+import { SearchSnippetPreview } from './SearchSnippetPreview'
+import { OpenGraphPreview } from './OpenGraphPreview'
+import { XCardPreview } from './XCardPreview'
+import { SchemaPreview } from './SchemaPreview'
+import styles from './SeoPreviewRail.module.css'
+
+interface SeoPreviewRailProps {
+  resolved: ResolvedSeoMetadata
+  workspace: SeoWorkspace
+  routePath: string
+  /**
+   * Target backing the schema block. The site-defaults editor passes the
+   * homepage here so the rail previews "a typical page with these defaults".
+   */
+  schemaTarget: SeoTarget | null
+}
+
+export function SeoPreviewRail({ resolved, workspace, routePath, schemaTarget }: SeoPreviewRailProps) {
+  const [schemaOpen, setSchemaOpen] = useState(false)
+
+  return (
+    <aside className={styles.rail} aria-label="Live previews">
+      <section className={styles.block}>
+        <h3 className={styles.blockLabel}>Google</h3>
+        <SearchSnippetPreview
+          resolved={resolved}
+          siteName={workspace.siteName}
+          origin={workspace.publicOrigin}
+          routePath={routePath}
+        />
+      </section>
+
+      <section className={styles.block}>
+        <h3 className={styles.blockLabel}>Open Graph</h3>
+        <OpenGraphPreview resolved={resolved} origin={workspace.publicOrigin} />
+      </section>
+
+      <section className={styles.block}>
+        <h3 className={styles.blockLabel}>X</h3>
+        <XCardPreview resolved={resolved} origin={workspace.publicOrigin} />
+      </section>
+
+      {schemaTarget && (
+        <section className={styles.block}>
+          <Button
+            type="button"
+            variant="ghost"
+            size="xs"
+            className={styles.schemaToggle}
+            aria-expanded={schemaOpen}
+            onClick={() => setSchemaOpen((open) => !open)}
+            data-testid="seo-schema-toggle"
+          >
+            {schemaOpen
+              ? <ChevronDownIcon size={11} aria-hidden="true" />
+              : <ChevronRightIcon size={11} aria-hidden="true" />}
+            <span>Structured data (JSON-LD)</span>
+          </Button>
+          {schemaOpen && (
+            <SchemaPreview target={schemaTarget} resolved={resolved} workspace={workspace} />
+          )}
+        </section>
+      )}
+    </aside>
+  )
+}
diff --git a/src/admin/pages/seo/components/SeoTargetIndex.module.css b/src/admin/pages/seo/components/SeoTargetIndex.module.css
index ca2bd5a78..1426bcfbe 100644
--- a/src/admin/pages/seo/components/SeoTargetIndex.module.css
+++ b/src/admin/pages/seo/components/SeoTargetIndex.module.css
@@ -1,126 +1,146 @@
 .index {
-  display: flex;
-  flex-direction: column;
-  gap: 10px;
+    display: flex;
+    flex-direction: column;
+    gap: 12px;
+    min-width: 0;
 }
 
-.summaryRow {
-  display: flex;
-  flex-wrap: wrap;
-  gap: 6px;
+.summary {
+    margin: 0;
+    font-size: 11px;
+    color: var(--editor-warning-text);
 }
 
-.summaryChip {
-  font-size: 11px;
-  padding: 2px 8px;
-  border-radius: var(--editor-radius-sm);
-  background: var(--editor-surface-3);
-  color: var(--editor-warning-text);
+.scroller {
+    display: flex;
+    flex-direction: column;
+    gap: 14px;
+    outline: none;
 }
 
-.list {
-  display: flex;
-  flex-direction: column;
-  gap: 1px;
-  background: var(--editor-surface);
-  border-radius: 16px;
-  overflow: hidden;
-  outline: none;
+.scroller:focus-visible {
+    border-radius: var(--editor-radius);
+    box-shadow: 0 0 0 2px var(--editor-focus-ring);
 }
 
-.list:focus-visible {
-  box-shadow: 0 0 0 2px var(--editor-focus-ring);
+/* Pinned site-defaults card — its own rounded tile above the groups. */
+.siteRow {
+    display: flex;
+    align-items: center;
+    justify-content: space-between;
+    gap: 10px;
+    width: 100%;
+    padding: 12px 14px;
+    border-radius: var(--panel-radius);
+    background: var(--editor-surface-2);
+    text-align: left;
+}
+
+.siteRow:hover {
+    background: var(--editor-surface-3);
+}
+
+.group {
+    display: flex;
+    flex-direction: column;
+    gap: 6px;
+}
+
+.groupLabel {
+    margin: 0;
+    padding: 0 2px;
+    font-size: 10px;
+    font-weight: 620;
+    letter-spacing: 0.08em;
+    text-transform: uppercase;
+    color: var(--editor-text-secondary);
+}
+
+.groupList {
+    display: flex;
+    flex-direction: column;
+    gap: 1px;
+    background: var(--editor-surface);
+    border-radius: var(--panel-radius);
+    overflow: hidden;
 }
 
 .row {
-  display: flex;
-  align-items: center;
-  justify-content: space-between;
-  gap: 10px;
-  width: 100%;
-  padding: 8px 12px;
-  border-radius: 0;
-  background: var(--editor-surface-2);
-  text-align: left;
+    display: flex;
+    align-items: center;
+    justify-content: space-between;
+    gap: 10px;
+    width: 100%;
+    padding: 10px 14px;
+    border-radius: 0;
+    background: var(--editor-surface-2);
+    text-align: left;
 }
 
 .row:hover {
-  background: var(--editor-surface-3);
+    background: var(--editor-surface-3);
 }
 
 .rowSelected,
 .rowSelected:hover {
-  background: var(--editor-surface-4);
-}
-
-.rowPinned {
-  background: var(--editor-surface-3);
+    background: var(--editor-surface-4);
+    box-shadow: inset 2px 0 0 var(--editor-accent);
 }
 
 .rowMain {
-  display: flex;
-  flex-direction: column;
-  gap: 1px;
-  min-width: 0;
+    display: flex;
+    flex-direction: column;
+    gap: 2px;
+    min-width: 0;
 }
 
 .rowTitle {
-  font-size: 12px;
-  font-weight: 600;
-  color: var(--editor-text-bright);
-  white-space: nowrap;
-  overflow: hidden;
-  text-overflow: ellipsis;
+    font-size: 12px;
+    font-weight: 600;
+    color: var(--editor-text-bright);
+    white-space: nowrap;
+    overflow: hidden;
+    text-overflow: ellipsis;
 }
 
 .rowSub {
-  font-size: 11px;
-  color: var(--editor-text-muted);
-  white-space: nowrap;
-  overflow: hidden;
-  text-overflow: ellipsis;
-}
-
-.rowMeta {
-  display: flex;
-  align-items: center;
-  gap: 8px;
-  flex-shrink: 0;
-}
-
-.rowKind {
-  font-size: 10px;
-  text-transform: uppercase;
-  letter-spacing: 0.04em;
-  color: var(--editor-text-muted);
+    font-size: 11px;
+    font-family: var(--font-mono);
+    color: var(--editor-text-muted);
+    white-space: nowrap;
+    overflow: hidden;
+    text-overflow: ellipsis;
 }
 
 .dots {
-  display: inline-flex;
-  gap: 3px;
+    display: inline-flex;
+    gap: 3px;
+    flex-shrink: 0;
 }
 
 .dot {
-  width: 6px;
-  height: 6px;
-  border-radius: 50%;
+    width: 6px;
+    height: 6px;
+    border-radius: 50%;
 }
 
 .dot_ok {
-  background: var(--editor-success-green);
+    background: var(--editor-success-green);
 }
 
 .dot_warn {
-  background: var(--editor-warning);
+    background: var(--editor-warning);
 }
 
 .dot_bad {
-  background: var(--editor-danger);
+    background: var(--editor-danger);
 }
 
 .empty {
-  padding: 16px;
-  font-size: 12px;
-  color: var(--editor-text-muted);
-  background: var(--editor-surface-2);
+    margin: 0;
+    padding: 14px;
+    font-size: 12px;
+    color: var(--editor-text-muted);
+    background: var(--editor-surface-2);
+    border-radius: var(--panel-radius);
 }
diff --git a/src/admin/pages/seo/components/SeoTargetIndex.tsx b/src/admin/pages/seo/components/SeoTargetIndex.tsx
index b85078b76..d587e1e65 100644
--- a/src/admin/pages/seo/components/SeoTargetIndex.tsx
+++ b/src/admin/pages/seo/components/SeoTargetIndex.tsx
@@ -1,10 +1,10 @@
 /**
  * SeoTargetIndex — the Meta tab's right column: navigation + audit context.
  *
- * Search bar, kind filters (All / Pages / Posts / Templates / Issues), an
- * issues summary chip row, the pinned Site defaults row, and dense target
- * rows with per-field health dots. Keyboard: ↑/↓ move the selection,
- * Enter activates, `/` focuses search.
+ * Search, kind filters, an issues summary chip, the pinned Site defaults
+ * card, then the targets grouped under Pages / Templates / Posts section
+ * headers — each row shows title, mono route, and per-field health dots.
+ * Keyboard: ↑/↓ move the selection, `/` focuses search.
  */
 import { useRef, useState, type KeyboardEvent } from 'react'
 import { SearchBar } from '@ui/components/SearchBar'
@@ -32,6 +32,11 @@ interface IndexedTarget {
   health: SeoHealth
 }
 
+interface TargetGroup {
+  label: string
+  items: IndexedTarget[]
+}
+
 interface SeoTargetIndexProps {
   workspace: SeoWorkspace
   selectedId: string
@@ -43,7 +48,6 @@ export function SeoTargetIndex({ workspace, selectedId, siteDefaultsId, onSelect
   const [query, setQuery] = useState('')
   const [filter, setFilter] = useState<Filter>('all')
   const searchRef = useRef<HTMLInputElement>(null)
-  const listRef = useRef<HTMLDivElement>(null)
 
   const indexed: IndexedTarget[] = workspace.targets.map((target) => ({
     target,
@@ -53,9 +57,7 @@ export function SeoTargetIndex({ workspace, selectedId, siteDefaultsId, onSelect
     ),
   }))
 
-  const missingTitles = indexed.filter((item) => item.health.title !== 'ok').length
-  const missingDescriptions = indexed.filter((item) => item.health.description !== 'ok').length
-  const noindexed = indexed.filter((item) => !item.health.indexable).length
+  const issueCount = indexed.filter((item) => item.health.issueCount > 0).length
 
   const normalizedQuery = query.trim().toLowerCase()
   const visible = indexed.filter(({ target, health }) => {
@@ -70,8 +72,15 @@ export function SeoTargetIndex({ workspace, selectedId, siteDefaultsId, onSelect
     )
   })
 
-  // Keyboard order: pinned site row first, then the visible targets.
-  const order: string[] = [siteDefaultsId, ...visible.map(({ target }) => target.id)]
+  const groups: TargetGroup[] = [
+    { label: 'Pages', items: visible.filter(({ target }) => target.kind === 'page') },
+    { label: 'Templates', items: visible.filter(({ target }) => target.kind === 'template') },
+    { label: 'Posts', items: visible.filter(({ target }) => target.kind === 'post') },
+  ].filter((group) => group.items.length > 0)
+
+  // Keyboard order: pinned site row first, then the grouped targets in
+  // display order.
+  const order: string[] = [siteDefaultsId, ...groups.flatMap((group) => group.items.map(({ target }) => target.id))]
 
   function handleListKeyDown(event: KeyboardEvent<HTMLDivElement>): void {
     if (event.key === '/') {
@@ -105,52 +114,54 @@ export function SeoTargetIndex({ workspace, selectedId, siteDefaultsId, onSelect
         options={FILTER_OPTIONS}
         onChange={setFilter}
         size="xs"
+        fullWidth
         aria-label="Filter targets"
         data-testid="seo-target-filter"
       />
 
-      {(missingTitles > 0 || missingDescriptions > 0 || noindexed > 0) && (
-        <div className={styles.summaryRow} role="status">
-          {missingTitles > 0 && (
-            <span className={styles.summaryChip}>{missingTitles} title {missingTitles === 1 ? 'issue' : 'issues'}</span>
-          )}
-          {missingDescriptions > 0 && (
-            <span className={styles.summaryChip}>{missingDescriptions} description {missingDescriptions === 1 ? 'issue' : 'issues'}</span>
-          )}
-          {noindexed > 0 && (
-            <span className={styles.summaryChip}>{noindexed} noindexed</span>
-          )}
-        </div>
+      {issueCount > 0 && (
+        <p className={styles.summary} role="status">
+          {issueCount} {issueCount === 1 ? 'target needs' : 'targets need'} attention
+        </p>
       )}
 
       <div
-        ref={listRef}
-        className={styles.list}
+        className={styles.scroller}
         role="listbox"
         aria-label="SEO target list"
         tabIndex={0}
         onKeyDown={handleListKeyDown}
       >
-        <TargetRow
-          pinned
-          label="Site defaults"
-          sublabel="Fallbacks for every target"
-          selected={selectedId === siteDefaultsId}
-          onSelect={() => onSelect(siteDefaultsId)}
-          testId="seo-target-site-defaults"
-        />
-        {visible.map(({ target, health }) => (
-          <TargetRow
-            key={target.id}
-            label={target.title}
-            sublabel={target.route ?? (target.kind === 'template' ? 'Entry template' : '—')}
-            kind={target.kind}
-            tableLabel={target.tableLabel}
-            health={health}
-            selected={selectedId === target.id}
-            onSelect={() => onSelect(target.id)}
-            testId={`seo-target-${target.id}`}
-          />
+        <Button
+          type="button"
+          variant="ghost"
+          className={cn(styles.siteRow, selectedId === siteDefaultsId && styles.rowSelected)}
+          role="option"
+          aria-selected={selectedId === siteDefaultsId}
+          onClick={() => onSelect(siteDefaultsId)}
+          data-testid="seo-target-site-defaults"
+        >
+          <span className={styles.rowMain}>
+            <span className={styles.rowTitle}>Site defaults</span>
+            <span className={styles.rowSub}>Fallbacks for every target</span>
+          </span>
+        </Button>
+
+        {groups.map((group) => (
+          <div key={group.label} className={styles.group}>
+            <h3 className={styles.groupLabel}>{group.label}</h3>
+            <div className={styles.groupList}>
+              {group.items.map(({ target, health }) => (
+                <TargetRow
+                  key={target.id}
+                  target={target}
+                  health={health}
+                  selected={selectedId === target.id}
+                  onSelect={() => onSelect(target.id)}
+                />
+              ))}
+            </div>
+          </div>
         ))}
         {visible.length === 0 && (
           <p className={styles.empty} role="status">No targets match the current filter.</p>
@@ -161,45 +172,33 @@ export function SeoTargetIndex({ workspace, selectedId, siteDefaultsId, onSelect
 }
 
 function TargetRow({
-  label,
-  sublabel,
-  kind,
-  tableLabel,
+  target,
   health,
   selected,
-  pinned = false,
   onSelect,
-  testId,
 }: {
-  label: string
-  sublabel: string
-  kind?: SeoTarget['kind']
-  tableLabel?: string
-  health?: SeoHealth
+  target: SeoTarget
+  health: SeoHealth
   selected: boolean
-  pinned?: boolean
   onSelect: () => void
-  testId: string
 }) {
-  const kindLabel = kind === 'post' ? (tableLabel ?? 'Post') : kind === 'template' ? 'Template' : kind === 'page' ? 'Page' : 'Site'
   return (
     <Button
       type="button"
       variant="ghost"
-      className={cn(styles.row, selected && styles.rowSelected, pinned && styles.rowPinned)}
+      className={cn(styles.row, selected && styles.rowSelected)}
       role="option"
       aria-selected={selected}
       onClick={onSelect}
-      data-testid={testId}
+      data-testid={`seo-target-${target.id}`}
     >
       <span className={styles.rowMain}>
-        <span className={styles.rowTitle}>{label}</span>
-        <span className={styles.rowSub}>{sublabel}</span>
-      </span>
-      <span className={styles.rowMeta}>
-        <span className={styles.rowKind}>{kindLabel}</span>
-        {health && <HealthDots health={health} />}
+        <span className={styles.rowTitle}>{target.title}</span>
+        <span className={styles.rowSub}>
+          {target.route ?? (target.kind === 'template' ? `Entry template${target.tableSlug ? ` · ${target.tableSlug}` : ''}` : '—')}
+        </span>
       </span>
+      <HealthDots health={health} />
     </Button>
   )
 }
diff --git a/src/admin/pages/seo/components/SiteDefaultsEditor.tsx b/src/admin/pages/seo/components/SiteDefaultsEditor.tsx
index 6552d62fb..ae2f4fb42 100644
--- a/src/admin/pages/seo/components/SiteDefaultsEditor.tsx
+++ b/src/admin/pages/seo/components/SiteDefaultsEditor.tsx
@@ -1,18 +1,22 @@
 /**
- * SiteDefaultsEditor — the pinned "Site defaults" target's editing surface.
+ * SiteDefaultsEditor — the pinned "Site defaults" target's workbench.
  *
- * Edits `site.settings.seo`: the title pattern (shared `{source.field}`
- * token syntax), site description, default social image + alt, default X
- * card type, X site handle, and the Organization fields that feed the
- * site-wide JSON-LD. Robots/sitemap settings live on the same object but
- * are edited in their own tabs.
+ * Left rail: live previews of the HOMEPAGE resolved with the draft defaults
+ * applied — the user sees exactly what a typical page inherits while they
+ * type the pattern. Right: the sectioned defaults form (`site.settings.seo`:
+ * title pattern, description, default social image, X handle/card, and the
+ * Organization fields feeding site-wide JSON-LD). Robots/sitemap settings
+ * live on the same object but are edited in their own tabs.
  */
 import { useEffect, useId, useState } from 'react'
 import { Input, Textarea } from '@ui/components/Input'
 import { Select } from '@ui/components/Select'
+import { Separator } from '@ui/components/Separator'
 import { getErrorMessage } from '@core/utils/errorMessage'
 import type { SiteSeoSettings } from '@core/seo'
 import type { SeoWorkspace } from '../hooks/useSeoWorkspace'
+import { resolveTargetSeo } from '../lib/resolveTargetSeo'
+import { SeoPreviewRail } from './SeoPreviewRail'
 import { SeoImageField } from './SeoImageField'
 import { SaveControls } from './SeoPreviewEditor'
 import styles from './SeoPreviewEditor.module.css'
@@ -71,6 +75,19 @@ export function SiteDefaultsEditor({ workspace, canManage, onDirtyChange }: Site
     onDirtyChange(isDirty)
   }, [isDirty, onDirtyChange])
 
+  // Rail sample: the homepage (or any page) resolved with the DRAFT defaults
+  // overlayed — live "what a typical page inherits" feedback while typing.
+  const sampleTarget =
+    workspace.targets.find((target) => target.kind === 'page' && target.route === '/') ??
+    workspace.targets.find((target) => target.kind === 'page') ??
+    null
+  const sampleResolved = sampleTarget
+    ? resolveTargetSeo(sampleTarget, sampleTarget.seo ?? undefined, {
+        ...workspace.resolveContext,
+        siteSeo: draft,
+      })
+    : null
+
   function setField(field: SiteStringField, value: string): void {
     setDraft((current) => {
       const next = { ...current }
@@ -111,28 +128,42 @@ export function SiteDefaultsEditor({ workspace, canManage, onDirtyChange }: Site
   }
 
   return (
-    <section className={styles.editor} aria-label="Site SEO defaults">
-      <header className={styles.header}>
-        <div className={styles.headerText}>
-          <h2 className={styles.headerTitle}>Site defaults</h2>
-          <span className={styles.headerRoute}>Fallbacks for every page and post</span>
-        </div>
-        <SaveControls dirty={isDirty} state={saveState} canManage={canManage} onSave={() => void handleSave()} />
-      </header>
-      {saveError && <p className={styles.error} role="alert">{saveError}</p>}
-      {!canManage && (
-        <p className={styles.readOnlyNote} role="status">
-          Read-only — your role does not include Manage SEO.
-        </p>
-      )}
-      {!workspace.siteSeo && !isDirty && (
-        <p className={styles.templateNote} role="status">
-          No site defaults yet — set a title pattern and description so every
-          target has sensible metadata out of the box.
-        </p>
+    <div className={styles.workbench}>
+      {sampleResolved && sampleTarget ? (
+        <SeoPreviewRail
+          resolved={sampleResolved}
+          workspace={workspace}
+          routePath={sampleTarget.route ?? '/'}
+          schemaTarget={sampleTarget}
+        />
+      ) : (
+        <div />
       )}
 
-      <div className={styles.platformBody}>
+      <section className={styles.form} aria-label="Site SEO defaults">
+        <header className={styles.header}>
+          <div className={styles.headerText}>
+            <h2 className={styles.headerTitle}>Site defaults</h2>
+            <span className={styles.headerRoute}>
+              {sampleTarget ? `Previewing “${sampleTarget.title}” with these defaults` : 'Fallbacks for every page and post'}
+            </span>
+          </div>
+          <SaveControls dirty={isDirty} state={saveState} canManage={canManage} onSave={() => void handleSave()} />
+        </header>
+        {saveError && <p className={styles.error} role="alert">{saveError}</p>}
+        {!canManage && (
+          <p className={styles.readOnlyNote} role="status">
+            Read-only — your role does not include Manage SEO.
+          </p>
+        )}
+        {!workspace.siteSeo && !isDirty && (
+          <p className={styles.templateNote} role="status">
+            No site defaults yet — set a title pattern and description so every
+            target has sensible metadata out of the box.
+          </p>
+        )}
+
+        <h3 className={styles.sectionHeading}>Defaults</h3>
         <div className={styles.field}>
           <label htmlFor={`${idBase}-pattern`} className={styles.fieldLabel}>Title pattern</label>
           <Input
@@ -215,6 +246,7 @@ export function SiteDefaultsEditor({ workspace, canManage, onDirtyChange }: Site
           />
         </div>
 
+        <Separator />
         <h3 className={styles.sectionHeading}>Organization (structured data)</h3>
         <p className={styles.fieldHint}>
           Emitted as schema.org <code>Organization</code> JSON-LD on the homepage —
@@ -239,7 +271,7 @@ export function SiteDefaultsEditor({ workspace, canManage, onDirtyChange }: Site
           disabled={!canManage}
           onChange={(next) => setOrgField('logoUrl', next)}
         />
-      </div>
-    </section>
+      </section>
+    </div>
   )
 }
diff --git a/src/admin/pages/seo/components/XCardPreview.module.css b/src/admin/pages/seo/components/XCardPreview.module.css
index 6370832e2..dbfe452eb 100644
--- a/src/admin/pages/seo/components/XCardPreview.module.css
+++ b/src/admin/pages/seo/components/XCardPreview.module.css
@@ -1,70 +1,119 @@
-.card {
-  margin: 0;
-  border-radius: var(--panel-radius);
-  overflow: hidden;
-  background: var(--editor-surface);
+/* 1:1 X (Twitter) dark-theme cards. */
+
+.wrap {
+    display: flex;
+    flex-direction: column;
+    gap: 4px;
+    margin: 0;
+    font-family: -apple-system, BlinkMacSystemFont, "Segoe UI", Helvetica, arial, sans-serif;
+}
+
+/* ── summary_large_image ─────────────────────────────────────────────────── */
+.largeCard {
+    position: relative;
+    border-radius: 16px;
+    border: 1px solid var(--seo-x-border);
+    overflow: hidden;
+    background: var(--seo-x-bg);
+}
+
+.largeImage {
+    width: 100%;
+    aspect-ratio: 1.91 / 1;
+    object-fit: cover;
+    display: block;
 }
 
-.cardLarge {
-  display: flex;
-  flex-direction: column;
+.largePlaceholder {
+    width: 100%;
+    aspect-ratio: 1.91 / 1;
+    display: flex;
+    align-items: center;
+    justify-content: center;
+    color: var(--seo-x-text);
+    font-size: 13px;
 }
 
-.cardSummary {
-  display: grid;
-  grid-template-columns: 96px minmax(0, 1fr);
-  align-items: stretch;
+.overlayTitle {
+    position: absolute;
+    left: 12px;
+    bottom: 12px;
+    max-width: calc(100% - 24px);
+    padding: 2px 8px;
+    border-radius: 4px;
+    background: var(--seo-x-overlay);
+    color: var(--seo-x-title);
+    font-size: 13px;
+    line-height: 20px;
+    white-space: nowrap;
+    overflow: hidden;
+    text-overflow: ellipsis;
 }
 
-.cardLarge .image,
-.cardLarge .imagePlaceholder {
-  width: 100%;
-  aspect-ratio: 1.91 / 1;
+.fromLine {
+    color: var(--seo-x-text);
+    font-size: 13px;
+    line-height: 16px;
+    padding-left: 4px;
 }
 
-.cardSummary .image,
-.cardSummary .imagePlaceholder {
-  width: 96px;
-  height: 100%;
-  min-height: 96px;
+/* ── summary ─────────────────────────────────────────────────────────────── */
+.summaryCard {
+    display: grid;
+    grid-template-columns: 96px minmax(0, 1fr);
+    border-radius: 16px;
+    border: 1px solid var(--seo-x-border);
+    overflow: hidden;
+    background: var(--seo-x-bg);
 }
 
-.image {
-  object-fit: cover;
+.summaryImage {
+    width: 96px;
+    height: 100%;
+    min-height: 96px;
+    object-fit: cover;
+    display: block;
+    border-right: 1px solid var(--seo-x-border);
 }
 
-.imagePlaceholder {
-  display: flex;
-  align-items: center;
-  justify-content: center;
-  background: var(--editor-surface-3);
-  color: var(--editor-text-muted);
-  font-size: 11px;
+.summaryPlaceholder {
+    width: 96px;
+    min-height: 96px;
+    background: var(--seo-og-placeholder);
+    border-right: 1px solid var(--seo-x-border);
 }
 
-.meta {
-  display: flex;
-  flex-direction: column;
-  gap: 2px;
-  padding: 10px 14px;
+.summaryMeta {
+    display: flex;
+    flex-direction: column;
+    gap: 2px;
+    justify-content: center;
+    padding: 12px;
 }
 
-.title {
-  font-size: 13px;
-  font-weight: 700;
-  color: var(--editor-text-bright);
+.summaryDomain {
+    color: var(--seo-x-text);
+    font-size: 13px;
+    line-height: 16px;
 }
 
-.description {
-  font-size: 12px;
-  color: var(--editor-text);
-  display: -webkit-box;
-  -webkit-line-clamp: 2;
-  -webkit-box-orient: vertical;
-  overflow: hidden;
+.summaryTitle {
+    color: var(--seo-x-title);
+    font-size: 15px;
+    line-height: 20px;
+    font-weight: 400;
+    overflow: hidden;
+    display: -webkit-box;
+    -webkit-line-clamp: 1;
+    -webkit-box-orient: vertical;
 }
 
-.handle {
-  font-size: 11px;
-  color: var(--editor-text-muted);
+.summaryDescription {
+    color: var(--seo-x-text);
+    font-size: 15px;
+    line-height: 20px;
+    overflow: hidden;
+    display: -webkit-box;
+    -webkit-line-clamp: 2;
+    -webkit-box-orient: vertical;
 }
diff --git a/src/admin/pages/seo/components/XCardPreview.tsx b/src/admin/pages/seo/components/XCardPreview.tsx
index 131a7b3b7..ca75442d4 100644
--- a/src/admin/pages/seo/components/XCardPreview.tsx
+++ b/src/admin/pages/seo/components/XCardPreview.tsx
@@ -1,28 +1,56 @@
 /**
- * XCardPreview — X (Twitter) card mock rendered from resolved values.
- * Layout follows the card type: `summary_large_image` stacks a wide image
- * above the text; `summary` puts a small square thumb beside it.
+ * XCardPreview — 1:1 mock of an X (Twitter) dark-theme card.
+ *
+ * `summary_large_image`: 16px-radius hairline-bordered image with the title
+ * chip overlaid bottom-left, then the grey "From domain" line below — X's
+ * current rendering. `summary`: square thumb on the left, domain/title/
+ * description stack on the right. Colours live in the `--seo-x-*` palette.
  */
 import { cn } from '@ui/cn'
 import type { ResolvedSeoMetadata } from '@core/seo'
 import styles from './XCardPreview.module.css'
+import { previewDomain } from './previewDomain'
 
-export function XCardPreview({ resolved }: { resolved: ResolvedSeoMetadata }) {
+interface XCardPreviewProps {
+  resolved: ResolvedSeoMetadata
+  origin: string | null
+}
+
+export function XCardPreview({ resolved, origin }: XCardPreviewProps) {
+  const domain = previewDomain(origin, resolved.canonicalUrl)
   const large = resolved.xCard === 'summary_large_image'
+
+  if (large) {
+    return (
+      <figure className={styles.wrap} aria-label="X card preview">
+        <div className={styles.largeCard}>
+          {resolved.xImage ? (
+            <img className={styles.largeImage} src={resolved.xImage} alt={resolved.xImageAlt ?? ''} />
+          ) : (
+            <div className={styles.largePlaceholder} aria-hidden="true">No image</div>
+          )}
+          <span className={styles.overlayTitle}>{resolved.xTitle}</span>
+        </div>
+        <span className={styles.fromLine}>From {domain}</span>
+      </figure>
+    )
+  }
+
   return (
-    <figure
-      className={cn(styles.card, large ? styles.cardLarge : styles.cardSummary)}
-      aria-label="X card preview"
-    >
-      {resolved.xImage ? (
-        <img className={styles.image} src={resolved.xImage} alt={resolved.xImageAlt ?? ''} />
-      ) : (
-        <div className={styles.imagePlaceholder} aria-hidden="true">No image</div>
-      )}
-      <div className={styles.meta}>
-        <span className={styles.title}>{resolved.xTitle}</span>
-        {resolved.xDescription && <span className={styles.description}>{resolved.xDescription}</span>}
-        {resolved.xSiteHandle && <span className={styles.handle}>{resolved.xSiteHandle}</span>}
+    <figure className={styles.wrap} aria-label="X card preview">
+      <div className={cn(styles.summaryCard)}>
+        {resolved.xImage ? (
+          <img className={styles.summaryImage} src={resolved.xImage} alt={resolved.xImageAlt ?? ''} />
+        ) : (
+          <div className={styles.summaryPlaceholder} aria-hidden="true" />
+        )}
+        <div className={styles.summaryMeta}>
+          <span className={styles.summaryDomain}>{domain}</span>
+          <span className={styles.summaryTitle}>{resolved.xTitle}</span>
+          {resolved.xDescription && (
+            <span className={styles.summaryDescription}>{resolved.xDescription}</span>
+          )}
+        </div>
       </div>
     </figure>
   )
diff --git a/src/admin/pages/seo/components/previewDomain.ts b/src/admin/pages/seo/components/previewDomain.ts
new file mode 100644
index 000000000..97851ec9f
--- /dev/null
+++ b/src/admin/pages/seo/components/previewDomain.ts
@@ -0,0 +1,28 @@
+/**
+ * Display-domain helpers shared by the platform previews. The previews are
+ * 1:1 mocks, so they show the breadcrumb/domain lines exactly the way the
+ * platforms render them.
+ */
+
+/** `https://acme.com/x` → `acme.com`; falls back to a neutral placeholder. */
+export function previewDomain(origin: string | null, canonicalUrl?: string): string {
+  const source = canonicalUrl ?? origin ?? ''
+  try {
+    return new URL(source).hostname
+  } catch {
+    return 'example.com'
+  }
+}
+
+/** Google-style breadcrumb: `acme.com › posts › hello-world`. */
+export function serpBreadcrumb(origin: string | null, routePath: string, canonicalUrl?: string): string {
+  const domain = previewDomain(origin, canonicalUrl)
+  const segments = routePath.split('/').filter(Boolean)
+  return [domain, ...segments].join(' › ')
+}
+
+/** Capitalised site-name line Google shows above the breadcrumb. */
+export function serpSiteLabel(siteName: string, origin: string | null): string {
+  if (siteName.trim() !== '') return siteName
+  return previewDomain(origin)
+}
diff --git a/src/admin/pages/seo/tabs/MetaTab.module.css b/src/admin/pages/seo/tabs/MetaTab.module.css
index dbcac6422..a76fb2667 100644
--- a/src/admin/pages/seo/tabs/MetaTab.module.css
+++ b/src/admin/pages/seo/tabs/MetaTab.module.css
@@ -1,26 +1,28 @@
 .columns {
-  display: grid;
-  grid-template-columns: minmax(0, 1fr) 360px;
-  gap: 16px;
-  align-items: start;
+    display: grid;
+    grid-template-columns: minmax(0, 1fr) 300px;
+    gap: 28px;
+    align-items: start;
 }
 
 .editorColumn {
-  position: sticky;
-  top: 16px;
-  min-width: 0;
+    min-width: 0;
 }
 
 .indexColumn {
-  min-width: 0;
+    position: sticky;
+    top: 0;
+    align-self: start;
+    min-width: 0;
 }
 
 @media (max-width: 960px) {
-  .columns {
-    grid-template-columns: 1fr;
-  }
+    .columns {
+        grid-template-columns: 1fr;
+    }
 
-  .editorColumn {
-    position: static;
-  }
+    .indexColumn {
+        position: static;
+        order: -1;
+    }
 }
diff --git a/src/admin/pages/seo/tabs/MetaTab.tsx b/src/admin/pages/seo/tabs/MetaTab.tsx
index 596ec5a17..e1899106b 100644
--- a/src/admin/pages/seo/tabs/MetaTab.tsx
+++ b/src/admin/pages/seo/tabs/MetaTab.tsx
@@ -3,14 +3,15 @@
  *
  * Two persistent columns:
  *   - Left: sticky preview editor. Platform switcher (Search / Open Graph /
- *     X / Schema), editable snippet fields with inherited-value placeholders
- *     and pixel length meters. The pinned "Site defaults" target renders the
- *     site-level editor instead (patterns, default images, organization).
+ *     X / Schema) over live 1:1 platform previews, editable snippet fields
+ *     with inherited-value placeholders and pixel length meters. The pinned
+ *     "Site defaults" row opens the site-level editor instead.
  *   - Right: target index — search, kind filters, issues summary chips,
  *     dense rows with per-field health dots, full keyboard navigation.
  *
- * Dirty guard: switching targets with unsaved changes asks through an
- * in-app dialog (never `confirm()`); nothing is silently discarded.
+ * The homepage is selected by default so the user lands on a live preview,
+ * not an empty defaults form. Switching targets with unsaved changes asks
+ * through an in-app dialog (never `confirm()`).
  */
 import { useState } from 'react'
 import { Button } from '@ui/components/Button'
@@ -30,11 +31,22 @@ interface MetaTabProps {
   canManage: boolean
 }
 
+/** Homepage first, then any page, then the site defaults row. */
+function defaultSelectionId(targets: SeoTarget[]): string {
+  return (
+    targets.find((target) => target.kind === 'page' && target.route === '/')?.id ??
+    targets.find((target) => target.kind === 'page')?.id ??
+    SITE_DEFAULTS_ID
+  )
+}
+
 export function MetaTab({ workspace, canManage }: MetaTabProps) {
-  const [selectedId, setSelectedId] = useState<string>(SITE_DEFAULTS_ID)
+  const [selection, setSelection] = useState<string | null>(null)
   const [editorDirty, setEditorDirty] = useState(false)
   const [pendingSelection, setPendingSelection] = useState<string | null>(null)
 
+  const selectedId = selection ?? defaultSelectionId(workspace.targets)
+
   const selectedTarget: SeoTarget | null =
     selectedId === SITE_DEFAULTS_ID
       ? null
@@ -46,12 +58,12 @@ export function MetaTab({ workspace, canManage }: MetaTabProps) {
       setPendingSelection(nextId)
       return
     }
-    setSelectedId(nextId)
+    setSelection(nextId)
   }
 
   function discardAndSwitch(): void {
     if (pendingSelection !== null) {
-      setSelectedId(pendingSelection)
+      setSelection(pendingSelection)
       setEditorDirty(false)
       setPendingSelection(null)
     }
diff --git a/src/admin/pages/seo/tabs/RobotsTab.tsx b/src/admin/pages/seo/tabs/RobotsTab.tsx
index 856670150..2f9ebef01 100644
--- a/src/admin/pages/seo/tabs/RobotsTab.tsx
+++ b/src/admin/pages/seo/tabs/RobotsTab.tsx
@@ -1,14 +1,15 @@
 /**
  * RobotsTab — generated robots.txt controls + live preview.
  *
- * Three switches (indexing, AI training crawlers, AI answer crawlers) over
- * a byte-identical preview of the served file — the preview calls the same
- * `generateRobotsTxt` the server endpoint uses. Saving writes
- * `site.settings.seo.robots`; output goes live with the publish lifecycle.
+ * Three FormField-wrapped switches (indexing, AI training crawlers, AI
+ * answer crawlers) over a byte-identical CodeMirror preview of the served
+ * file — the preview calls the same `generateRobotsTxt` the server endpoint
+ * uses. Saving writes `site.settings.seo.robots`; output goes live with the
+ * publish lifecycle.
  */
 import { useState } from 'react'
 import { Switch } from '@ui/components/Switch'
-import { Code } from '@ui/components/Code'
+import { FormField } from '@ui/components/FormField'
 import { getErrorMessage } from '@core/utils/errorMessage'
 import {
   generateRobotsTxt,
@@ -17,6 +18,7 @@ import {
   type SeoRobotsSettings,
 } from '@core/seo'
 import { SaveControls } from '../components/SeoPreviewEditor'
+import { SeoCodeViewer } from '../components/SeoCodeViewer'
 import type { SeoWorkspace } from '../hooks/useSeoWorkspace'
 import styles from './SettingsTabs.module.css'
 
@@ -77,68 +79,49 @@ export function RobotsTab({ workspace, canManage }: RobotsTabProps) {
       )}
 
       <div className={styles.controls}>
-        <SettingSwitch
+        <FormField
+          layout="inline-end"
           label="Allow search engine indexing"
           description="Turning this off serves a global Disallow — the whole site disappears from search."
-          checked={draft.indexingEnabled !== false}
-          disabled={!canManage}
-          onChange={(value) => setFlag('indexingEnabled', value)}
-          testId="seo-robots-indexing"
-        />
-        <SettingSwitch
+        >
+          <Switch
+            checked={draft.indexingEnabled !== false}
+            onCheckedChange={(value) => setFlag('indexingEnabled', value)}
+            disabled={!canManage}
+            aria-label="Allow search engine indexing"
+            data-testid="seo-robots-indexing"
+          />
+        </FormField>
+        <FormField
+          layout="inline-end"
           label="Allow AI training crawlers"
           description={`Bots that ingest content for model training: ${AI_TRAINING_CRAWLERS.join(', ')}.`}
-          checked={draft.allowAiTrainingCrawlers !== false}
-          disabled={!canManage || draft.indexingEnabled === false}
-          onChange={(value) => setFlag('allowAiTrainingCrawlers', value)}
-          testId="seo-robots-ai-training"
-        />
-        <SettingSwitch
+        >
+          <Switch
+            checked={draft.allowAiTrainingCrawlers !== false}
+            onCheckedChange={(value) => setFlag('allowAiTrainingCrawlers', value)}
+            disabled={!canManage || draft.indexingEnabled === false}
+            aria-label="Allow AI training crawlers"
+            data-testid="seo-robots-ai-training"
+          />
+        </FormField>
+        <FormField
+          layout="inline-end"
           label="Allow AI search & answer crawlers"
           description={`Bots that fetch content to ground live AI answers: ${AI_ANSWER_CRAWLERS.join(', ')}. Blocking these removes the site from AI search results.`}
-          checked={draft.allowAiAnswerCrawlers !== false}
-          disabled={!canManage || draft.indexingEnabled === false}
-          onChange={(value) => setFlag('allowAiAnswerCrawlers', value)}
-          testId="seo-robots-ai-answer"
-        />
+        >
+          <Switch
+            checked={draft.allowAiAnswerCrawlers !== false}
+            onCheckedChange={(value) => setFlag('allowAiAnswerCrawlers', value)}
+            disabled={!canManage || draft.indexingEnabled === false}
+            aria-label="Allow AI search & answer crawlers"
+            data-testid="seo-robots-ai-answer"
+          />
+        </FormField>
       </div>
 
       <h3 className={styles.previewHeading}>Preview</h3>
-      <div data-testid="seo-robots-preview">
-        <Code className={styles.preview}>{preview}</Code>
-      </div>
+      <SeoCodeViewer docKey="robots-preview" value={preview} language="text" data-testid="seo-robots-preview" />
     </section>
   )
 }
-
-export function SettingSwitch({
-  label,
-  description,
-  checked,
-  disabled,
-  onChange,
-  testId,
-}: {
-  label: string
-  description: string
-  checked: boolean
-  disabled: boolean
-  onChange: (value: boolean) => void
-  testId: string
-}) {
-  return (
-    <div className={styles.switchRow}>
-      <Switch
-        checked={checked}
-        onCheckedChange={onChange}
-        disabled={disabled}
-        aria-label={label}
-        data-testid={testId}
-      />
-      <div className={styles.switchText}>
-        <span className={styles.switchLabel}>{label}</span>
-        <span className={styles.switchDescription}>{description}</span>
-      </div>
-    </div>
-  )
-}
diff --git a/src/admin/pages/seo/tabs/SettingsTabs.module.css b/src/admin/pages/seo/tabs/SettingsTabs.module.css
index c412c0668..b965bd101 100644
--- a/src/admin/pages/seo/tabs/SettingsTabs.module.css
+++ b/src/admin/pages/seo/tabs/SettingsTabs.module.css
@@ -1,126 +1,103 @@
 /* Shared layout for the Robots.txt and Sitemap settings tabs. */
 
 .tab {
-  display: flex;
-  flex-direction: column;
-  gap: 16px;
-  max-width: 720px;
+    display: flex;
+    flex-direction: column;
+    gap: 18px;
+    max-width: 720px;
 }
 
 .header {
-  display: flex;
-  align-items: flex-start;
-  justify-content: space-between;
-  gap: 12px;
+    display: flex;
+    align-items: flex-start;
+    justify-content: space-between;
+    gap: 12px;
 }
 
 .heading {
-  margin: 0;
-  font-size: 15px;
-  font-weight: 700;
-  color: var(--editor-text-bright);
+    margin: 0;
+    font-size: 16px;
+    font-weight: 700;
+    color: var(--editor-text-bright);
 }
 
 .subheading {
-  margin: 4px 0 0;
-  font-size: 12px;
-  color: var(--editor-text-muted);
+    margin: 4px 0 0;
+    font-size: 12px;
+    color: var(--editor-text-muted);
 }
 
 .error {
-  margin: 0;
-  font-size: 12px;
-  color: var(--editor-danger-text);
+    margin: 0;
+    font-size: 12px;
+    color: var(--editor-danger-text);
 }
 
 .notice {
-  margin: 0;
-  padding: 10px 12px;
-  border-radius: var(--editor-radius);
-  background: var(--editor-surface-3);
-  font-size: 12px;
-  color: var(--editor-warning-text);
+    margin: 0;
+    padding: 10px 12px;
+    border-radius: var(--editor-radius);
+    background: var(--editor-surface-3);
+    font-size: 12px;
+    color: var(--editor-warning-text);
 }
 
 .controls {
-  display: flex;
-  flex-direction: column;
-  gap: 12px;
-}
-
-.switchRow {
-  display: flex;
-  align-items: flex-start;
-  gap: 10px;
-}
-
-.switchText {
-  display: flex;
-  flex-direction: column;
-  gap: 2px;
-}
-
-.switchLabel {
-  font-size: 12px;
-  font-weight: 600;
-  color: var(--editor-text-bright);
-}
-
-.switchDescription {
-  font-size: 11px;
-  color: var(--editor-text-muted);
+    display: flex;
+    flex-direction: column;
+    gap: 14px;
+    background: var(--editor-surface-2);
+    border-radius: 16px;
+    padding: 16px 20px;
 }
 
 .previewHeading {
-  margin: 8px 0 0;
-  font-size: 12px;
-  font-weight: 700;
-  color: var(--editor-text-bright);
-}
-
-.preview {
-  font-size: 11px;
+    margin: 4px 0 0;
+    font-size: 13px;
+    font-weight: 700;
+    color: var(--editor-text-bright);
 }
 
 .counts {
-  margin: 0;
-  font-size: 12px;
-  color: var(--editor-text);
+    margin: 0;
+    font-size: 12px;
+    color: var(--editor-text);
 }
 
 .targetList {
-  display: flex;
-  flex-direction: column;
-  gap: 1px;
-  background: var(--editor-surface);
-  border-radius: 16px;
-  overflow: hidden;
+    display: flex;
+    flex-direction: column;
+    gap: 1px;
+    background: var(--editor-surface);
+    border-radius: 16px;
+    overflow: hidden;
 }
 
 .targetRow {
-  display: flex;
-  align-items: center;
-  gap: 10px;
-  padding: 8px 12px;
-  background: var(--editor-surface-2);
+    display: flex;
+    align-items: center;
+    gap: 12px;
+    padding: 10px 14px;
+    background: var(--editor-surface-2);
 }
 
 .targetTitle {
-  font-size: 12px;
-  font-weight: 600;
-  color: var(--editor-text-bright);
+    font-size: 12px;
+    font-weight: 600;
+    color: var(--editor-text-bright);
 }
 
 .targetRoute {
-  font-size: 11px;
-  color: var(--editor-text-muted);
-  flex: 1;
-  white-space: nowrap;
-  overflow: hidden;
-  text-overflow: ellipsis;
+    font-size: 11px;
+    font-family: var(--font-mono);
+    color: var(--editor-text-muted);
+    flex: 1;
+    white-space: nowrap;
+    overflow: hidden;
+    text-overflow: ellipsis;
 }
 
 .targetNote {
-  font-size: 10px;
-  color: var(--editor-warning-text);
+    font-size: 10px;
+    color: var(--editor-warning-text);
 }
diff --git a/src/admin/pages/seo/tabs/SitemapTab.tsx b/src/admin/pages/seo/tabs/SitemapTab.tsx
index ecdc5d7db..b8f4278a2 100644
--- a/src/admin/pages/seo/tabs/SitemapTab.tsx
+++ b/src/admin/pages/seo/tabs/SitemapTab.tsx
@@ -7,12 +7,12 @@
  * the control is disabled with the reason inline.
  */
 import { useState } from 'react'
-import { Code } from '@ui/components/Code'
 import { Switch } from '@ui/components/Switch'
+import { FormField } from '@ui/components/FormField'
 import { getErrorMessage } from '@core/utils/errorMessage'
 import type { SeoSitemapSettings } from '@core/seo'
 import { SaveControls } from '../components/SeoPreviewEditor'
-import { SettingSwitch } from './RobotsTab'
+import { SeoCodeViewer } from '../components/SeoCodeViewer'
 import type { SeoWorkspace } from '../hooks/useSeoWorkspace'
 import styles from './SettingsTabs.module.css'
 
@@ -86,22 +86,27 @@ export function SitemapTab({ workspace, canManage }: SitemapTabProps) {
       )}
 
       <div className={styles.controls}>
-        <SettingSwitch
+        <FormField
+          layout="inline-end"
           label="Generate sitemap.xml"
           description="Search and answer engines use the sitemap to discover published pages and posts."
-          checked={enabled}
-          disabled={!canManage}
-          onChange={(value) => {
-            setDraft((current) => {
-              const next = { ...current }
-              if (value) delete next.enabled
-              else next.enabled = false
-              return next
-            })
-            if (saveState !== 'idle') setSaveState('idle')
-          }}
-          testId="seo-sitemap-enabled"
-        />
+        >
+          <Switch
+            checked={enabled}
+            disabled={!canManage}
+            onCheckedChange={(value) => {
+              setDraft((current) => {
+                const next = { ...current }
+                if (value) delete next.enabled
+                else next.enabled = false
+                return next
+              })
+              if (saveState !== 'idle') setSaveState('idle')
+            }}
+            aria-label="Generate sitemap.xml"
+            data-testid="seo-sitemap-enabled"
+          />
+        </FormField>
       </div>
 
       <p className={styles.counts} role="status" data-testid="seo-sitemap-counts">
@@ -137,7 +142,7 @@ export function SitemapTab({ workspace, canManage }: SitemapTabProps) {
       )}
 
       <h3 className={styles.previewHeading}>Entry format</h3>
-      <Code className={styles.preview}>{sampleEntry(workspace)}</Code>
+      <SeoCodeViewer docKey="sitemap-sample" value={sampleEntry(workspace)} language="html" />
     </section>
   )
 }
diff --git a/src/admin/pages/site/code-editor/CodeMirrorEditor.tsx b/src/admin/pages/site/code-editor/CodeMirrorEditor.tsx
index bb3cf4298..f4fc9f78b 100644
--- a/src/admin/pages/site/code-editor/CodeMirrorEditor.tsx
+++ b/src/admin/pages/site/code-editor/CodeMirrorEditor.tsx
@@ -273,13 +273,22 @@ interface CodeMirrorEditorProps {
   value: string
   /** Which language extensions to load for highlighting. */
   language: CodeLanguage
-  /** Debounced (250 ms) on every edit, and flushed immediately on docKey switch. */
-  onChange: (content: string) => void
+  /**
+   * Debounced (250 ms) on every edit, and flushed immediately on docKey
+   * switch. Optional for `readOnly` mounts — a viewer has nothing to report.
+   */
+  onChange?: (content: string) => void
   /**
    * Change propagation delay. File editors keep the 250 ms default; modal
    * command surfaces can pass 0 so their primary action never reads stale text.
    */
   changeDelayMs?: number
+  /**
+   * Read-only viewer mode — syntax-highlighted display with selection/copy
+   * but no edits (SEO schema/robots previews, future log viewers). Skips the
+   * update-listener plumbing entirely.
+   */
+  readOnly?: boolean
 }
 
 export default function CodeMirrorEditor({
@@ -288,6 +297,7 @@ export default function CodeMirrorEditor({
   language,
   onChange,
   changeDelayMs = 250,
+  readOnly = false,
 }: CodeMirrorEditorProps) {
   const containerRef = useRef<HTMLDivElement | null>(null)
 
@@ -299,9 +309,9 @@ export default function CodeMirrorEditor({
 
   // Always-current reference to onChange — avoids stale closure inside the CM6
   // updateListener while keeping the main useEffect dep-free.
-  const onChangeRef = useRef(onChange)
+  const onChangeRef = useRef(onChange ?? (() => {}))
   useEffect(() => {
-    onChangeRef.current = onChange
+    onChangeRef.current = onChange ?? (() => {})
   }, [onChange])
 
   // useCallback kept: stable identity for the [flush] useEffect dep array (exhaustive-deps).
@@ -333,6 +343,7 @@ export default function CodeMirrorEditor({
           ...getLanguageExtensions(language),
           readableSyntaxHighlighting,
           achromatic,
+          ...(readOnly ? [EditorState.readOnly.of(true), EditorView.editable.of(false)] : []),
           EditorView.updateListener.of((update) => {
             if (!update.docChanged) return
             const content = update.state.doc.toString()
diff --git a/src/styles/globals.css b/src/styles/globals.css
index 5fdc80427..ca998ae64 100644
--- a/src/styles/globals.css
+++ b/src/styles/globals.css
@@ -387,6 +387,30 @@
     --plugins-hero-tint-a: rgba(35, 92, 72, 0.32);
     --plugins-hero-tint-b: rgba(49, 64, 94, 0.24);
     --canvas-live-scrim: rgba(24, 24, 27, 0.82);
+
+    /* ─── SEO platform-preview palettes ──────────────────────────────────────
+     * 1:1 mock colours for the SEO workspace's live previews. These mirror
+     * the REAL platform dark themes (Google SERP, Facebook link card, X
+     * card), so they are intentionally outside the editor's achromatic
+     * two-layer model — the previews must look like the platforms, not
+     * like the editor. Used only by src/admin/pages/seo/components/. */
+    --seo-serp-bg: #202124;             /* Google dark result background   */
+    --seo-serp-chip: #303134;           /* favicon circle                  */
+    --seo-serp-site: #dadce0;           /* site name line                  */
+    --seo-serp-url: #bdc1c6;            /* breadcrumb URL line             */
+    --seo-serp-title: #8ab4f8;          /* result title (Google blue)      */
+    --seo-serp-text: #bdc1c6;           /* snippet description             */
+    --seo-og-bg: #242526;               /* Facebook card body              */
+    --seo-og-strip: #3a3b3c;            /* Facebook meta strip             */
+    --seo-og-domain: #b0b3b8;           /* uppercase domain line           */
+    --seo-og-title: #e4e6eb;            /* card title                      */
+    --seo-og-text: #b0b3b8;             /* card description                */
+    --seo-og-placeholder: #18191a;      /* missing-image area              */
+    --seo-x-bg: #000000;                /* X card background               */
+    --seo-x-border: #2f3336;            /* X card hairline border          */
+    --seo-x-title: #e7e9ea;             /* X card title                    */
+    --seo-x-text: #71767b;              /* X domain / description          */
+    --seo-x-overlay: rgba(0, 0, 0, 0.77); /* large-image title chip        */
 }
 
 /* Reduced motion support — Constraint from UX Guideline #189 */

From 8e491b2573b4488db9ccabd44b9b5ffc766b076b Mon Sep 17 00:00:00 2001
From: DavidBabinec <hello@davidbabinec.com>
Date: Fri, 12 Jun 2026 14:18:51 +0200
Subject: [PATCH 08/26] feat(seo): index v3, gradient meters, SERP favicon,
 unified preview radii
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Target index refactored onto bare-button list rows (§8.8 — the Button
primitive's fixed heights crushed the two-line layout): pinned Site
defaults card with globe icon, 'Pages · N' group headers with counts,
clean two-line rows (title + mono route / sans descriptor) and a
clickable issues line that jumps to the Issues filter. Google snippet
now renders the configured site favicon. All preview cards share
--panel-radius. Length meters gain a green→amber→red gradient clipped
by fill (true progression) plus a budget tick; preview rail unsticks on
narrow viewports so mobile scrolling isn't trapped.

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
---
 server/handlers/cms/seo.ts                    |   1 +
 src/__tests__/admin/seoWorkspace.test.tsx     |   1 +
 .../button-primitive-usage.test.ts            |   8 ++
 .../seo/components/MetaLengthMeter.module.css |  81 ++++++++-----
 .../pages/seo/components/MetaLengthMeter.tsx  |  24 ++--
 .../components/OpenGraphPreview.module.css    |   2 +-
 .../SearchSnippetPreview.module.css           |   6 +
 .../seo/components/SearchSnippetPreview.tsx   |  10 +-
 .../seo/components/SeoPreviewRail.module.css  |   8 ++
 .../pages/seo/components/SeoPreviewRail.tsx   |   1 +
 .../seo/components/SeoTargetIndex.module.css  | 109 +++++++++++++-----
 .../pages/seo/components/SeoTargetIndex.tsx   |  69 +++++++----
 .../seo/components/XCardPreview.module.css    |   4 +-
 src/admin/pages/seo/hooks/useSeoWorkspace.ts  |   5 +
 src/admin/pages/seo/lib/seoApi.ts             |   1 +
 15 files changed, 234 insertions(+), 96 deletions(-)

diff --git a/server/handlers/cms/seo.ts b/server/handlers/cms/seo.ts
index fa965a02d..87bfdca0c 100644
--- a/server/handlers/cms/seo.ts
+++ b/server/handlers/cms/seo.ts
@@ -135,6 +135,7 @@ async function handleGetTargets(req: Request, db: DbClient): Promise<Response> {
     siteName: site?.name ?? '',
     language: site?.settings.language ?? null,
     publicOrigin: canonicalPublicOrigin(),
+    faviconUrl: site?.settings.faviconUrl ?? null,
     siteSeo: site?.settings.seo ?? null,
     targets: [...pageRows.map(pageRowToTarget), ...postTargets],
   })
diff --git a/src/__tests__/admin/seoWorkspace.test.tsx b/src/__tests__/admin/seoWorkspace.test.tsx
index 865ee9cf0..b24defe55 100644
--- a/src/__tests__/admin/seoWorkspace.test.tsx
+++ b/src/__tests__/admin/seoWorkspace.test.tsx
@@ -71,6 +71,7 @@ const TARGETS_PAYLOAD = {
   siteName: 'Acme',
   language: 'en',
   publicOrigin: 'https://acme.com',
+  faviconUrl: null,
   siteSeo: {
     titlePattern: '{page.title} — {site.name}',
     description: 'Site default description',
diff --git a/src/__tests__/architecture/button-primitive-usage.test.ts b/src/__tests__/architecture/button-primitive-usage.test.ts
index a73db07c0..e58786e13 100644
--- a/src/__tests__/architecture/button-primitive-usage.test.ts
+++ b/src/__tests__/architecture/button-primitive-usage.test.ts
@@ -100,6 +100,14 @@ const ALLOWLIST = new Set([
   // mode toggle's segmented pill pattern and shares the same constraints.
   'admin/pages/content/components/ContentModeToggle/ContentModeToggle.tsx',
 
+  // ── §8.8 SEO target index rows ──────────────────────────────────────────
+  // role="option" rows inside the SEO workspace's role="listbox" target
+  // index: full-width two-line rows (title + route, health dots right) and
+  // the pinned Site defaults card. Button's fixed per-size heights and
+  // white-space: nowrap crush the two-line layout — same rationale as the
+  // §8.1 nav rows and §8.7 listbox options.
+  'admin/pages/seo/components/SeoTargetIndex.tsx',
+
   // ── §8.7 Full-width row disclosure / listbox option custom layouts ──────
   // ColorTokenCard row toggle is a full-width structured row (title + meta,
   // expand caret pattern) — same pattern as §8.2 disclosures but on a
diff --git a/src/admin/pages/seo/components/MetaLengthMeter.module.css b/src/admin/pages/seo/components/MetaLengthMeter.module.css
index bf7989026..7e3e262f2 100644
--- a/src/admin/pages/seo/components/MetaLengthMeter.module.css
+++ b/src/admin/pages/seo/components/MetaLengthMeter.module.css
@@ -1,56 +1,73 @@
 .meter {
-  display: flex;
-  align-items: center;
-  gap: 8px;
+    display: flex;
+    align-items: center;
+    gap: 10px;
 }
 
 .meterInherited {
-  opacity: 0.55;
+    opacity: 0.5;
 }
 
 .track {
-  position: relative;
-  flex: 1;
-  height: 3px;
-  border-radius: 2px;
-  background: var(--editor-surface-4);
-  overflow: hidden;
+    position: relative;
+    flex: 1;
+    height: 4px;
+    border-radius: 2px;
+    background: var(--editor-surface-4);
+    overflow: hidden;
+    --seo-meter-fill: 0%;
+    --seo-meter-gradient-span: 100% 100%;
 }
 
+/* Green → amber → red progression: the gradient is sized to the FULL track
+ * (via --seo-meter-gradient-span) and clipped by the fill width, so the
+ * colour at the fill's leading edge always reflects how close the text is
+ * to the budget. */
 .fill {
-  position: absolute;
-  inset: 0 auto 0 0;
-  width: var(--seo-meter-fill);
-  border-radius: 2px;
+    position: absolute;
+    inset: 0 auto 0 0;
+    width: var(--seo-meter-fill);
+    border-radius: 2px;
+    background-image: linear-gradient(
+        90deg,
+        var(--editor-success-green) 0%,
+        var(--editor-success-green) 55%,
+        var(--editor-warning) 82%,
+        var(--editor-danger) 100%
+    );
+    background-size: var(--seo-meter-gradient-span);
+    background-repeat: no-repeat;
+    transition: width 120ms ease;
 }
 
-.fill_ok {
-  background: var(--editor-success-green);
+.fillOver {
+    background-image: none;
+    background-color: var(--editor-danger);
 }
 
-.fill_amber {
-  background: var(--editor-warning);
-}
-
-.fill_over {
-  background: var(--editor-danger);
+/* Hairline marker at the budget edge so "how much room is left" reads at
+ * a glance even when the bar is short. */
+.budgetTick {
+    position: absolute;
+    top: -1px;
+    bottom: -1px;
+    right: 0;
+    width: 2px;
+    background: var(--editor-border-med);
 }
 
 .count {
-  font-size: 10px;
-  font-variant-numeric: tabular-nums;
-  color: var(--editor-text-muted);
+    font-size: 10px;
+    font-variant-numeric: tabular-nums;
+    color: var(--editor-text-muted);
+    min-width: 44px;
+    text-align: right;
 }
 
 .count_amber {
-  color: var(--editor-warning-text);
+    color: var(--editor-warning-text);
 }
 
 .count_over {
-  color: var(--editor-danger-text);
-}
-
-/* Track reads the fill width from the custom property set inline. */
-.track {
-  --seo-meter-fill: 0%;
+    color: var(--editor-danger-text);
 }
diff --git a/src/admin/pages/seo/components/MetaLengthMeter.tsx b/src/admin/pages/seo/components/MetaLengthMeter.tsx
index d6cdf0e80..a6bbd1cce 100644
--- a/src/admin/pages/seo/components/MetaLengthMeter.tsx
+++ b/src/admin/pages/seo/components/MetaLengthMeter.tsx
@@ -1,9 +1,13 @@
 /**
  * MetaLengthMeter — live character + approximate pixel-width meter for SEO
  * title/description fields, against Google's desktop truncation budgets
- * (~580px title / ~990px description). Zones: ok (≤85%), amber, over.
- * Inherited (placeholder) values render the meter muted — informative but
- * clearly not the user's own text.
+ * (~580px title / ~990px description).
+ *
+ * The fill carries a green → amber → red gradient that is sized to the FULL
+ * track and clipped by the fill width, so the colour genuinely progresses
+ * as the text grows instead of flipping between flat colours. Over budget,
+ * the whole fill turns danger-red. Inherited (placeholder) values render
+ * muted — informative but clearly not the user's own text.
  */
 import { cn } from '@ui/cn'
 import {
@@ -30,6 +34,9 @@ export function MetaLengthMeter({ text, budget, explicit }: MetaLengthMeterProps
   const width = approxPixelWidth(text)
   const zone = meterZone(width, pixelBudget)
   const fillPct = Math.min(100, Math.round((width / pixelBudget) * 100))
+  // The gradient spans the full track: a fill at X% shows the first X% of
+  // it, so colour position always matches budget position.
+  const gradientSpan = fillPct > 0 ? `${Math.round(10000 / fillPct)}% 100%` : '100% 100%'
 
   return (
     <div
@@ -37,11 +44,12 @@ export function MetaLengthMeter({ text, budget, explicit }: MetaLengthMeterProps
       role="status"
       aria-label={`${budget === 'title' ? 'Title' : 'Description'} length: ${text.length} characters, ${zone === 'over' ? 'over' : 'within'} the display budget`}
     >
-      <span
-        className={cn(styles.track)}
-        style={{ '--seo-meter-fill': `${fillPct}%` } as CSSProperties}
-      >
-        <span className={cn(styles.fill, styles[`fill_${zone}`])} />
+      <span className={styles.track}>
+        <span
+          className={cn(styles.fill, zone === 'over' && styles.fillOver)}
+          style={{ '--seo-meter-fill': `${fillPct}%`, '--seo-meter-gradient-span': gradientSpan } as CSSProperties}
+        />
+        <span className={styles.budgetTick} aria-hidden="true" />
       </span>
       <span className={cn(styles.count, styles[`count_${zone}`])}>
         {text.length}/{charGuide}
diff --git a/src/admin/pages/seo/components/OpenGraphPreview.module.css b/src/admin/pages/seo/components/OpenGraphPreview.module.css
index b601faa46..edd47317a 100644
--- a/src/admin/pages/seo/components/OpenGraphPreview.module.css
+++ b/src/admin/pages/seo/components/OpenGraphPreview.module.css
@@ -4,7 +4,7 @@
     display: flex;
     flex-direction: column;
     margin: 0;
-    border-radius: var(--editor-radius);
+    border-radius: var(--panel-radius);
     overflow: hidden;
     background: var(--seo-og-bg);
     font-family: Helvetica, arial, sans-serif;
diff --git a/src/admin/pages/seo/components/SearchSnippetPreview.module.css b/src/admin/pages/seo/components/SearchSnippetPreview.module.css
index b0674eb25..b4dc158ad 100644
--- a/src/admin/pages/seo/components/SearchSnippetPreview.module.css
+++ b/src/admin/pages/seo/components/SearchSnippetPreview.module.css
@@ -33,6 +33,12 @@
     flex-shrink: 0;
 }
 
+.faviconImage {
+    width: 18px;
+    height: 18px;
+    object-fit: contain;
+}
+
 .headText {
     display: flex;
     flex-direction: column;
diff --git a/src/admin/pages/seo/components/SearchSnippetPreview.tsx b/src/admin/pages/seo/components/SearchSnippetPreview.tsx
index 51492367f..89d5f45f4 100644
--- a/src/admin/pages/seo/components/SearchSnippetPreview.tsx
+++ b/src/admin/pages/seo/components/SearchSnippetPreview.tsx
@@ -16,15 +16,21 @@ interface SearchSnippetPreviewProps {
   siteName: string
   origin: string | null
   routePath: string
+  /** Site favicon — shown in the icon circle like the real SERP. */
+  faviconUrl: string | null
 }
 
-export function SearchSnippetPreview({ resolved, siteName, origin, routePath }: SearchSnippetPreviewProps) {
+export function SearchSnippetPreview({ resolved, siteName, origin, routePath, faviconUrl }: SearchSnippetPreviewProps) {
   const siteLabel = serpSiteLabel(siteName, origin)
   return (
     <figure className={styles.serp} aria-label="Google search result preview">
       <div className={styles.head}>
         <span className={styles.favicon} aria-hidden="true">
-          {siteLabel.slice(0, 1).toUpperCase()}
+          {faviconUrl ? (
+            <img className={styles.faviconImage} src={faviconUrl} alt="" />
+          ) : (
+            siteLabel.slice(0, 1).toUpperCase()
+          )}
         </span>
         <span className={styles.headText}>
           <span className={styles.site}>{siteLabel}</span>
diff --git a/src/admin/pages/seo/components/SeoPreviewRail.module.css b/src/admin/pages/seo/components/SeoPreviewRail.module.css
index 1a91b3634..235b8087f 100644
--- a/src/admin/pages/seo/components/SeoPreviewRail.module.css
+++ b/src/admin/pages/seo/components/SeoPreviewRail.module.css
@@ -8,6 +8,14 @@
     min-width: 0;
 }
 
+/* Single-column layouts (the workbench collapses at 1100px): a sticky rail
+ * would pin the previews over the form while scrolling — unstick it. */
+@media (max-width: 1100px) {
+    .rail {
+        position: static;
+    }
+}
+
 .block {
     display: flex;
     flex-direction: column;
diff --git a/src/admin/pages/seo/components/SeoPreviewRail.tsx b/src/admin/pages/seo/components/SeoPreviewRail.tsx
index 5b55f8714..f0d580109 100644
--- a/src/admin/pages/seo/components/SeoPreviewRail.tsx
+++ b/src/admin/pages/seo/components/SeoPreviewRail.tsx
@@ -41,6 +41,7 @@ export function SeoPreviewRail({ resolved, workspace, routePath, schemaTarget }:
           siteName={workspace.siteName}
           origin={workspace.publicOrigin}
           routePath={routePath}
+          faviconUrl={workspace.faviconUrl}
         />
       </section>
 
diff --git a/src/admin/pages/seo/components/SeoTargetIndex.module.css b/src/admin/pages/seo/components/SeoTargetIndex.module.css
index 1426bcfbe..8e7c5a897 100644
--- a/src/admin/pages/seo/components/SeoTargetIndex.module.css
+++ b/src/admin/pages/seo/components/SeoTargetIndex.module.css
@@ -5,16 +5,23 @@
     min-width: 0;
 }
 
-.summary {
-    margin: 0;
-    font-size: 11px;
+.issuesLine {
+    align-self: flex-start;
+    gap: 6px;
     color: var(--editor-warning-text);
 }
 
+.issuesDot {
+    width: 6px;
+    height: 6px;
+    border-radius: 50%;
+    background: var(--editor-warning);
+}
+
 .scroller {
     display: flex;
     flex-direction: column;
-    gap: 14px;
+    gap: 16px;
     outline: none;
 }
 
@@ -23,23 +30,51 @@
     box-shadow: 0 0 0 2px var(--editor-focus-ring);
 }
 
-/* Pinned site-defaults card — its own rounded tile above the groups. */
-.siteRow {
-    display: flex;
+/* ── Shared row reset — §8.8 bare buttons ────────────────────────────────── */
+.row,
+.siteCard {
+    appearance: none;
+    border: 0;
+    margin: 0;
+    font: inherit;
+    cursor: pointer;
+    width: 100%;
+    text-align: left;
+    color: var(--editor-text);
+}
+
+/* ── Pinned Site defaults card ───────────────────────────────────────────── */
+.siteCard {
+    display: grid;
+    grid-template-columns: auto minmax(0, 1fr) auto;
     align-items: center;
-    justify-content: space-between;
     gap: 10px;
-    width: 100%;
     padding: 12px 14px;
     border-radius: var(--panel-radius);
     background: var(--editor-surface-2);
-    text-align: left;
+    transition: background 120ms ease;
 }
 
-.siteRow:hover {
+.siteCard:hover {
     background: var(--editor-surface-3);
 }
 
+.siteCardIcon {
+    display: flex;
+    align-items: center;
+    justify-content: center;
+    width: 28px;
+    height: 28px;
+    border-radius: var(--editor-radius);
+    background: var(--editor-surface-4);
+    color: var(--editor-text);
+}
+
+.siteCardChevron {
+    color: var(--editor-text-subtle);
+}
+
+/* ── Groups ──────────────────────────────────────────────────────────────── */
 .group {
     display: flex;
     flex-direction: column;
@@ -47,6 +82,9 @@
 }
 
 .groupLabel {
+    display: flex;
+    align-items: center;
+    gap: 6px;
     margin: 0;
     padding: 0 2px;
     font-size: 10px;
@@ -56,6 +94,11 @@
     color: var(--editor-text-secondary);
 }
 
+.groupCount {
+    font-weight: 500;
+    color: var(--editor-text-subtle);
+}
+
 .groupList {
     display: flex;
     flex-direction: column;
@@ -65,48 +108,58 @@
     overflow: hidden;
 }
 
+/* ── Target rows ─────────────────────────────────────────────────────────── */
 .row {
-    display: flex;
+    display: grid;
+    grid-template-columns: minmax(0, 1fr) auto;
     align-items: center;
-    justify-content: space-between;
     gap: 10px;
-    width: 100%;
-    padding: 10px 14px;
-    border-radius: 0;
+    padding: 9px 13px;
     background: var(--editor-surface-2);
-    text-align: left;
+    transition: background 120ms ease;
 }
 
 .row:hover {
     background: var(--editor-surface-3);
 }
 
-.rowSelected,
-.rowSelected:hover {
+.selected,
+.selected:hover {
     background: var(--editor-surface-4);
     box-shadow: inset 2px 0 0 var(--editor-accent);
 }
 
-.rowMain {
+.rowText {
     display: flex;
     flex-direction: column;
-    gap: 2px;
+    gap: 1px;
     min-width: 0;
 }
 
 .rowTitle {
-    font-size: 12px;
+    font-size: 12.5px;
     font-weight: 600;
+    line-height: 17px;
     color: var(--editor-text-bright);
     white-space: nowrap;
     overflow: hidden;
     text-overflow: ellipsis;
 }
 
-.rowSub {
-    font-size: 11px;
+.rowRoute {
+    font-size: 10.5px;
+    line-height: 15px;
     font-family: var(--font-mono);
-    color: var(--editor-text-muted);
+    color: var(--editor-text-subtle);
+    white-space: nowrap;
+    overflow: hidden;
+    text-overflow: ellipsis;
+}
+
+.rowDescriptor {
+    font-size: 11px;
+    line-height: 15px;
+    color: var(--editor-text-subtle);
     white-space: nowrap;
     overflow: hidden;
     text-overflow: ellipsis;
@@ -114,13 +167,13 @@
 
 .dots {
     display: inline-flex;
-    gap: 3px;
+    gap: 4px;
     flex-shrink: 0;
 }
 
 .dot {
-    width: 6px;
-    height: 6px;
+    width: 5px;
+    height: 5px;
     border-radius: 50%;
 }
 
diff --git a/src/admin/pages/seo/components/SeoTargetIndex.tsx b/src/admin/pages/seo/components/SeoTargetIndex.tsx
index d587e1e65..78a343fbd 100644
--- a/src/admin/pages/seo/components/SeoTargetIndex.tsx
+++ b/src/admin/pages/seo/components/SeoTargetIndex.tsx
@@ -1,15 +1,20 @@
 /**
  * SeoTargetIndex — the Meta tab's right column: navigation + audit context.
  *
- * Search, kind filters, an issues summary chip, the pinned Site defaults
- * card, then the targets grouped under Pages / Templates / Posts section
- * headers — each row shows title, mono route, and per-field health dots.
- * Keyboard: ↑/↓ move the selection, `/` focuses search.
+ * Search, kind filters, a clickable issues line, the pinned Site defaults
+ * card (globe icon), then targets grouped under "Pages · N" style section
+ * headers. Rows are bare <button> list rows (§8.8 in
+ * `button-primitive-usage.test.ts`) — two lines (title + route/descriptor)
+ * with per-field health dots on the right; the Button primitive's fixed
+ * heights and nowrap cannot host this layout. Keyboard: ↑/↓ move the
+ * selection, `/` focuses search.
  */
 import { useRef, useState, type KeyboardEvent } from 'react'
 import { SearchBar } from '@ui/components/SearchBar'
 import { SegmentedControl } from '@ui/components/SegmentedControl'
 import { Button } from '@ui/components/Button'
+import { GlobeSolidIcon } from 'pixel-art-icons/icons/globe-solid'
+import { ChevronRightIcon } from 'pixel-art-icons/icons/chevron-right'
 import { computeSeoHealth, type SeoHealth } from '@core/seo'
 import { cn } from '@ui/cn'
 import type { SeoTarget } from '../lib/seoApi'
@@ -119,10 +124,18 @@ export function SeoTargetIndex({ workspace, selectedId, siteDefaultsId, onSelect
         data-testid="seo-target-filter"
       />
 
-      {issueCount > 0 && (
-        <p className={styles.summary} role="status">
-          {issueCount} {issueCount === 1 ? 'target needs' : 'targets need'} attention
-        </p>
+      {issueCount > 0 && filter !== 'issues' && (
+        <Button
+          type="button"
+          variant="ghost"
+          size="xs"
+          className={styles.issuesLine}
+          onClick={() => setFilter('issues')}
+          data-testid="seo-issues-line"
+        >
+          <span className={styles.issuesDot} aria-hidden="true" />
+          <span>{issueCount} {issueCount === 1 ? 'target needs' : 'targets need'} attention</span>
+        </Button>
       )}
 
       <div
@@ -132,24 +145,31 @@ export function SeoTargetIndex({ workspace, selectedId, siteDefaultsId, onSelect
         tabIndex={0}
         onKeyDown={handleListKeyDown}
       >
-        <Button
+        {/* §8.8 — pinned card + rows are bare <button> list rows. */}
+        <button
           type="button"
-          variant="ghost"
-          className={cn(styles.siteRow, selectedId === siteDefaultsId && styles.rowSelected)}
+          className={cn(styles.siteCard, selectedId === siteDefaultsId && styles.selected)}
           role="option"
           aria-selected={selectedId === siteDefaultsId}
           onClick={() => onSelect(siteDefaultsId)}
           data-testid="seo-target-site-defaults"
         >
-          <span className={styles.rowMain}>
+          <span className={styles.siteCardIcon} aria-hidden="true">
+            <GlobeSolidIcon size={14} />
+          </span>
+          <span className={styles.rowText}>
             <span className={styles.rowTitle}>Site defaults</span>
-            <span className={styles.rowSub}>Fallbacks for every target</span>
+            <span className={styles.rowDescriptor}>Fallbacks for every target</span>
           </span>
-        </Button>
+          <ChevronRightIcon size={11} aria-hidden="true" className={styles.siteCardChevron} />
+        </button>
 
         {groups.map((group) => (
           <div key={group.label} className={styles.group}>
-            <h3 className={styles.groupLabel}>{group.label}</h3>
+            <h3 className={styles.groupLabel}>
+              {group.label}
+              <span className={styles.groupCount}>{group.items.length}</span>
+            </h3>
             <div className={styles.groupList}>
               {group.items.map(({ target, health }) => (
                 <TargetRow
@@ -183,23 +203,26 @@ function TargetRow({
   onSelect: () => void
 }) {
   return (
-    <Button
+    <button
       type="button"
-      variant="ghost"
-      className={cn(styles.row, selected && styles.rowSelected)}
+      className={cn(styles.row, selected && styles.selected)}
       role="option"
       aria-selected={selected}
       onClick={onSelect}
       data-testid={`seo-target-${target.id}`}
     >
-      <span className={styles.rowMain}>
+      <span className={styles.rowText}>
         <span className={styles.rowTitle}>{target.title}</span>
-        <span className={styles.rowSub}>
-          {target.route ?? (target.kind === 'template' ? `Entry template${target.tableSlug ? ` · ${target.tableSlug}` : ''}` : '—')}
-        </span>
+        {target.route !== null ? (
+          <span className={styles.rowRoute}>{target.route}</span>
+        ) : (
+          <span className={styles.rowDescriptor}>
+            Entry template{target.tableSlug ? ` · ${target.tableSlug}` : ''}
+          </span>
+        )}
       </span>
       <HealthDots health={health} />
-    </Button>
+    </button>
   )
 }
 
diff --git a/src/admin/pages/seo/components/XCardPreview.module.css b/src/admin/pages/seo/components/XCardPreview.module.css
index dbfe452eb..271ed6afc 100644
--- a/src/admin/pages/seo/components/XCardPreview.module.css
+++ b/src/admin/pages/seo/components/XCardPreview.module.css
@@ -11,7 +11,7 @@
 /* ── summary_large_image ─────────────────────────────────────────────────── */
 .largeCard {
     position: relative;
-    border-radius: 16px;
+    border-radius: var(--panel-radius);
     border: 1px solid var(--seo-x-border);
     overflow: hidden;
     background: var(--seo-x-bg);
@@ -61,7 +61,7 @@
 .summaryCard {
     display: grid;
     grid-template-columns: 96px minmax(0, 1fr);
-    border-radius: 16px;
+    border-radius: var(--panel-radius);
     border: 1px solid var(--seo-x-border);
     overflow: hidden;
     background: var(--seo-x-bg);
diff --git a/src/admin/pages/seo/hooks/useSeoWorkspace.ts b/src/admin/pages/seo/hooks/useSeoWorkspace.ts
index cd2305a0c..abe2f0f6e 100644
--- a/src/admin/pages/seo/hooks/useSeoWorkspace.ts
+++ b/src/admin/pages/seo/hooks/useSeoWorkspace.ts
@@ -24,6 +24,8 @@ export interface SeoWorkspace {
   siteName: string
   language: string | null
   publicOrigin: string | null
+  /** Site favicon — rendered in the Google snippet preview's icon circle. */
+  faviconUrl: string | null
   siteSeo: SiteSeoSettings | null
   targets: SeoTarget[]
   /** Context bundle for `resolveTargetSeo` / health computation. */
@@ -40,6 +42,7 @@ export function useSeoWorkspace(): SeoWorkspace {
   const [siteName, setSiteName] = useState('')
   const [language, setLanguage] = useState<string | null>(null)
   const [publicOrigin, setPublicOrigin] = useState<string | null>(null)
+  const [faviconUrl, setFaviconUrl] = useState<string | null>(null)
   const [siteSeo, setSiteSeo] = useState<SiteSeoSettings | null>(null)
   const [targets, setTargets] = useState<SeoTarget[]>([])
 
@@ -52,6 +55,7 @@ export function useSeoWorkspace(): SeoWorkspace {
         setSiteName(payload.siteName)
         setLanguage(payload.language)
         setPublicOrigin(payload.publicOrigin)
+        setFaviconUrl(payload.faviconUrl)
         setSiteSeo(payload.siteSeo)
         setTargets(payload.targets)
         setError(null)
@@ -83,6 +87,7 @@ export function useSeoWorkspace(): SeoWorkspace {
     siteName,
     language,
     publicOrigin,
+    faviconUrl,
     siteSeo,
     targets,
     resolveContext: { siteName, language, publicOrigin, siteSeo, targets },
diff --git a/src/admin/pages/seo/lib/seoApi.ts b/src/admin/pages/seo/lib/seoApi.ts
index b9214b95f..991c82f14 100644
--- a/src/admin/pages/seo/lib/seoApi.ts
+++ b/src/admin/pages/seo/lib/seoApi.ts
@@ -39,6 +39,7 @@ export const SeoTargetsResponseSchema = Type.Object({
   siteName: Type.String(),
   language: Type.Union([Type.String(), Type.Null()]),
   publicOrigin: Type.Union([Type.String(), Type.Null()]),
+  faviconUrl: Type.Union([Type.String(), Type.Null()]),
   siteSeo: Type.Union([SiteSeoSettingsSchema, Type.Null()]),
   targets: Type.Array(SeoTargetSchema),
 })

From 70c61e477ae1a57d57d7e4f69e4937dd0da84f60 Mon Sep 17 00:00:00 2001
From: DavidBabinec <hello@davidbabinec.com>
Date: Fri, 12 Jun 2026 14:21:09 +0200
Subject: [PATCH 09/26] fix(seo): say 'goes live on publish' in the Meta tab
 save status
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

'Saved' alone read as 'live on the site' — it isn't: SEO follows the
publish lifecycle (Layer A bakes heads at publish time). The save status
now states it, matching the Robots/Sitemap tab subheadings.

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
---
 src/admin/pages/seo/components/SeoPreviewEditor.tsx | 4 +++-
 1 file changed, 3 insertions(+), 1 deletion(-)

diff --git a/src/admin/pages/seo/components/SeoPreviewEditor.tsx b/src/admin/pages/seo/components/SeoPreviewEditor.tsx
index 2f9a4d4be..6530a85f8 100644
--- a/src/admin/pages/seo/components/SeoPreviewEditor.tsx
+++ b/src/admin/pages/seo/components/SeoPreviewEditor.tsx
@@ -279,9 +279,11 @@ export function SaveControls({
   canManage: boolean
   onSave: () => void
 }) {
+  // "Saved" alone reads as "live" — it isn't. SEO follows the publish
+  // lifecycle (static pages are baked at publish time), so say so.
   const statusText =
     state === 'saving' ? 'Saving…'
-    : state === 'saved' && !dirty ? 'Saved'
+    : state === 'saved' && !dirty ? 'Saved — goes live on publish'
     : dirty ? 'Unsaved changes' : ''
   return (
     <div className={styles.saveControls}>

From 48a332e7306a6e59fcc3dd4747aac3c8c5c9ac17 Mon Sep 17 00:00:00 2001
From: DavidBabinec <hello@davidbabinec.com>
Date: Fri, 12 Jun 2026 15:16:07 +0200
Subject: [PATCH 10/26] feat(seo): toolbar publish and scored control-center
 Meta tab
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Save/publish moves out of the editor headers into the workspace toolbar,
matching the Site and Content workspaces: the active editor (target,
site defaults, robots, sitemap) registers on a save bridge and SeoToolbar
renders the shared PublishActionGroup (status dot, Save & publish split
button, Save draft / Open live URL menu). Posts publish through the
incremental row endpoint; everything else runs the step-up-gated full
site publish — the same machinery as the Site toolbar.

The Meta tab becomes a control center driven by a new core report engine
(computeSeoReport): weighted per-target checks with a 0-100 score, a
site-wide scoreboard with the LiquidProgressRing (promoted to a shared
@ui primitive with amber/danger tones) and coverage tiles, tiered score
pills in the target index, a live score chip, and a clickable
improvements list that focuses the field each issue describes.

Length meters get an ideal band: green is reserved for the 30-60 /
70-160 character bands instead of lighting up from the first character,
and inherited placeholder values render muted with an Inherited/Missing
tag instead of a bogus character count. The editor form switches to a
two-column grid (muted labels left, controls right, large section
headings).

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
---
 docs/features/dashboard.md                    |   7 +-
 docs/features/seo.md                          |  51 +++--
 docs/reference/ui-primitives.md               |   1 +
 src/__tests__/admin/seoWorkspace.test.tsx     | 105 ++++++++-
 .../button-primitive-usage.test.ts            |   9 +-
 .../dashboard/components/OnboardingPanel.tsx  |   2 +-
 src/admin/pages/seo/SeoPage.tsx               |  22 +-
 .../seo/components/MetaLengthMeter.module.css |  67 ++++--
 .../pages/seo/components/MetaLengthMeter.tsx  |  57 +++--
 .../seo/components/SeoImageField.module.css   |  21 +-
 .../pages/seo/components/SeoImageField.tsx    |   5 +-
 .../components/SeoPreviewEditor.module.css    | 122 ++++++++--
 .../pages/seo/components/SeoPreviewEditor.tsx | 210 ++++++++++++------
 .../seo/components/SeoScoreChip.module.css    |  39 ++++
 .../pages/seo/components/SeoScoreChip.tsx     |  23 ++
 .../seo/components/SeoScoreboard.module.css   | 125 +++++++++++
 .../pages/seo/components/SeoScoreboard.tsx    | 116 ++++++++++
 .../seo/components/SeoTargetIndex.module.css  |  35 +--
 .../pages/seo/components/SeoTargetIndex.tsx   |  98 ++++----
 src/admin/pages/seo/components/SeoToolbar.tsx | 111 +++++++++
 .../seo/components/SiteDefaultsEditor.tsx     |  60 +++--
 src/admin/pages/seo/hooks/useSeoDraft.ts      |  30 +--
 src/admin/pages/seo/hooks/useSeoSaveBridge.ts |  91 ++++++++
 src/admin/pages/seo/lib/indexTargets.ts       |  24 ++
 src/admin/pages/seo/tabs/MetaTab.module.css   |   6 +
 src/admin/pages/seo/tabs/MetaTab.tsx          |  96 ++++----
 src/admin/pages/seo/tabs/RobotsTab.tsx        |  51 ++++-
 src/admin/pages/seo/tabs/SitemapTab.tsx       |  51 ++++-
 src/core/seo/__tests__/health.test.ts         |  99 ++++++---
 src/core/seo/health.ts                        | 190 ++++++++++++----
 src/core/seo/index.ts                         |  17 +-
 src/core/seo/lengthMeter.ts                   |  22 +-
 .../LiquidProgressRing.module.css             |  14 +-
 .../LiquidProgressRing.tsx                    | 105 +++++++--
 src/ui/components/LiquidProgressRing/index.ts |   2 +
 35 files changed, 1679 insertions(+), 405 deletions(-)
 create mode 100644 src/admin/pages/seo/components/SeoScoreChip.module.css
 create mode 100644 src/admin/pages/seo/components/SeoScoreChip.tsx
 create mode 100644 src/admin/pages/seo/components/SeoScoreboard.module.css
 create mode 100644 src/admin/pages/seo/components/SeoScoreboard.tsx
 create mode 100644 src/admin/pages/seo/components/SeoToolbar.tsx
 create mode 100644 src/admin/pages/seo/hooks/useSeoSaveBridge.ts
 create mode 100644 src/admin/pages/seo/lib/indexTargets.ts
 rename src/{admin/pages/dashboard/components => ui/components/LiquidProgressRing}/LiquidProgressRing.module.css (94%)
 rename src/{admin/pages/dashboard/components => ui/components/LiquidProgressRing}/LiquidProgressRing.tsx (74%)
 create mode 100644 src/ui/components/LiquidProgressRing/index.ts

diff --git a/docs/features/dashboard.md b/docs/features/dashboard.md
index 401d0ec60..97cad611a 100644
--- a/docs/features/dashboard.md
+++ b/docs/features/dashboard.md
@@ -30,10 +30,9 @@ src/admin/pages/dashboard/
 │   ├── DashboardGrid.module.css — the 1px-gap pattern + customize-mode transitions
 │   ├── BlockLibrary.tsx         — bottom-docked dock of unused widgets in customize mode
 │   ├── BlockLibrary.module.css
-│   ├── OnboardingPanel.tsx      — first-run setup checklist
-│   ├── OnboardingPanel.module.css
-│   ├── LiquidProgressRing.tsx   — animated liquid-filled ring (onboarding completion)
-│   └── LiquidProgressRing.module.css
+│   ├── OnboardingPanel.tsx      — first-run setup checklist (completion ring:
+│   │                              the shared @ui LiquidProgressRing primitive)
+│   └── OnboardingPanel.module.css
 ├── hooks/
 │   ├── useDashboardLayout.ts    — layout state (positions / sizes) + DnD + resize math
 │   ├── useDashboardStats.ts     — fetches /admin/api/cms/dashboard
diff --git a/docs/features/seo.md b/docs/features/seo.md
index 56623ba77..e35c008b2 100644
--- a/docs/features/seo.md
+++ b/docs/features/seo.md
@@ -21,8 +21,8 @@ One engine module owns everything: **`src/core/seo/`** (barrel-gated).
 | `jsonLd.ts` | `buildJsonLdEntities` (`WebSite`, `Organization`, `Article`, `BreadcrumbList`) + `serializeJsonLd` (escapes `</script`, `<!--`) |
 | `robots.ts` | `generateRobotsTxt` — shared by the server endpoint and the admin live preview (byte-identical) |
 | `aiCrawlers.ts` | The AI-crawler user-agent lists behind the Robots tab's two toggles |
-| `health.ts` | `computeSeoHealth` — the index dots / issue chips |
-| `lengthMeter.ts` | Approximate pixel-width metering (~580px title / ~990px description budgets) |
+| `health.ts` | `computeSeoReport` — per-target weighted checks + 0–100 score (`aggregateSeoScore`, `seoScoreTier` for the site-wide rollup and good/fair/poor tiers) |
+| `lengthMeter.ts` | Approximate pixel-width metering with an ideal band (~580px title / ~990px description budgets; "ok" only between the too-short minimum and the budget) |
 
 ### Storage
 
@@ -37,7 +37,7 @@ One engine module owns everything: **`src/core/seo/`** (barrel-gated).
 ### Resolution — two-stage title
 
 `resolveSeoMetadata` is shared by the publisher, the admin previews, and the
-health indicators — what the editor shows IS what gets emitted.
+score reports — what the editor shows IS what gets emitted.
 
 ```
 baseTitle  = target.seo.title ?? row/page title
@@ -101,16 +101,30 @@ lifecycle (edit → publish → live).
 `/admin/plugins/:pluginId/:pageId` routes are unchanged — only nav grouping
 moved).
 
-- **Meta tab** — right: target index (search, All/Pages/Posts/Templates/Issues
-  filters, issue summary chips, per-field health dots, ↑/↓/Enter + `/`
-  keyboard nav, pinned Site defaults row). Left: sticky preview editor with
-  Search / Open Graph / X / Schema platform views. Controlled
-  `Input`/`Textarea` primitives (no contentEditable); empty fields show their
-  RESOLVED fallback as placeholder; title/description carry pixel meters;
-  images pick from the media library; X fields hide behind "Customize X
-  preview" until set; switching targets while dirty asks via an in-app
-  dialog. The Schema view pretty-prints the exact JSON-LD the publisher will
-  emit.
+Save/publish lives in the **toolbar**, like the Site and Content workspaces:
+the active editor (target editor, site defaults, robots, sitemap) registers
+itself on a save bridge (`hooks/useSeoSaveBridge.ts`) and `SeoToolbar`
+renders the shared `PublishActionGroup` (status dot, split "Save & publish"
+button, Save draft + Open live URL menu). Posts publish through the
+incremental row endpoint; everything else runs the step-up-gated full site
+publish — the same machinery as the Site toolbar, not a parallel path.
+
+- **Meta tab** — top: scoreboard — site-wide SEO score in a
+  `LiquidProgressRing` (tier-toned liquid) plus coverage tiles (search
+  snippets / social cards / indexable / needs-work with a jump to the issues
+  filter), computed from one shared `indexSeoTargets` pass. Right: target
+  index (search, All/Pages/Posts/Templates/Issues filters, tiered score
+  pills per row, ↑/↓/Enter + `/` keyboard nav, pinned Site defaults row).
+  Left: sticky preview editor with Search / Open Graph / X / Schema platform
+  views, a live score chip, and a clickable improvements list (each row
+  focuses the field it describes). Controlled `Input`/`Textarea` primitives
+  (no contentEditable); empty fields show their RESOLVED fallback as
+  placeholder; title/description carry ideal-band pixel meters (green only
+  inside the band; inherited values render muted with an Inherited/Missing
+  tag instead of character counts); images pick from the media library; X
+  fields hide behind "Customize X preview" until set; switching targets
+  while dirty asks via an in-app dialog. The Schema view pretty-prints the
+  exact JSON-LD the publisher will emit.
 - **Robots.txt tab** — indexing + AI-crawler toggles over a live preview
   generated by the same `generateRobotsTxt` the endpoint serves.
 - **Sitemap tab** — enable/disable, inclusion counts, per-target
@@ -138,14 +152,17 @@ auto-saves.
 | `PUT /seo/site` | `seo.manage` | Site defaults + robots + sitemap settings (one object) |
 | `POST /seo/generate` | `seo.manage` + `ai.chat` | AI suggestions |
 
-`seo.read` gates the workspace; `seo.manage` gates writes. Health indicators
-are computed client-side with the shared core resolver, so the index, the
-editor, and the published output agree by construction.
+`seo.read` gates the workspace; `seo.manage` gates writes. Publishing
+additionally requires the real publish capability for the scope
+(`content.publish.*` for post rows, `pages.publish` for the site publish).
+Score reports are computed client-side with the shared core resolver, so the
+scoreboard, the index, the editor, and the published output agree by
+construction.
 
 ## Tests
 
 - `src/core/seo/__tests__/` — resolver fallback chains, JSON-LD building +
-  escaping, robots generation, health.
+  escaping, robots generation, score reports.
 - `src/__tests__/publisher/render.test.ts` — emitted head tags.
 - `src/__tests__/server/seoEndpoints.test.ts` — robots/sitemap endpoints +
   version caching.
diff --git a/docs/reference/ui-primitives.md b/docs/reference/ui-primitives.md
index 52883a401..aa4a07667 100644
--- a/docs/reference/ui-primitives.md
+++ b/docs/reference/ui-primitives.md
@@ -73,6 +73,7 @@ Every interactive control in `src/admin/` goes through one of these. Bare `<butt
 | `Image`                    | Image with built-in blurhash fallback                        | `src`, `blurhash`, `alt`, `width`, `height`              |
 | `CanvasModulePlaceholder`  | Diagonal-stripe placeholder for empty modules on the canvas  | `label`                                                  |
 | `Kbd`                      | Single keyboard keycap. Use anywhere a key name appears as a hint. | `children`, `className`                             |
+| `LiquidProgressRing`       | Animated liquid-filled progress ring — onboarding completion, the SEO site score. Tier the liquid with `tone`; override the centered fraction with `label`. | `value`, `total`, `size?`, `tone?: 'mint' \| 'amber' \| 'danger'`, `label?`, `ariaLabel?` |
 | `ShortcutKeys`             | Full shortcut sequence ("⌘K", "Ctrl+Shift+P") — splits the label into individual `Kbd` spans. | `label`, `aria-hidden`, `className` |
 
 ### Loading / skeleton
diff --git a/src/__tests__/admin/seoWorkspace.test.tsx b/src/__tests__/admin/seoWorkspace.test.tsx
index b24defe55..8f54db268 100644
--- a/src/__tests__/admin/seoWorkspace.test.tsx
+++ b/src/__tests__/admin/seoWorkspace.test.tsx
@@ -14,10 +14,13 @@ import { afterEach, describe, expect, it } from 'bun:test'
 import { cleanup, fireEvent, render, screen, waitFor, within } from '@testing-library/react'
 import { MemoryRouter } from '@admin/lib/routing'
 import { AdminSessionProvider } from '@admin/session'
+import { StepUpProvider } from '@admin/shared/StepUp'
 import { AdminSectionNavigation } from '@admin/shared/AdminSectionNavigation'
 import { MetaTab } from '@admin/pages/seo/tabs/MetaTab'
 import { RobotsTab } from '@admin/pages/seo/tabs/RobotsTab'
+import { SeoToolbar } from '@admin/pages/seo/components/SeoToolbar'
 import { useSeoWorkspace } from '@admin/pages/seo/hooks/useSeoWorkspace'
+import { useSeoSaveBridge } from '@admin/pages/seo/hooks/useSeoSaveBridge'
 import type { CmsCurrentUser } from '@core/persistence'
 
 const originalFetch = globalThis.fetch
@@ -135,6 +138,32 @@ function mockSeoFetch(): FetchCall[] {
       const stored = TARGETS_PAYLOAD.targets.find((t) => t.id === id)!
       return json({ target: { ...stored, seo: body.seo } })
     }
+    if (url.match(/^\/admin\/api\/cms\/data\/rows\/[^/]+\/publish$/) && init?.method === 'POST') {
+      const id = url.split('/').at(-2)!
+      // RowEnvelope validates a full DataRow shape — return one.
+      return json({
+        row: {
+          id,
+          tableId: 'posts',
+          cells: { title: 'Hello world', slug: 'hello-world' },
+          slug: 'hello-world',
+          status: 'published',
+          authorUserId: null,
+          createdByUserId: null,
+          updatedByUserId: null,
+          publishedByUserId: null,
+          author: null,
+          createdBy: null,
+          updatedBy: null,
+          publishedBy: null,
+          createdAt: now,
+          updatedAt: now,
+          publishedAt: now,
+          scheduledPublishAt: null,
+          deletedAt: null,
+        },
+      })
+    }
     if (url === '/admin/api/cms/seo/site' && init?.method === 'PUT') {
       const body = JSON.parse(String(init.body)) as { seo: Record<string, unknown> }
       return json({ seo: body.seo })
@@ -144,23 +173,39 @@ function mockSeoFetch(): FetchCall[] {
   return calls
 }
 
+/**
+ * Mirrors SeoPage's wiring: the tab registers on the save bridge and the
+ * toolbar's PublishActionGroup drives it — without the AdminPageLayout
+ * chrome the page itself adds.
+ */
 function MetaHarness({ canManage = true }: { canManage?: boolean }) {
   const workspace = useSeoWorkspace()
+  const bridge = useSeoSaveBridge()
   if (workspace.loading) return <p>Loading…</p>
-  return <MetaTab workspace={workspace} canManage={canManage} />
+  return (
+    <>
+      <SeoToolbar status={bridge.status} onSave={bridge.save} onPublish={bridge.publish} />
+      <MetaTab workspace={workspace} canManage={canManage} bridge={bridge} />
+    </>
+  )
 }
 
 function RobotsHarness() {
   const workspace = useSeoWorkspace()
+  const bridge = useSeoSaveBridge()
   if (workspace.loading) return <p>Loading…</p>
-  return <RobotsTab workspace={workspace} canManage />
+  return <RobotsTab workspace={workspace} canManage bridge={bridge} />
 }
 
-function renderWithSession(node: React.ReactElement, capabilities: string[] = ['seo.read', 'seo.manage', 'ai.chat']) {
+function renderWithSession(node: React.ReactElement, capabilities: string[] = ['seo.read', 'seo.manage', 'ai.chat', 'pages.publish', 'content.publish.any']) {
   return render(
     <MemoryRouter initialEntries={['/admin/tools/seo']}>
       <AdminSessionProvider user={currentUser(capabilities)}>
-        {node}
+        {/* The real app provides StepUpProvider in AuthenticatedAdmin — the
+            SEO editors consume useStepUp for the publish action. */}
+        <StepUpProvider>
+          {node}
+        </StepUpProvider>
       </AdminSessionProvider>
     </MemoryRouter>,
   )
@@ -206,7 +251,9 @@ describe('SEO Meta tab', () => {
     fireEvent.change(within(editor).getByLabelText('Description'), {
       target: { value: 'The Acme homepage.' },
     })
-    fireEvent.click(screen.getByTestId('seo-save'))
+    // Save draft lives in the toolbar's publish-actions menu, like Content.
+    fireEvent.click(screen.getByTestId('toolbar-publish-actions-trigger'))
+    fireEvent.click(screen.getByTestId('toolbar-seo-save-draft'))
 
     await waitFor(() => {
       const put = calls.find(
@@ -237,6 +284,54 @@ describe('SEO Meta tab', () => {
     expect(xTitle.placeholder).toBe('About Acme')
   })
 
+  it('saves then publishes a post through the row publish endpoint', async () => {
+    const calls = mockSeoFetch()
+    renderWithSession(<MetaHarness />)
+
+    fireEvent.click(await screen.findByTestId('seo-target-row_hello'))
+    const editor = await screen.findByRole('region', { name: 'SEO for Hello world' })
+    fireEvent.change(within(editor).getByLabelText('Title'), { target: { value: 'Published title' } })
+
+    fireEvent.click(screen.getByTestId('toolbar-publish-btn'))
+    await screen.findByText('Published — live')
+
+    const put = calls.find(
+      (call) => String(call.input) === '/admin/api/cms/seo/targets/post/row_hello' && call.init?.method === 'PUT',
+    )
+    expect(put).toBeDefined()
+    const publish = calls.find(
+      (call) => String(call.input) === '/admin/api/cms/data/rows/row_hello/publish' && call.init?.method === 'POST',
+    )
+    expect(publish).toBeDefined()
+  })
+
+  it('renders the scoreboard and jumps the index to the issues filter', async () => {
+    mockSeoFetch()
+    renderWithSession(<MetaHarness />)
+
+    // Site-wide score ring + live per-target score chip in the editor.
+    await screen.findByLabelText(/Site SEO score: \d+ out of 100/)
+    expect(screen.getByTestId('seo-score-chip')).toBeDefined()
+
+    // Every seeded target has at least one open check, so the review action
+    // is present; clicking it narrows the index to issue targets only.
+    fireEvent.click(screen.getByTestId('seo-scoreboard-review-issues'))
+    expect(screen.queryByTestId('seo-issues-line')).toBeNull()
+    expect(screen.getByTestId('seo-target-page_home')).toBeDefined()
+  })
+
+  it('clicking an improvement focuses the field it describes', async () => {
+    mockSeoFetch()
+    renderWithSession(<MetaHarness />)
+
+    fireEvent.click(await screen.findByTestId('seo-target-page_about'))
+    const editor = await screen.findByRole('region', { name: 'SEO for About' })
+
+    // "About Acme" has no social image — the improvement row points at it.
+    fireEvent.click(within(editor).getByTestId('seo-improvement-socialImage'))
+    expect(document.activeElement).toBe(within(editor).getByLabelText('OG image URL'))
+  })
+
   it('guards target switching while the editor is dirty', async () => {
     mockSeoFetch()
     renderWithSession(<MetaHarness />)
diff --git a/src/__tests__/architecture/button-primitive-usage.test.ts b/src/__tests__/architecture/button-primitive-usage.test.ts
index e58786e13..769e55606 100644
--- a/src/__tests__/architecture/button-primitive-usage.test.ts
+++ b/src/__tests__/architecture/button-primitive-usage.test.ts
@@ -102,12 +102,19 @@ const ALLOWLIST = new Set([
 
   // ── §8.8 SEO target index rows ──────────────────────────────────────────
   // role="option" rows inside the SEO workspace's role="listbox" target
-  // index: full-width two-line rows (title + route, health dots right) and
+  // index: full-width two-line rows (title + route, score pill right) and
   // the pinned Site defaults card. Button's fixed per-size heights and
   // white-space: nowrap crush the two-line layout — same rationale as the
   // §8.1 nav rows and §8.7 listbox options.
   'admin/pages/seo/components/SeoTargetIndex.tsx',
 
+  // ── §8.11 SEO improvements advice rows ──────────────────────────────────
+  // The Meta editor's improvements list renders full-width rows (status dot
+  // + wrapping two-line advice text) that focus the field they describe.
+  // Button's fixed heights and white-space: nowrap cannot host wrapping
+  // multi-line row content — same pattern class as the §8.8 index rows.
+  'admin/pages/seo/components/SeoPreviewEditor.tsx',
+
   // ── §8.7 Full-width row disclosure / listbox option custom layouts ──────
   // ColorTokenCard row toggle is a full-width structured row (title + meta,
   // expand caret pattern) — same pattern as §8.2 disclosures but on a
diff --git a/src/admin/pages/dashboard/components/OnboardingPanel.tsx b/src/admin/pages/dashboard/components/OnboardingPanel.tsx
index 4b71f2e11..c6c59e446 100644
--- a/src/admin/pages/dashboard/components/OnboardingPanel.tsx
+++ b/src/admin/pages/dashboard/components/OnboardingPanel.tsx
@@ -38,7 +38,7 @@ import { useAdminUi } from '@admin/state/adminUi'
 import { Button } from '@ui/components/Button'
 import type { PixelArtIconComponent } from '@core/dashboard'
 import type { OnboardingFacts, OnboardingStepState } from '../hooks/useOnboardingState'
-import { LiquidProgressRing } from './LiquidProgressRing'
+import { LiquidProgressRing } from '@ui/components/LiquidProgressRing'
 import styles from './OnboardingPanel.module.css'
 
 interface StepDef {
diff --git a/src/admin/pages/seo/SeoPage.tsx b/src/admin/pages/seo/SeoPage.tsx
index 7fd18f858..abc5b3293 100644
--- a/src/admin/pages/seo/SeoPage.tsx
+++ b/src/admin/pages/seo/SeoPage.tsx
@@ -2,13 +2,19 @@
  * SeoPage — `/admin/tools/seo`.
  *
  * The SEO & AEO workspace: per-target metadata editing with live 1:1
- * platform previews (Meta tab), generated robots.txt with AI-crawler
- * controls (Robots.txt tab), and sitemap generation settings (Sitemap tab).
+ * platform previews and a scored control-center overview (Meta tab),
+ * generated robots.txt with AI-crawler controls (Robots.txt tab), and
+ * sitemap generation settings (Sitemap tab).
  *
  * Tab chrome matches the sibling AI / Users / Account pages: the same
  * capability-gated Button row passed through AdminPageLayout's `tabs` slot
  * (§T.6 in `no-plugin-tab-shells.test.ts`).
  *
+ * Save/publish lives in the TOOLBAR, like the Site and Content workspaces:
+ * the active editor registers itself on the save bridge
+ * (`useSeoSaveBridge`), and `SeoToolbar` renders the shared
+ * PublishActionGroup in the layout's `toolbarRightSlot`.
+ *
  * Capabilities: `seo.read` gates the workspace (enforced by
  * `canAccessWorkspace`); `seo.manage` gates every write — tabs receive
  * `canManage` and disable their editing affordances with inline reasons.
@@ -22,7 +28,9 @@ import { useCurrentAdminUser } from '@admin/sessionContext'
 import { MetaTab } from './tabs/MetaTab'
 import { RobotsTab } from './tabs/RobotsTab'
 import { SitemapTab } from './tabs/SitemapTab'
+import { SeoToolbar } from './components/SeoToolbar'
 import { useSeoWorkspace } from './hooks/useSeoWorkspace'
+import { useSeoSaveBridge } from './hooks/useSeoSaveBridge'
 import styles from './SeoPage.module.css'
 
 type Tab = 'meta' | 'robots' | 'sitemap'
@@ -42,6 +50,7 @@ export function SeoPage() {
 
   const [tab, setTab] = useState<Tab>('meta')
   const workspace = useSeoWorkspace()
+  const bridge = useSeoSaveBridge()
 
   const tabs = (
     <div role="tablist" aria-label="SEO sections" className={styles.tabsRow}>
@@ -69,15 +78,18 @@ export function SeoPage() {
       titleId="seo-title"
       description="Search and answer-engine optimization: metadata, social cards, structured data, robots, and sitemap."
       tabs={tabs}
+      toolbarRightSlot={(
+        <SeoToolbar status={bridge.status} onSave={bridge.save} onPublish={bridge.publish} />
+      )}
       loading={workspace.loading}
     >
       {workspace.error ? (
         <p className={styles.loadError} role="alert">{workspace.error}</p>
       ) : (
         <div className={styles.body}>
-          {tab === 'meta' && <MetaTab workspace={workspace} canManage={canManage} />}
-          {tab === 'robots' && <RobotsTab workspace={workspace} canManage={canManage} />}
-          {tab === 'sitemap' && <SitemapTab workspace={workspace} canManage={canManage} />}
+          {tab === 'meta' && <MetaTab workspace={workspace} canManage={canManage} bridge={bridge} />}
+          {tab === 'robots' && <RobotsTab workspace={workspace} canManage={canManage} bridge={bridge} />}
+          {tab === 'sitemap' && <SitemapTab workspace={workspace} canManage={canManage} bridge={bridge} />}
         </div>
       )}
     </AdminPageLayout>
diff --git a/src/admin/pages/seo/components/MetaLengthMeter.module.css b/src/admin/pages/seo/components/MetaLengthMeter.module.css
index 7e3e262f2..3f336dd5b 100644
--- a/src/admin/pages/seo/components/MetaLengthMeter.module.css
+++ b/src/admin/pages/seo/components/MetaLengthMeter.module.css
@@ -16,33 +16,46 @@
     background: var(--editor-surface-4);
     overflow: hidden;
     --seo-meter-fill: 0%;
-    --seo-meter-gradient-span: 100% 100%;
+    --seo-meter-ideal-start: 45%;
 }
 
-/* Green → amber → red progression: the gradient is sized to the FULL track
- * (via --seo-meter-gradient-span) and clipped by the fill width, so the
- * colour at the fill's leading edge always reflects how close the text is
- * to the budget. */
+/* The ideal band — a faint green segment from the too-short threshold to
+ * the budget tick, visible through and around the fill so "where the text
+ * should land" reads before a single character is typed. */
+.idealBand {
+    position: absolute;
+    inset: 0 0 0 var(--seo-meter-ideal-start);
+    background: var(--editor-success-tint-12);
+}
+
+/* Zone-colored fill: neutral while too short — green is RESERVED for the
+ * ideal band — then amber near the budget and red over it. */
 .fill {
     position: absolute;
     inset: 0 auto 0 0;
     width: var(--seo-meter-fill);
     border-radius: 2px;
-    background-image: linear-gradient(
-        90deg,
-        var(--editor-success-green) 0%,
-        var(--editor-success-green) 55%,
-        var(--editor-warning) 82%,
-        var(--editor-danger) 100%
-    );
-    background-size: var(--seo-meter-gradient-span);
-    background-repeat: no-repeat;
-    transition: width 120ms ease;
+    transition: width 120ms ease, background-color 120ms ease;
+}
+
+.fill_empty {
+    background: transparent;
+}
+
+.fill_short {
+    background: var(--editor-border-strong);
+}
+
+.fill_ok {
+    background: var(--editor-success-green);
+}
+
+.fill_amber {
+    background: var(--editor-warning);
 }
 
-.fillOver {
-    background-image: none;
-    background-color: var(--editor-danger);
+.fill_over {
+    background: var(--editor-danger);
 }
 
 /* Hairline marker at the budget edge so "how much room is left" reads at
@@ -64,6 +77,14 @@
     text-align: right;
 }
 
+.count_short {
+    color: var(--editor-text-muted);
+}
+
+.count_ok {
+    color: var(--editor-success-text-soft);
+}
+
 .count_amber {
     color: var(--editor-warning-text);
 }
@@ -71,3 +92,13 @@
 .count_over {
     color: var(--editor-danger-text);
 }
+
+.inheritedTag {
+    font-size: 9px;
+    font-weight: 600;
+    letter-spacing: 0.07em;
+    text-transform: uppercase;
+    color: var(--editor-text-subtle);
+    min-width: 44px;
+    text-align: right;
+}
diff --git a/src/admin/pages/seo/components/MetaLengthMeter.tsx b/src/admin/pages/seo/components/MetaLengthMeter.tsx
index a6bbd1cce..4a2331a8a 100644
--- a/src/admin/pages/seo/components/MetaLengthMeter.tsx
+++ b/src/admin/pages/seo/components/MetaLengthMeter.tsx
@@ -3,18 +3,23 @@
  * title/description fields, against Google's desktop truncation budgets
  * (~580px title / ~990px description).
  *
- * The fill carries a green → amber → red gradient that is sized to the FULL
- * track and clipped by the fill width, so the colour genuinely progresses
- * as the text grows instead of flipping between flat colours. Over budget,
- * the whole fill turns danger-red. Inherited (placeholder) values render
- * muted — informative but clearly not the user's own text.
+ * The track shows the IDEAL BAND (a faint green segment between the
+ * too-short threshold and the budget tick); the fill is colored by zone —
+ * neutral while too short, green only inside the band, amber approaching
+ * the budget, red over it. So the bar reads "not enough yet" instead of
+ * rewarding two characters with a green light.
+ *
+ * Inherited (placeholder) values render muted with an "Inherited" tag and
+ * NO character count — the numbers belong to the user's own text only.
  */
 import { cn } from '@ui/cn'
 import {
   approxPixelWidth,
   meterZone,
   TITLE_PIXEL_BUDGET,
+  TITLE_PIXEL_MIN,
   DESCRIPTION_PIXEL_BUDGET,
+  DESCRIPTION_PIXEL_MIN,
   TITLE_CHAR_GUIDE,
   DESCRIPTION_CHAR_GUIDE,
 } from '@core/seo'
@@ -28,32 +33,48 @@ interface MetaLengthMeterProps {
   explicit: boolean
 }
 
+const ZONE_HINT = {
+  empty: 'empty',
+  short: 'too short',
+  ok: 'in the ideal band',
+  amber: 'near the display budget',
+  over: 'over the display budget',
+} as const
+
 export function MetaLengthMeter({ text, budget, explicit }: MetaLengthMeterProps) {
   const pixelBudget = budget === 'title' ? TITLE_PIXEL_BUDGET : DESCRIPTION_PIXEL_BUDGET
+  const pixelMin = budget === 'title' ? TITLE_PIXEL_MIN : DESCRIPTION_PIXEL_MIN
   const charGuide = budget === 'title' ? TITLE_CHAR_GUIDE : DESCRIPTION_CHAR_GUIDE
   const width = approxPixelWidth(text)
-  const zone = meterZone(width, pixelBudget)
+  const zone = meterZone(width, pixelBudget, pixelMin)
   const fillPct = Math.min(100, Math.round((width / pixelBudget) * 100))
-  // The gradient spans the full track: a fill at X% shows the first X% of
-  // it, so colour position always matches budget position.
-  const gradientSpan = fillPct > 0 ? `${Math.round(10000 / fillPct)}% 100%` : '100% 100%'
+  const idealStartPct = Math.round((pixelMin / pixelBudget) * 100)
 
   return (
     <div
       className={cn(styles.meter, !explicit && styles.meterInherited)}
       role="status"
-      aria-label={`${budget === 'title' ? 'Title' : 'Description'} length: ${text.length} characters, ${zone === 'over' ? 'over' : 'within'} the display budget`}
+      aria-label={
+        explicit
+          ? `${budget === 'title' ? 'Title' : 'Description'} length: ${text.length} characters, ${ZONE_HINT[zone]}`
+          : `${budget === 'title' ? 'Title' : 'Description'} ${text === '' ? 'has no value yet' : 'uses the inherited value'}`
+      }
     >
-      <span className={styles.track}>
-        <span
-          className={cn(styles.fill, zone === 'over' && styles.fillOver)}
-          style={{ '--seo-meter-fill': `${fillPct}%`, '--seo-meter-gradient-span': gradientSpan } as CSSProperties}
-        />
+      <span
+        className={styles.track}
+        style={{ '--seo-meter-fill': `${fillPct}%`, '--seo-meter-ideal-start': `${idealStartPct}%` } as CSSProperties}
+      >
+        <span className={styles.idealBand} aria-hidden="true" />
+        <span className={cn(styles.fill, styles[`fill_${zone}`])} />
         <span className={styles.budgetTick} aria-hidden="true" />
       </span>
-      <span className={cn(styles.count, styles[`count_${zone}`])}>
-        {text.length}/{charGuide}
-      </span>
+      {explicit ? (
+        <span className={cn(styles.count, styles[`count_${zone}`])}>
+          {text.length}/{charGuide}
+        </span>
+      ) : (
+        <span className={styles.inheritedTag}>{text === '' ? 'Missing' : 'Inherited'}</span>
+      )}
     </div>
   )
 }
diff --git a/src/admin/pages/seo/components/SeoImageField.module.css b/src/admin/pages/seo/components/SeoImageField.module.css
index ed09d6025..3b0e3e0ae 100644
--- a/src/admin/pages/seo/components/SeoImageField.module.css
+++ b/src/admin/pages/seo/components/SeoImageField.module.css
@@ -1,22 +1,33 @@
+/* Mirrors SeoPreviewEditor's two-column field grid — the shared
+ * --seo-label-col is defined on the parent .form. */
 .field {
-    display: flex;
-    flex-direction: column;
-    gap: 6px;
+    display: grid;
+    grid-template-columns: var(--seo-label-col) minmax(0, 1fr);
+    column-gap: 18px;
+    align-items: center;
 }
 
 .label {
-    font-size: 12px;
+    font-size: 12.5px;
     font-weight: 600;
-    color: var(--editor-text);
+    color: var(--editor-text-muted);
 }
 
 .controls {
     display: flex;
     align-items: center;
     gap: 6px;
+    min-width: 0;
 }
 
 .controls > :first-child {
     flex: 1;
     min-width: 0;
 }
+
+@media (max-width: 700px) {
+    .field {
+        grid-template-columns: 1fr;
+        row-gap: 6px;
+    }
+}
diff --git a/src/admin/pages/seo/components/SeoImageField.tsx b/src/admin/pages/seo/components/SeoImageField.tsx
index 872a18426..3621482a1 100644
--- a/src/admin/pages/seo/components/SeoImageField.tsx
+++ b/src/admin/pages/seo/components/SeoImageField.tsx
@@ -21,6 +21,8 @@ const MediaPickerModal = lazy(() =>
 
 interface SeoImageFieldProps {
   label: string
+  /** Id for the URL input — lets the improvements list focus this field. */
+  inputId?: string
   /** Explicit value ('' when inheriting). */
   value: string
   /** Resolved fallback shown when no explicit value is set. */
@@ -29,7 +31,7 @@ interface SeoImageFieldProps {
   onChange: (next: string) => void
 }
 
-export function SeoImageField({ label, value, inheritedValue, disabled, onChange }: SeoImageFieldProps) {
+export function SeoImageField({ label, inputId, value, inheritedValue, disabled, onChange }: SeoImageFieldProps) {
   const [pickerOpen, setPickerOpen] = useState(false)
 
   function handlePick(asset: CmsMediaAsset): void {
@@ -43,6 +45,7 @@ export function SeoImageField({ label, value, inheritedValue, disabled, onChange
       <div className={styles.controls}>
         <Input
           type="text"
+          id={inputId}
           value={value}
           placeholder={inheritedValue ?? 'No image — pick from the library'}
           disabled={disabled}
diff --git a/src/admin/pages/seo/components/SeoPreviewEditor.module.css b/src/admin/pages/seo/components/SeoPreviewEditor.module.css
index 825f1b0ac..f80326629 100644
--- a/src/admin/pages/seo/components/SeoPreviewEditor.module.css
+++ b/src/admin/pages/seo/components/SeoPreviewEditor.module.css
@@ -16,11 +16,14 @@
 .form {
     display: flex;
     flex-direction: column;
-    gap: 14px;
+    gap: 16px;
     background: var(--editor-surface-2);
     border-radius: 16px;
     padding: 20px;
     min-width: 0;
+    /* Shared label-column width for every field row in the form, including
+       the SeoImageField rows rendered inside it. */
+    --seo-label-col: 140px;
 }
 
 .header {
@@ -39,7 +42,7 @@
 
 .headerTitle {
     margin: 0;
-    font-size: 16px;
+    font-size: 18px;
     font-weight: 700;
     color: var(--editor-text-bright);
     white-space: nowrap;
@@ -53,18 +56,66 @@
     font-family: var(--font-mono);
 }
 
-.saveControls {
+/* ── Improvements list — clickable advice rows under the header ─────────── */
+.improvements {
     display: flex;
-    align-items: center;
-    gap: 10px;
+    flex-direction: column;
+    gap: 1px;
+    background: var(--editor-surface);
+    border-radius: var(--panel-radius);
+    overflow: hidden;
+}
+
+/* §8.11 bare-button row: dot + two-line advice text, full width. */
+.improvement {
+    appearance: none;
+    border: 0;
+    margin: 0;
+    font: inherit;
+    cursor: pointer;
+    width: 100%;
+    text-align: left;
+    display: flex;
+    align-items: baseline;
+    gap: 8px;
+    padding: 8px 12px;
+    background: var(--editor-surface-3);
+    color: var(--editor-text);
+    transition: background 120ms ease;
+}
+
+.improvement:hover {
+    background: var(--editor-surface-4);
+}
+
+.improvement:focus-visible {
+    outline: none;
+    box-shadow: inset 0 0 0 2px var(--editor-focus-ring);
+}
+
+.improvementDot {
     flex-shrink: 0;
+    width: 6px;
+    height: 6px;
+    border-radius: 50%;
+    background: var(--editor-warning);
 }
 
-.saveStatus {
-    font-size: 11px;
+.improvementDotFail {
+    background: var(--editor-danger);
+}
+
+.improvementText {
+    font-size: 11.5px;
+    line-height: 1.45;
     color: var(--editor-text-muted);
 }
 
+.improvementText strong {
+    font-weight: 600;
+    color: var(--editor-text);
+}
+
 .error {
     margin: 0;
     font-size: 12px;
@@ -79,19 +130,32 @@
 }
 
 .sectionHeading {
-    margin: 2px 0 0;
-    font-size: 13px;
+    margin: 4px 0 2px;
+    font-size: 17px;
     font-weight: 700;
     color: var(--editor-text-bright);
 }
 
-/* Field shell — mirrors the FormField primitive's stacked layout. The
- * sparkle action rides the label row, which FormField's single label slot
- * can't host, hence the local mirror instead of the wrapper. */
+/* Field shell — two-column grid row: muted label (+ sparkle) on the left,
+ * control + meter/hint stacked on the right. Labels center against the
+ * control block. */
 .field {
-    display: flex;
-    flex-direction: column;
-    gap: 6px;
+    display: grid;
+    grid-template-columns: var(--seo-label-col) minmax(0, 1fr);
+    column-gap: 18px;
+    row-gap: 6px;
+    align-items: center;
+}
+
+.field > * {
+    grid-column: 2;
+    min-width: 0;
+}
+
+.field > .fieldLabelRow,
+.field > .fieldLabel {
+    grid-column: 1;
+    grid-row: 1;
 }
 
 .fieldLabelRow {
@@ -99,13 +163,35 @@
     align-items: center;
     justify-content: space-between;
     gap: 8px;
-    min-height: 20px;
 }
 
 .fieldLabel {
-    font-size: 12px;
+    font-size: 12.5px;
     font-weight: 600;
-    color: var(--editor-text);
+    color: var(--editor-text-muted);
+}
+
+/* noindex row: hint left, switch pinned right — same grid as every field. */
+.switchRow {
+    display: flex;
+    align-items: center;
+    justify-content: space-between;
+    gap: 12px;
+}
+
+@media (max-width: 700px) {
+    .field {
+        grid-template-columns: 1fr;
+    }
+
+    .field > * {
+        grid-column: 1;
+    }
+
+    .field > .fieldLabelRow,
+    .field > .fieldLabel {
+        grid-row: auto;
+    }
 }
 
 .fieldHint {
diff --git a/src/admin/pages/seo/components/SeoPreviewEditor.tsx b/src/admin/pages/seo/components/SeoPreviewEditor.tsx
index 6530a85f8..b9e4be4d3 100644
--- a/src/admin/pages/seo/components/SeoPreviewEditor.tsx
+++ b/src/admin/pages/seo/components/SeoPreviewEditor.tsx
@@ -5,6 +5,16 @@
  * right. One draft, one resolver — every keystroke re-resolves and the rail
  * re-renders, so what's previewed is exactly what the publisher will emit.
  *
+ * The header carries a live score chip and an actionable improvements list
+ * (both recomputed from the draft on every keystroke — fixing a check turns
+ * the score in real time). Each improvement focuses the field it's about.
+ *
+ * Save/publish: the editor registers itself on the workspace save bridge —
+ * the toolbar's PublishActionGroup drives `handleSave` / `handlePublish`.
+ * Posts publish incrementally through the row endpoint; pages/templates go
+ * live with the step-up-gated full site publish, exactly like the Site
+ * toolbar.
+ *
  * Form sections: Search appearance → Social card (Open Graph) → X card
  * (behind the customize gate while inheriting). Controlled Input/Textarea
  * primitives only; empty fields show their resolved fallback as placeholder.
@@ -14,15 +24,22 @@ import { Button } from '@ui/components/Button'
 import { Input, Textarea } from '@ui/components/Input'
 import { Select } from '@ui/components/Select'
 import { Switch } from '@ui/components/Switch'
-import { FormField } from '@ui/components/FormField'
 import { Separator } from '@ui/components/Separator'
 import { getErrorMessage } from '@core/utils/errorMessage'
-import { isSafeCanonicalUrl } from '@core/seo'
+import { isSafeCanonicalUrl, computeSeoReport, type SeoCheckId } from '@core/seo'
+import { publishCmsDataRow, publishCmsDraft } from '@core/persistence'
+import { hasCapability, canPublishContentEntry } from '@admin/access'
+import { useCurrentAdminUser } from '@admin/sessionContext'
+import { StepUpCancelledMessage, useStepUp } from '@admin/shared/StepUp'
+import { cn } from '@ui/cn'
 import type { SeoTarget } from '../lib/seoApi'
 import { resolveTargetSeo, templateForPost } from '../lib/resolveTargetSeo'
 import type { SeoWorkspace } from '../hooks/useSeoWorkspace'
+import type { SeoSaveBridge } from '../hooks/useSeoSaveBridge'
+import { useSeoSaveSurface } from '../hooks/useSeoSaveBridge'
 import { useSeoDraft, normalizeSeoDraft, type SeoDraftField } from '../hooks/useSeoDraft'
 import { SeoPreviewRail } from './SeoPreviewRail'
+import { SeoScoreChip } from './SeoScoreChip'
 import { MetaLengthMeter } from './MetaLengthMeter'
 import { SeoImageField } from './SeoImageField'
 import { AiSuggestionSparkle } from './AiSuggestionBubbles'
@@ -32,35 +49,103 @@ interface SeoPreviewEditorProps {
   target: SeoTarget
   workspace: SeoWorkspace
   canManage: boolean
-  onDirtyChange: (dirty: boolean) => void
+  bridge: SeoSaveBridge
 }
 
-export function SeoPreviewEditor({ target, workspace, canManage, onDirtyChange }: SeoPreviewEditorProps) {
-  const draft = useSeoDraft(target.seo, onDirtyChange)
+/** Field-id suffix each report check focuses when clicked. */
+const CHECK_FIELD: Record<SeoCheckId, SeoDraftField | 'noindex'> = {
+  title: 'title',
+  description: 'description',
+  canonical: 'canonicalUrl',
+  socialImage: 'ogImage',
+  imageAlt: 'ogImageAlt',
+  indexable: 'noindex',
+}
+
+export function SeoPreviewEditor({ target, workspace, canManage, bridge }: SeoPreviewEditorProps) {
+  const draft = useSeoDraft(target.seo)
   const fieldIdBase = useId()
+  const currentUser = useCurrentAdminUser()
+  const { runStepUp } = useStepUp()
+
+  // Posts publish incrementally through the row endpoint; pages/templates go
+  // live with a full site publish (their rendered output lives in the site
+  // snapshot). Both make THIS target's saved SEO live immediately.
+  const canPublish = target.kind === 'post'
+    ? !currentUser || canPublishContentEntry(currentUser, null) || hasCapability(currentUser, 'content.publish.any')
+    : !currentUser || hasCapability(currentUser, 'pages.publish')
 
   const resolved = resolveTargetSeo(target, draft.draft, workspace.resolveContext)
+  const report = computeSeoReport(draft.draft, resolved)
   const template = templateForPost(target, workspace.targets)
   const canonicalValue = draft.draft.canonicalUrl ?? ''
   const canonicalInvalid = canonicalValue !== '' && !isSafeCanonicalUrl(canonicalValue)
   const routePath = target.route ?? '/'
 
-  async function handleSave(): Promise<void> {
+  async function handleSave(): Promise<boolean> {
     if (canonicalInvalid) {
       draft.markError('Canonical URL must be an absolute http(s) URL')
-      return
+      return false
     }
     draft.markSaving()
     try {
       const normalized = normalizeSeoDraft(draft.draft)
       await workspace.saveTarget(target.kind, target.id, normalized)
       draft.markSaved(normalized)
+      return true
     } catch (err) {
       console.error('[seo-page] save failed:', err)
       draft.markError(getErrorMessage(err, 'Could not save SEO metadata'))
+      return false
+    }
+  }
+
+  async function handlePublish(): Promise<void> {
+    if (draft.isDirty || draft.saveState === 'error') {
+      const saved = await handleSave()
+      if (!saved) return
+    }
+    draft.markPublishing()
+    try {
+      if (target.kind === 'post') {
+        await publishCmsDataRow(target.id)
+      } else {
+        // Full site publish — same action as the Site toolbar's Publish
+        // button (step-up gated). Publishes every pending site draft.
+        await runStepUp(() => publishCmsDraft())
+      }
+      draft.markPublished()
+    } catch (err) {
+      // A cancelled step-up is a normal flow, not an error to surface.
+      if (err instanceof Error && err.message === StepUpCancelledMessage) {
+        draft.markSaved(normalizeSeoDraft(draft.draft))
+        return
+      }
+      console.error('[seo-page] publish failed:', err)
+      draft.markError(getErrorMessage(err, 'Could not publish'))
     }
   }
 
+  useSeoSaveSurface(
+    bridge,
+    {
+      dirty: draft.isDirty,
+      state: draft.saveState,
+      canSave: canManage,
+      canPublish,
+      publishScope: target.kind === 'post' ? 'row' : 'site',
+      liveUrl: workspace.publicOrigin && target.route ? `${workspace.publicOrigin}${target.route}` : null,
+    },
+    { save: () => void handleSave(), publish: () => void handlePublish() },
+  )
+
+  function focusCheckField(id: SeoCheckId): void {
+    const element = document.getElementById(`${fieldIdBase}-${CHECK_FIELD[id]}`)
+    if (!element) return
+    element.scrollIntoView({ behavior: 'smooth', block: 'center' })
+    element.focus({ preventScroll: true })
+  }
+
   const xCustomized =
     draft.draft.xTitle !== undefined ||
     draft.draft.xDescription !== undefined ||
@@ -113,7 +198,13 @@ export function SeoPreviewEditor({ target, workspace, canManage, onDirtyChange }
           />
         )}
         {opts?.meterBudget && (
-          <MetaLengthMeter text={value || placeholder || ''} budget={opts.meterBudget} explicit={value !== ''} />
+          /* Inherited values meter against the RESOLVED text, never the
+             input's hint placeholder ("No description — add one…"). */
+          <MetaLengthMeter
+            text={value !== '' ? value : opts.meterBudget === 'title' ? resolved.title : resolved.description ?? ''}
+            budget={opts.meterBudget}
+            explicit={value !== ''}
+          />
         )}
       </div>
     )
@@ -135,6 +226,8 @@ export function SeoPreviewEditor({ target, workspace, canManage, onDirtyChange }
     }
   }
 
+  const openIssues = report.checks.filter((check) => check.status !== 'pass')
+
   return (
     <div className={styles.workbench}>
       <SeoPreviewRail
@@ -152,12 +245,7 @@ export function SeoPreviewEditor({ target, workspace, canManage, onDirtyChange }
               {target.route ?? (target.kind === 'template' ? `Entry template${target.tableSlug ? ` · ${target.tableSlug}` : ''}` : '')}
             </span>
           </div>
-          <SaveControls
-            dirty={draft.isDirty}
-            state={draft.saveState}
-            canManage={canManage}
-            onSave={() => void handleSave()}
-          />
+          <SeoScoreChip score={report.score} />
         </header>
         {draft.saveError && <p className={styles.error} role="alert">{draft.saveError}</p>}
         {!canManage && (
@@ -177,6 +265,31 @@ export function SeoPreviewEditor({ target, workspace, canManage, onDirtyChange }
           </p>
         )}
 
+        {openIssues.length > 0 && (
+          <div className={styles.improvements} role="list" aria-label="Suggested improvements">
+            {openIssues.map((check) => (
+              /* §8.11 — full-width two-line advice rows; see
+                 button-primitive-usage.test.ts ALLOWLIST. */
+              <button
+                key={check.id}
+                type="button"
+                role="listitem"
+                className={styles.improvement}
+                onClick={() => focusCheckField(check.id)}
+                data-testid={`seo-improvement-${check.id}`}
+              >
+                <span
+                  className={cn(styles.improvementDot, check.status === 'fail' && styles.improvementDotFail)}
+                  aria-hidden="true"
+                />
+                <span className={styles.improvementText}>
+                  <strong>{check.label}</strong> — {check.advice}
+                </span>
+              </button>
+            ))}
+          </div>
+        )}
+
         <h3 className={styles.sectionHeading}>Search appearance</h3>
         {field('title', 'Title', { meterBudget: 'title', sparkle: true })}
         {field('description', 'Description', { textarea: true, meterBudget: 'description', sparkle: true })}
@@ -184,19 +297,24 @@ export function SeoPreviewEditor({ target, workspace, canManage, onDirtyChange }
         {canonicalInvalid && (
           <p className={styles.error} role="alert">Canonical URL must be an absolute http(s) URL.</p>
         )}
-        <FormField
-          layout="inline-end"
-          label="Exclude from search engines"
-          description="Emits noindex — the page disappears from search and answer engines."
-        >
-          <Switch
-            checked={draft.draft.noindex === true}
-            onCheckedChange={draft.setNoindex}
-            disabled={!canManage}
-            aria-label="Exclude from search engines (noindex)"
-            switchSize="sm"
-          />
-        </FormField>
+        <div className={styles.field}>
+          <label htmlFor={`${fieldIdBase}-noindex`} className={styles.fieldLabel}>
+            Exclude from search engines
+          </label>
+          <div className={styles.switchRow}>
+            <span className={styles.fieldHint}>
+              Emits noindex — the page disappears from search and answer engines.
+            </span>
+            <Switch
+              id={`${fieldIdBase}-noindex`}
+              checked={draft.draft.noindex === true}
+              onCheckedChange={draft.setNoindex}
+              disabled={!canManage}
+              aria-label="Exclude from search engines (noindex)"
+              switchSize="sm"
+            />
+          </div>
+        </div>
 
         <Separator />
         <h3 className={styles.sectionHeading}>Social card (Open Graph)</h3>
@@ -204,6 +322,7 @@ export function SeoPreviewEditor({ target, workspace, canManage, onDirtyChange }
         {field('ogDescription', 'OG description', { textarea: true, sparkle: true })}
         <SeoImageField
           label="OG image"
+          inputId={`${fieldIdBase}-ogImage`}
           value={draft.draft.ogImage ?? ''}
           inheritedValue={resolved.ogImage ?? null}
           disabled={!canManage}
@@ -266,40 +385,3 @@ export function SeoPreviewEditor({ target, workspace, canManage, onDirtyChange }
     </div>
   )
 }
-
-/** Quiet save affordance: Save button + tiny inline state text. */
-export function SaveControls({
-  dirty,
-  state,
-  canManage,
-  onSave,
-}: {
-  dirty: boolean
-  state: 'idle' | 'saving' | 'saved' | 'error'
-  canManage: boolean
-  onSave: () => void
-}) {
-  // "Saved" alone reads as "live" — it isn't. SEO follows the publish
-  // lifecycle (static pages are baked at publish time), so say so.
-  const statusText =
-    state === 'saving' ? 'Saving…'
-    : state === 'saved' && !dirty ? 'Saved — goes live on publish'
-    : dirty ? 'Unsaved changes' : ''
-  return (
-    <div className={styles.saveControls}>
-      {statusText && (
-        <span className={styles.saveStatus} role="status">{statusText}</span>
-      )}
-      <Button
-        variant="primary"
-        size="sm"
-        disabled={!canManage || !dirty || state === 'saving'}
-        tooltip={!canManage ? 'Your role does not include Manage SEO' : undefined}
-        onClick={onSave}
-        data-testid="seo-save"
-      >
-        Save
-      </Button>
-    </div>
-  )
-}
diff --git a/src/admin/pages/seo/components/SeoScoreChip.module.css b/src/admin/pages/seo/components/SeoScoreChip.module.css
new file mode 100644
index 000000000..6c5619e90
--- /dev/null
+++ b/src/admin/pages/seo/components/SeoScoreChip.module.css
@@ -0,0 +1,39 @@
+.chip {
+    display: inline-flex;
+    align-items: baseline;
+    gap: 6px;
+    flex-shrink: 0;
+    padding: 4px 10px;
+    border-radius: var(--editor-radius);
+}
+
+.value {
+    font-family: var(--font-mono);
+    font-size: 16px;
+    font-weight: 700;
+    line-height: 1.2;
+    font-variant-numeric: tabular-nums;
+}
+
+.caption {
+    font-size: 10px;
+    font-weight: 600;
+    letter-spacing: 0.06em;
+    text-transform: uppercase;
+    opacity: 0.75;
+}
+
+.chip_good {
+    background: var(--editor-success-bg);
+    color: var(--editor-success-text-soft);
+}
+
+.chip_fair {
+    background: var(--editor-warning-bg);
+    color: var(--editor-warning-text);
+}
+
+.chip_poor {
+    background: var(--editor-danger-bg);
+    color: var(--editor-danger-text);
+}
diff --git a/src/admin/pages/seo/components/SeoScoreChip.tsx b/src/admin/pages/seo/components/SeoScoreChip.tsx
new file mode 100644
index 000000000..07a237925
--- /dev/null
+++ b/src/admin/pages/seo/components/SeoScoreChip.tsx
@@ -0,0 +1,23 @@
+/**
+ * SeoScoreChip — compact live score readout for the editor header. Recolors
+ * by tier (green ≥ 80, amber ≥ 50, red below) and updates on every
+ * keystroke, so fixing a check visibly moves the number.
+ */
+import { seoScoreTier } from '@core/seo'
+import { cn } from '@ui/cn'
+import styles from './SeoScoreChip.module.css'
+
+export function SeoScoreChip({ score }: { score: number }) {
+  const tier = seoScoreTier(score)
+  return (
+    <span
+      className={cn(styles.chip, styles[`chip_${tier}`])}
+      role="status"
+      aria-label={`SEO score: ${score} out of 100`}
+      data-testid="seo-score-chip"
+    >
+      <span className={styles.value}>{score}</span>
+      <span className={styles.caption}>SEO score</span>
+    </span>
+  )
+}
diff --git a/src/admin/pages/seo/components/SeoScoreboard.module.css b/src/admin/pages/seo/components/SeoScoreboard.module.css
new file mode 100644
index 000000000..1c61ddc7e
--- /dev/null
+++ b/src/admin/pages/seo/components/SeoScoreboard.module.css
@@ -0,0 +1,125 @@
+/* Borderless card pattern: surface-2 cells over the darker surface parent
+ * with a 1px grid gap, 16px outer radius. */
+.scoreboard {
+    display: grid;
+    grid-template-columns: minmax(280px, 1.6fr) repeat(4, minmax(0, 1fr));
+    gap: 1px;
+    background: var(--editor-surface);
+    border-radius: 16px;
+    overflow: hidden;
+}
+
+.cell {
+    background: var(--editor-surface-2);
+    padding: 16px 18px;
+    min-width: 0;
+}
+
+.scoreCell {
+    display: flex;
+    align-items: center;
+    gap: 18px;
+}
+
+.scoreValue {
+    font-family: var(--font-mono);
+    font-size: 30px;
+    font-weight: 600;
+    letter-spacing: -0.04em;
+    line-height: 1;
+    color: var(--editor-text-bright);
+    text-shadow:
+        0 1px 2px var(--editor-overlay-black-45),
+        0 0 8px var(--editor-overlay-black-25);
+}
+
+.scoreText {
+    display: flex;
+    flex-direction: column;
+    gap: 3px;
+    min-width: 0;
+}
+
+.scoreTitle {
+    margin: 0;
+    font-size: 13px;
+    font-weight: 700;
+    color: var(--editor-text-bright);
+}
+
+.scoreHeadline {
+    margin: 0;
+    font-size: 12px;
+    color: var(--editor-text);
+}
+
+.scoreSub {
+    margin: 0;
+    font-size: 11px;
+    line-height: 1.45;
+    color: var(--editor-text-muted);
+}
+
+/* ── Coverage tiles ──────────────────────────────────────────────────────── */
+.tile {
+    display: flex;
+    flex-direction: column;
+    justify-content: center;
+    gap: 3px;
+    transition: background 120ms ease;
+}
+
+.tile:hover {
+    background: var(--editor-surface-3);
+}
+
+.tileValue {
+    font-family: var(--font-mono);
+    font-size: 22px;
+    font-weight: 600;
+    letter-spacing: -0.03em;
+    line-height: 1.1;
+    color: var(--editor-text-bright);
+}
+
+.tileValue[data-good] {
+    color: var(--editor-success-green);
+}
+
+.tileValue[data-attention] {
+    color: var(--editor-warning);
+}
+
+.tileTotal {
+    font-size: 13px;
+    font-weight: 500;
+    color: var(--editor-text-subtle);
+}
+
+.tileLabel {
+    font-size: 11.5px;
+    font-weight: 600;
+    color: var(--editor-text);
+}
+
+.tileHint {
+    font-size: 10.5px;
+    line-height: 1.4;
+    color: var(--editor-text-muted);
+}
+
+.tileAction {
+    align-self: flex-start;
+    margin-left: -6px;
+    color: var(--editor-warning-text);
+}
+
+@media (max-width: 1100px) {
+    .scoreboard {
+        grid-template-columns: repeat(2, minmax(0, 1fr));
+    }
+
+    .scoreCell {
+        grid-column: 1 / -1;
+    }
+}
diff --git a/src/admin/pages/seo/components/SeoScoreboard.tsx b/src/admin/pages/seo/components/SeoScoreboard.tsx
new file mode 100644
index 000000000..d19468d1e
--- /dev/null
+++ b/src/admin/pages/seo/components/SeoScoreboard.tsx
@@ -0,0 +1,116 @@
+/**
+ * SeoScoreboard — the Meta tab's control-center band: site-wide SEO score
+ * in a liquid-progress ring plus coverage tiles, all derived from the same
+ * per-target reports the index renders.
+ *
+ * Tiles follow the borderless card pattern (surface-2 cells over a darker
+ * surface parent with a 1px grid gap). The issues tile carries the one
+ * action — jump the index to the issues filter.
+ */
+import { Button } from '@ui/components/Button'
+import { LiquidProgressRing } from '@ui/components/LiquidProgressRing'
+import { aggregateSeoScore, seoScoreTier, type SeoCheckId } from '@core/seo'
+import { cn } from '@ui/cn'
+import type { IndexedSeoTarget } from '../lib/indexTargets'
+import styles from './SeoScoreboard.module.css'
+
+interface SeoScoreboardProps {
+  indexed: IndexedSeoTarget[]
+  onReviewIssues: () => void
+}
+
+const TIER_TONE = { good: 'mint', fair: 'amber', poor: 'danger' } as const
+
+const TIER_HEADLINE = {
+  good: 'Looking sharp — keep it green.',
+  fair: 'Solid base — a few targets need attention.',
+  poor: 'Search engines are flying blind — start with titles and descriptions.',
+} as const
+
+function passCount(indexed: IndexedSeoTarget[], ids: SeoCheckId[]): number {
+  return indexed.filter(({ report }) =>
+    ids.every((id) => {
+      const check = report.checks.find((c) => c.id === id)
+      // Omitted checks (alt with no image) don't count as covered.
+      return check !== undefined && check.status === 'pass'
+    }),
+  ).length
+}
+
+export function SeoScoreboard({ indexed, onReviewIssues }: SeoScoreboardProps) {
+  const total = indexed.length
+  const score = aggregateSeoScore(indexed.map(({ report }) => report))
+  const tier = seoScoreTier(score)
+
+  const searchReady = passCount(indexed, ['title', 'description'])
+  const socialReady = passCount(indexed, ['socialImage', 'imageAlt'])
+  const indexable = passCount(indexed, ['indexable'])
+  const issues = indexed.filter(({ report }) => report.issueCount > 0).length
+
+  return (
+    <section className={styles.scoreboard} aria-label="Site SEO score">
+      <div className={cn(styles.cell, styles.scoreCell)}>
+        <LiquidProgressRing
+          value={score}
+          total={100}
+          size={88}
+          tone={TIER_TONE[tier]}
+          label={<span className={styles.scoreValue}>{score}</span>}
+          ariaLabel={`Site SEO score: ${score} out of 100`}
+        />
+        <div className={styles.scoreText}>
+          <h3 className={styles.scoreTitle}>Site SEO score</h3>
+          <p className={styles.scoreHeadline}>{TIER_HEADLINE[tier]}</p>
+          <p className={styles.scoreSub}>
+            Average across {total} {total === 1 ? 'target' : 'targets'} — weighted checks on
+            titles, descriptions, social cards, and indexability.
+          </p>
+        </div>
+      </div>
+
+      <div className={cn(styles.cell, styles.tile)}>
+        <span className={styles.tileValue} data-good={searchReady === total || undefined}>
+          {searchReady}<span className={styles.tileTotal}>/{total}</span>
+        </span>
+        <span className={styles.tileLabel}>Search snippets</span>
+        <span className={styles.tileHint}>Title and description in the ideal band</span>
+      </div>
+
+      <div className={cn(styles.cell, styles.tile)}>
+        <span className={styles.tileValue} data-good={socialReady === total || undefined}>
+          {socialReady}<span className={styles.tileTotal}>/{total}</span>
+        </span>
+        <span className={styles.tileLabel}>Social cards</span>
+        <span className={styles.tileHint}>Image with alt text for link shares</span>
+      </div>
+
+      <div className={cn(styles.cell, styles.tile)}>
+        <span className={styles.tileValue} data-good={indexable === total || undefined}>
+          {indexable}<span className={styles.tileTotal}>/{total}</span>
+        </span>
+        <span className={styles.tileLabel}>Indexable</span>
+        <span className={styles.tileHint}>Visible to search and answer engines</span>
+      </div>
+
+      <div className={cn(styles.cell, styles.tile)}>
+        <span className={styles.tileValue} data-attention={issues > 0 || undefined}>
+          {issues}
+        </span>
+        <span className={styles.tileLabel}>{issues === 1 ? 'Target needs work' : 'Targets need work'}</span>
+        {issues > 0 ? (
+          <Button
+            variant="ghost"
+            size="xs"
+            className={styles.tileAction}
+            onClick={onReviewIssues}
+            data-testid="seo-scoreboard-review-issues"
+          >
+            Review issues
+          </Button>
+        ) : (
+          <span className={styles.tileHint}>Nothing flagged right now</span>
+        )}
+      </div>
+    </section>
+  )
+}
diff --git a/src/admin/pages/seo/components/SeoTargetIndex.module.css b/src/admin/pages/seo/components/SeoTargetIndex.module.css
index 8e7c5a897..b5418e18d 100644
--- a/src/admin/pages/seo/components/SeoTargetIndex.module.css
+++ b/src/admin/pages/seo/components/SeoTargetIndex.module.css
@@ -165,28 +165,33 @@
     text-overflow: ellipsis;
 }
 
-.dots {
-    display: inline-flex;
-    gap: 4px;
+/* Tiered score pill — tinted background + matching text, mono digits. */
+.scorePill {
     flex-shrink: 0;
+    min-width: 26px;
+    padding: 2px 5px;
+    border-radius: var(--editor-radius-sm);
+    font-family: var(--font-mono);
+    font-size: 10.5px;
+    font-weight: 600;
+    line-height: 1.3;
+    text-align: center;
+    font-variant-numeric: tabular-nums;
 }
 
-.dot {
-    width: 5px;
-    height: 5px;
-    border-radius: 50%;
-}
-
-.dot_ok {
-    background: var(--editor-success-green);
+.scorePill_good {
+    background: var(--editor-success-bg);
+    color: var(--editor-success-text-soft);
 }
 
-.dot_warn {
-    background: var(--editor-warning);
+.scorePill_fair {
+    background: var(--editor-warning-bg);
+    color: var(--editor-warning-text);
 }
 
-.dot_bad {
-    background: var(--editor-danger);
+.scorePill_poor {
+    background: var(--editor-danger-bg);
+    color: var(--editor-danger-text);
 }
 
 .empty {
diff --git a/src/admin/pages/seo/components/SeoTargetIndex.tsx b/src/admin/pages/seo/components/SeoTargetIndex.tsx
index 78a343fbd..578e27523 100644
--- a/src/admin/pages/seo/components/SeoTargetIndex.tsx
+++ b/src/admin/pages/seo/components/SeoTargetIndex.tsx
@@ -1,11 +1,12 @@
 /**
  * SeoTargetIndex — the Meta tab's right column: navigation + audit context.
  *
- * Search, kind filters, a clickable issues line, the pinned Site defaults
- * card (globe icon), then targets grouped under "Pages · N" style section
+ * Search, kind filters (lifted to MetaTab so the scoreboard can jump to the
+ * issues view), a clickable issues line, the pinned Site defaults card
+ * (globe icon), then targets grouped under "Pages · N" style section
  * headers. Rows are bare <button> list rows (§8.8 in
  * `button-primitive-usage.test.ts`) — two lines (title + route/descriptor)
- * with per-field health dots on the right; the Button primitive's fixed
+ * with a tiered score pill on the right; the Button primitive's fixed
  * heights and nowrap cannot host this layout. Keyboard: ↑/↓ move the
  * selection, `/` focuses search.
  */
@@ -15,16 +16,15 @@ import { SegmentedControl } from '@ui/components/SegmentedControl'
 import { Button } from '@ui/components/Button'
 import { GlobeSolidIcon } from 'pixel-art-icons/icons/globe-solid'
 import { ChevronRightIcon } from 'pixel-art-icons/icons/chevron-right'
-import { computeSeoHealth, type SeoHealth } from '@core/seo'
+import { seoScoreTier, type SeoReport } from '@core/seo'
 import { cn } from '@ui/cn'
 import type { SeoTarget } from '../lib/seoApi'
-import { resolveTargetSeo } from '../lib/resolveTargetSeo'
-import type { SeoWorkspace } from '../hooks/useSeoWorkspace'
+import type { IndexedSeoTarget } from '../lib/indexTargets'
 import styles from './SeoTargetIndex.module.css'
 
-type Filter = 'all' | 'pages' | 'posts' | 'templates' | 'issues'
+export type SeoTargetFilter = 'all' | 'pages' | 'posts' | 'templates' | 'issues'
 
-const FILTER_OPTIONS: { value: Filter; label: string }[] = [
+const FILTER_OPTIONS: { value: SeoTargetFilter; label: string }[] = [
   { value: 'all', label: 'All' },
   { value: 'pages', label: 'Pages' },
   { value: 'posts', label: 'Posts' },
@@ -32,44 +32,39 @@ const FILTER_OPTIONS: { value: Filter; label: string }[] = [
   { value: 'issues', label: 'Issues' },
 ]
 
-interface IndexedTarget {
-  target: SeoTarget
-  health: SeoHealth
-}
-
 interface TargetGroup {
   label: string
-  items: IndexedTarget[]
+  items: IndexedSeoTarget[]
 }
 
 interface SeoTargetIndexProps {
-  workspace: SeoWorkspace
+  indexed: IndexedSeoTarget[]
+  filter: SeoTargetFilter
+  onFilterChange: (filter: SeoTargetFilter) => void
   selectedId: string
   siteDefaultsId: string
   onSelect: (id: string) => void
 }
 
-export function SeoTargetIndex({ workspace, selectedId, siteDefaultsId, onSelect }: SeoTargetIndexProps) {
+export function SeoTargetIndex({
+  indexed,
+  filter,
+  onFilterChange,
+  selectedId,
+  siteDefaultsId,
+  onSelect,
+}: SeoTargetIndexProps) {
   const [query, setQuery] = useState('')
-  const [filter, setFilter] = useState<Filter>('all')
   const searchRef = useRef<HTMLInputElement>(null)
 
-  const indexed: IndexedTarget[] = workspace.targets.map((target) => ({
-    target,
-    health: computeSeoHealth(
-      target.seo ?? undefined,
-      resolveTargetSeo(target, undefined, workspace.resolveContext),
-    ),
-  }))
-
-  const issueCount = indexed.filter((item) => item.health.issueCount > 0).length
+  const issueCount = indexed.filter((item) => item.report.issueCount > 0).length
 
   const normalizedQuery = query.trim().toLowerCase()
-  const visible = indexed.filter(({ target, health }) => {
+  const visible = indexed.filter(({ target, report }) => {
     if (filter === 'pages' && target.kind !== 'page') return false
     if (filter === 'posts' && target.kind !== 'post') return false
     if (filter === 'templates' && target.kind !== 'template') return false
-    if (filter === 'issues' && health.issueCount === 0) return false
+    if (filter === 'issues' && report.issueCount === 0) return false
     if (normalizedQuery === '') return true
     return (
       target.title.toLowerCase().includes(normalizedQuery) ||
@@ -117,7 +112,7 @@ export function SeoTargetIndex({ workspace, selectedId, siteDefaultsId, onSelect
       <SegmentedControl
         value={filter}
         options={FILTER_OPTIONS}
-        onChange={setFilter}
+        onChange={onFilterChange}
         size="xs"
         fullWidth
         aria-label="Filter targets"
@@ -130,7 +125,7 @@ export function SeoTargetIndex({ workspace, selectedId, siteDefaultsId, onSelect
           variant="ghost"
           size="xs"
           className={styles.issuesLine}
-          onClick={() => setFilter('issues')}
+          onClick={() => onFilterChange('issues')}
           data-testid="seo-issues-line"
         >
           <span className={styles.issuesDot} aria-hidden="true" />
@@ -171,11 +166,11 @@ export function SeoTargetIndex({ workspace, selectedId, siteDefaultsId, onSelect
               <span className={styles.groupCount}>{group.items.length}</span>
             </h3>
             <div className={styles.groupList}>
-              {group.items.map(({ target, health }) => (
+              {group.items.map(({ target, report }) => (
                 <TargetRow
                   key={target.id}
                   target={target}
-                  health={health}
+                  report={report}
                   selected={selectedId === target.id}
                   onSelect={() => onSelect(target.id)}
                 />
@@ -193,12 +188,12 @@ export function SeoTargetIndex({ workspace, selectedId, siteDefaultsId, onSelect
 
 function TargetRow({
   target,
-  health,
+  report,
   selected,
   onSelect,
 }: {
   target: SeoTarget
-  health: SeoHealth
+  report: SeoReport
   selected: boolean
   onSelect: () => void
 }) {
@@ -221,33 +216,28 @@ function TargetRow({
           </span>
         )}
       </span>
-      <HealthDots health={health} />
+      <ScorePill report={report} />
     </button>
   )
 }
 
 /**
- * Compact health indicators: title, description, image, indexing — green
- * when ok, amber for soft issues, red for missing/noindex. Each dot carries
- * a title tooltip naming the field + state for hover discovery.
+ * Tiered score pill: green ≥ 80, amber ≥ 50, red below. The title tooltip
+ * names the open issues for hover discovery.
  */
-function HealthDots({ health }: { health: SeoHealth }) {
+function ScorePill({ report }: { report: SeoReport }) {
+  const tier = seoScoreTier(report.score)
+  const openIssues = report.checks.filter((check) => check.status !== 'pass')
+  const summary = openIssues.length === 0
+    ? 'No SEO issues'
+    : `Needs work: ${openIssues.map((check) => check.label.toLowerCase()).join(', ')}`
   return (
-    <span className={styles.dots} aria-label={healthSummary(health)}>
-      <Dot state={health.title === 'ok' ? 'ok' : health.title === 'long' ? 'warn' : 'bad'} label={`Title: ${health.title}`} />
-      <Dot state={health.description === 'ok' ? 'ok' : health.description === 'long' ? 'warn' : 'bad'} label={`Description: ${health.description}`} />
-      <Dot state={health.image === 'ok' ? 'ok' : health.image === 'missingAlt' ? 'warn' : 'bad'} label={`Social image: ${health.image}`} />
-      <Dot state={health.indexable ? 'ok' : 'bad'} label={health.indexable ? 'Indexable' : 'Noindex'} />
+    <span
+      className={cn(styles.scorePill, styles[`scorePill_${tier}`])}
+      title={summary}
+      aria-label={`SEO score ${report.score}. ${summary}`}
+    >
+      {report.score}
     </span>
   )
 }
-
-function healthSummary(health: SeoHealth): string {
-  return health.issueCount === 0
-    ? 'No SEO issues'
-    : `${health.issueCount} SEO ${health.issueCount === 1 ? 'issue' : 'issues'}`
-}
-
-function Dot({ state, label }: { state: 'ok' | 'warn' | 'bad'; label: string }) {
-  return <span className={cn(styles.dot, styles[`dot_${state}`])} title={label} />
-}
diff --git a/src/admin/pages/seo/components/SeoToolbar.tsx b/src/admin/pages/seo/components/SeoToolbar.tsx
new file mode 100644
index 000000000..a7dc183a5
--- /dev/null
+++ b/src/admin/pages/seo/components/SeoToolbar.tsx
@@ -0,0 +1,111 @@
+/**
+ * SeoToolbar — the SEO workspace's toolbar publish controls, rendered into
+ * AdminPageLayout's `toolbarRightSlot`. Same PublishActionGroup the Site and
+ * Content workspaces use: status dot + split publish button + actions menu
+ * (Save draft / Open live URL), driven by whichever editor currently owns
+ * the save bridge.
+ */
+import { CheckIcon } from 'pixel-art-icons/icons/check'
+import { CircleAlertSolidIcon } from 'pixel-art-icons/icons/circle-alert-solid'
+import { ExternalLinkSolidIcon } from 'pixel-art-icons/icons/external-link-solid'
+import { LoaderIcon } from 'pixel-art-icons/icons/loader'
+import { SaveSolidIcon } from 'pixel-art-icons/icons/save-solid'
+import { SendSolidIcon } from 'pixel-art-icons/icons/send-solid'
+import type { IconComponent } from 'pixel-art-icons/types'
+import {
+  PublishActionGroup,
+  type PublishActionMenuItem,
+  type PublishActionStatusTone,
+} from '@site/toolbar/PublishActionGroup'
+import type { SeoSaveStatus } from '../hooks/useSeoSaveBridge'
+
+interface SeoToolbarProps {
+  status: SeoSaveStatus | null
+  onSave: () => void
+  onPublish: () => void
+}
+
+interface ToolbarViewState {
+  statusText: string | null
+  statusTone: PublishActionStatusTone
+  publishLabel: string
+  PublishIcon: IconComponent
+  publishState: 'idle' | 'busy' | 'success' | 'error'
+}
+
+function deriveViewState(status: SeoSaveStatus): ToolbarViewState {
+  const { state, dirty } = status
+  if (state === 'publishing') {
+    return { statusText: 'Publishing', statusTone: 'neutral', publishLabel: 'Publishing', PublishIcon: LoaderIcon, publishState: 'busy' }
+  }
+  if (state === 'saving') {
+    return { statusText: 'Saving draft', statusTone: 'neutral', publishLabel: 'Publish', PublishIcon: SendSolidIcon, publishState: 'idle' }
+  }
+  if (state === 'error') {
+    return { statusText: 'Failed — details in the editor', statusTone: 'danger', publishLabel: 'Retry publish', PublishIcon: CircleAlertSolidIcon, publishState: 'error' }
+  }
+  if (dirty) {
+    return { statusText: 'Unsaved changes', statusTone: 'warning', publishLabel: 'Save & publish', PublishIcon: SendSolidIcon, publishState: 'idle' }
+  }
+  if (state === 'published') {
+    return { statusText: 'Published — live', statusTone: 'success', publishLabel: 'Published', PublishIcon: CheckIcon, publishState: 'success' }
+  }
+  if (state === 'saved') {
+    return { statusText: 'Saved — goes live on publish', statusTone: 'success', publishLabel: 'Publish', PublishIcon: SendSolidIcon, publishState: 'idle' }
+  }
+  return { statusText: null, statusTone: 'neutral', publishLabel: 'Publish', PublishIcon: SendSolidIcon, publishState: 'idle' }
+}
+
+export function SeoToolbar({ status, onSave, onPublish }: SeoToolbarProps) {
+  if (!status) return null
+
+  const { statusText, statusTone, publishLabel, PublishIcon, publishState } = deriveViewState(status)
+  const busy = status.state === 'saving' || status.state === 'publishing'
+  const cleanPublished = status.state === 'published' && !status.dirty
+
+  const publishTitle = !status.canSave
+    ? 'Your role does not include Manage SEO'
+    : !status.canPublish
+      ? 'Your role does not include publish permissions'
+      : status.publishScope === 'site'
+        ? 'Publishes the whole site draft — same as the Site toolbar'
+        : 'Saves and publishes this entry'
+
+  const menuItems: PublishActionMenuItem[] = [
+    {
+      id: 'save-draft',
+      label: 'Save draft',
+      icon: SaveSolidIcon,
+      disabled: !status.canSave || !status.dirty || busy,
+      onSelect: onSave,
+      testId: 'toolbar-seo-save-draft',
+    },
+    {
+      id: 'open-live',
+      label: 'Open live URL',
+      icon: ExternalLinkSolidIcon,
+      disabled: !status.liveUrl,
+      onSelect: () => {
+        if (!status.liveUrl) return
+        window.open(status.liveUrl, '_blank', 'noopener,noreferrer')
+      },
+      testId: 'toolbar-seo-open-live',
+    },
+  ]
+
+  return (
+    <PublishActionGroup
+      statusLabel={statusText}
+      statusTone={statusTone}
+      publishLabel={publishLabel}
+      publishAriaLabel={cleanPublished ? 'Published' : 'Publish SEO changes'}
+      publishTitle={publishTitle}
+      publishState={publishState}
+      publishBusy={status.state === 'publishing'}
+      publishDisabled={!status.canSave || !status.canPublish || busy || cleanPublished}
+      publishIcon={PublishIcon}
+      onPublish={onPublish}
+      menuItems={menuItems}
+    />
+  )
+}
diff --git a/src/admin/pages/seo/components/SiteDefaultsEditor.tsx b/src/admin/pages/seo/components/SiteDefaultsEditor.tsx
index ae2f4fb42..be6399586 100644
--- a/src/admin/pages/seo/components/SiteDefaultsEditor.tsx
+++ b/src/admin/pages/seo/components/SiteDefaultsEditor.tsx
@@ -8,17 +8,22 @@
  * Organization fields feeding site-wide JSON-LD). Robots/sitemap settings
  * live on the same object but are edited in their own tabs.
  */
-import { useEffect, useId, useState } from 'react'
+import { useId, useState } from 'react'
 import { Input, Textarea } from '@ui/components/Input'
 import { Select } from '@ui/components/Select'
 import { Separator } from '@ui/components/Separator'
 import { getErrorMessage } from '@core/utils/errorMessage'
 import type { SiteSeoSettings } from '@core/seo'
+import { publishCmsDraft } from '@core/persistence'
+import { hasCapability } from '@admin/access'
+import { useCurrentAdminUser } from '@admin/sessionContext'
+import { StepUpCancelledMessage, useStepUp } from '@admin/shared/StepUp'
 import type { SeoWorkspace } from '../hooks/useSeoWorkspace'
+import type { SeoSaveBridge } from '../hooks/useSeoSaveBridge'
+import { useSeoSaveSurface } from '../hooks/useSeoSaveBridge'
 import { resolveTargetSeo } from '../lib/resolveTargetSeo'
 import { SeoPreviewRail } from './SeoPreviewRail'
 import { SeoImageField } from './SeoImageField'
-import { SaveControls } from './SeoPreviewEditor'
 import styles from './SeoPreviewEditor.module.css'
 
 type SiteStringField =
@@ -56,25 +61,22 @@ function sameSiteSeo(a: SiteSeoSettings, b: SiteSeoSettings): boolean {
 interface SiteDefaultsEditorProps {
   workspace: SeoWorkspace
   canManage: boolean
-  onDirtyChange: (dirty: boolean) => void
+  bridge: SeoSaveBridge
 }
 
-export function SiteDefaultsEditor({ workspace, canManage, onDirtyChange }: SiteDefaultsEditorProps) {
+export function SiteDefaultsEditor({ workspace, canManage, bridge }: SiteDefaultsEditorProps) {
   const stored = workspace.siteSeo ?? {}
   const [draft, setDraft] = useState<SiteSeoSettings>(stored)
   const [baseline, setBaseline] = useState<SiteSeoSettings>(stored)
-  const [saveState, setSaveState] = useState<'idle' | 'saving' | 'saved' | 'error'>('idle')
+  const [saveState, setSaveState] = useState<'idle' | 'saving' | 'saved' | 'publishing' | 'published' | 'error'>('idle')
   const [saveError, setSaveError] = useState<string | null>(null)
   const idBase = useId()
+  const currentUser = useCurrentAdminUser()
+  const { runStepUp } = useStepUp()
+  const canPublish = !currentUser || hasCapability(currentUser, 'pages.publish')
 
   const isDirty = !sameSiteSeo(draft, baseline)
 
-  // Parent dirty-guard notification. `onDirtyChange` is a useState setter at
-  // every call site, so including it in the deps adds no extra firings.
-  useEffect(() => {
-    onDirtyChange(isDirty)
-  }, [isDirty, onDirtyChange])
-
   // Rail sample: the homepage (or any page) resolved with the DRAFT defaults
   // overlayed — live "what a typical page inherits" feedback while typing.
   const sampleTarget =
@@ -111,7 +113,7 @@ export function SiteDefaultsEditor({ workspace, canManage, onDirtyChange }: Site
     if (saveState !== 'idle') setSaveState('idle')
   }
 
-  async function handleSave(): Promise<void> {
+  async function handleSave(): Promise<boolean> {
     setSaveState('saving')
     setSaveError(null)
     try {
@@ -120,13 +122,46 @@ export function SiteDefaultsEditor({ workspace, canManage, onDirtyChange }: Site
       setBaseline(normalized)
       setDraft(normalized)
       setSaveState('saved')
+      return true
     } catch (err) {
       console.error('[seo-page] site defaults save failed:', err)
       setSaveState('error')
       setSaveError(getErrorMessage(err, 'Could not save site SEO defaults'))
+      return false
     }
   }
 
+  async function handlePublish(): Promise<void> {
+    if (isDirty && !(await handleSave())) return
+    setSaveState('publishing')
+    try {
+      // Full site publish — step-up gated, same as the Site toolbar.
+      await runStepUp(() => publishCmsDraft())
+      setSaveState('published')
+    } catch (err) {
+      if (err instanceof Error && err.message === StepUpCancelledMessage) {
+        setSaveState('saved')
+        return
+      }
+      console.error('[seo-page] publish failed:', err)
+      setSaveState('error')
+      setSaveError(getErrorMessage(err, 'Could not publish'))
+    }
+  }
+
+  useSeoSaveSurface(
+    bridge,
+    {
+      dirty: isDirty,
+      state: saveState,
+      canSave: canManage,
+      canPublish,
+      publishScope: 'site',
+      liveUrl: workspace.publicOrigin,
+    },
+    { save: () => void handleSave(), publish: () => void handlePublish() },
+  )
+
   return (
     <div className={styles.workbench}>
       {sampleResolved && sampleTarget ? (
@@ -148,7 +183,6 @@ export function SiteDefaultsEditor({ workspace, canManage, onDirtyChange }: Site
               {sampleTarget ? `Previewing “${sampleTarget.title}” with these defaults` : 'Fallbacks for every page and post'}
             </span>
           </div>
-          <SaveControls dirty={isDirty} state={saveState} canManage={canManage} onSave={() => void handleSave()} />
         </header>
         {saveError && <p className={styles.error} role="alert">{saveError}</p>}
         {!canManage && (
diff --git a/src/admin/pages/seo/hooks/useSeoDraft.ts b/src/admin/pages/seo/hooks/useSeoDraft.ts
index 85a2b07f8..fa4628d74 100644
--- a/src/admin/pages/seo/hooks/useSeoDraft.ts
+++ b/src/admin/pages/seo/hooks/useSeoDraft.ts
@@ -3,14 +3,14 @@
  *
  * Field edits stay local until Save; empty strings mean "unset" (the field
  * falls back through the resolver chain), so the persisted object only
- * carries explicit overrides. `isDirty` compares the normalized draft to the
- * stored value, and the parent is notified so target switching can guard
- * against silent discards.
+ * carries explicit overrides. `isDirty` compares the normalized draft to
+ * the stored value; the editor reports it to the workspace save bridge for
+ * the toolbar controls and the target-switch guard.
  */
-import { useEffect, useState } from 'react'
+import { useState } from 'react'
 import type { SeoMetadata } from '@core/seo'
 
-export type SeoSaveState = 'idle' | 'saving' | 'saved' | 'error'
+export type SeoSaveState = 'idle' | 'saving' | 'saved' | 'publishing' | 'published' | 'error'
 
 /** String-valued SeoMetadata keys editable through the snippet inputs. */
 export type SeoDraftField =
@@ -68,13 +68,12 @@ export interface UseSeoDraftResult {
   setNoindex: (value: boolean) => void
   markSaving: () => void
   markSaved: (saved: SeoMetadata) => void
+  markPublishing: () => void
+  markPublished: () => void
   markError: (message: string) => void
 }
 
-export function useSeoDraft(
-  stored: SeoMetadata | null,
-  onDirtyChange: (dirty: boolean) => void,
-): UseSeoDraftResult {
+export function useSeoDraft(stored: SeoMetadata | null): UseSeoDraftResult {
   const [draft, setDraft] = useState<SeoMetadata>(stored ?? {})
   const [baseline, setBaseline] = useState<SeoMetadata>(stored ?? {})
   const [saveState, setSaveState] = useState<SeoSaveState>('idle')
@@ -82,12 +81,6 @@ export function useSeoDraft(
 
   const isDirty = !sameSeo(draft, baseline)
 
-  // Parent dirty-guard notification. `onDirtyChange` is a useState setter at
-  // every call site, so including it in the deps adds no extra firings.
-  useEffect(() => {
-    onDirtyChange(isDirty)
-  }, [isDirty, onDirtyChange])
-
   function update(mutate: (next: SeoMetadata) => void): void {
     setDraft((current) => {
       const next = { ...current }
@@ -132,6 +125,13 @@ export function useSeoDraft(
       setDraft(saved)
       setSaveState('saved')
     },
+    markPublishing: () => {
+      setSaveState('publishing')
+      setSaveError(null)
+    },
+    markPublished: () => {
+      setSaveState('published')
+    },
     markError: (message) => {
       setSaveState('error')
       setSaveError(message)
diff --git a/src/admin/pages/seo/hooks/useSeoSaveBridge.ts b/src/admin/pages/seo/hooks/useSeoSaveBridge.ts
new file mode 100644
index 000000000..acef7f0df
--- /dev/null
+++ b/src/admin/pages/seo/hooks/useSeoSaveBridge.ts
@@ -0,0 +1,91 @@
+/**
+ * useSeoSaveBridge — connects whichever SEO editor is active (target editor,
+ * site defaults, robots, sitemap) to the workspace toolbar's save/publish
+ * controls, mirroring how the Site and Content workspaces drive their
+ * toolbar PublishActionGroup.
+ *
+ * Split deliberately in two channels:
+ *   - `status` is serializable view state (dirty/save-state/capabilities),
+ *     reported through React state so the toolbar re-renders with it.
+ *   - the save/publish handlers flow through a ref private to this hook —
+ *     they change identity every editor render, and the toolbar only needs
+ *     the latest at click time, not a re-render per keystroke. `save` /
+ *     `publish` are stable closures over that ref.
+ *
+ * Editors call `useSeoSaveSurface` once; it reports on change and withdraws
+ * the surface on unmount, so tab/target switches hand the toolbar over
+ * cleanly.
+ */
+import { useEffect, useRef, useState } from 'react'
+import type { SeoSaveState } from './useSeoDraft'
+
+export interface SeoSaveStatus {
+  dirty: boolean
+  state: SeoSaveState
+  /** False when the user lacks `seo.manage` — save is disabled with reason. */
+  canSave: boolean
+  /** False when the user lacks the publish capability for this scope. */
+  canPublish: boolean
+  /** 'row' = incremental post publish; 'site' = step-up gated full publish. */
+  publishScope: 'row' | 'site'
+  /** Public URL the active surface affects, for the "Open live" menu item. */
+  liveUrl: string | null
+}
+
+export interface SeoSaveActions {
+  save: () => void
+  publish: () => void
+}
+
+export interface SeoSaveBridge {
+  status: SeoSaveStatus | null
+  reportStatus: (status: SeoSaveStatus | null) => void
+  /** Latest-handler registration — called by the active editor each render. */
+  setActions: (actions: SeoSaveActions | null) => void
+  /** Invoke the active editor's handlers (no-ops with no surface). */
+  save: () => void
+  publish: () => void
+}
+
+export function useSeoSaveBridge(): SeoSaveBridge {
+  const [status, setStatus] = useState<SeoSaveStatus | null>(null)
+  const actionsRef = useRef<SeoSaveActions | null>(null)
+  // Stable closures over the private ref — one identity for the bridge's
+  // whole lifetime, so registering them in effects costs nothing.
+  const [stable] = useState(() => ({
+    setActions: (actions: SeoSaveActions | null) => {
+      actionsRef.current = actions
+    },
+    save: () => actionsRef.current?.save(),
+    publish: () => actionsRef.current?.publish(),
+  }))
+  return { status, reportStatus: setStatus, ...stable }
+}
+
+/** Register the calling editor as the toolbar's active save surface. */
+export function useSeoSaveSurface(
+  bridge: SeoSaveBridge,
+  status: SeoSaveStatus,
+  actions: SeoSaveActions,
+): void {
+  const { reportStatus, setActions } = bridge
+  const { dirty, state, canSave, canPublish, publishScope, liveUrl } = status
+
+  // Latest-closure pattern: re-registered every render so the toolbar always
+  // invokes handlers that see the current draft.
+  useEffect(() => {
+    setActions(actions)
+  })
+
+  useEffect(() => {
+    reportStatus({ dirty, state, canSave, canPublish, publishScope, liveUrl })
+  }, [reportStatus, dirty, state, canSave, canPublish, publishScope, liveUrl])
+
+  useEffect(
+    () => () => {
+      reportStatus(null)
+      setActions(null)
+    },
+    [reportStatus, setActions],
+  )
+}
diff --git a/src/admin/pages/seo/lib/indexTargets.ts b/src/admin/pages/seo/lib/indexTargets.ts
new file mode 100644
index 000000000..d5f285d1f
--- /dev/null
+++ b/src/admin/pages/seo/lib/indexTargets.ts
@@ -0,0 +1,24 @@
+/**
+ * indexSeoTargets — pair every workspace target with its computed SEO
+ * report. The Meta tab computes this once per render and shares it between
+ * the scoreboard, the target index, and the issues filter so all three
+ * agree on what counts as an issue.
+ */
+import { computeSeoReport, type SeoReport } from '@core/seo'
+import type { SeoTarget } from './seoApi'
+import { resolveTargetSeo, type ResolveTargetSeoContext } from './resolveTargetSeo'
+
+export interface IndexedSeoTarget {
+  target: SeoTarget
+  report: SeoReport
+}
+
+export function indexSeoTargets(
+  targets: SeoTarget[],
+  ctx: ResolveTargetSeoContext,
+): IndexedSeoTarget[] {
+  return targets.map((target) => ({
+    target,
+    report: computeSeoReport(target.seo ?? undefined, resolveTargetSeo(target, undefined, ctx)),
+  }))
+}
diff --git a/src/admin/pages/seo/tabs/MetaTab.module.css b/src/admin/pages/seo/tabs/MetaTab.module.css
index a76fb2667..b6f291fb1 100644
--- a/src/admin/pages/seo/tabs/MetaTab.module.css
+++ b/src/admin/pages/seo/tabs/MetaTab.module.css
@@ -1,3 +1,9 @@
+.layout {
+    display: flex;
+    flex-direction: column;
+    gap: 24px;
+}
+
 .columns {
     display: grid;
     grid-template-columns: minmax(0, 1fr) 300px;
diff --git a/src/admin/pages/seo/tabs/MetaTab.tsx b/src/admin/pages/seo/tabs/MetaTab.tsx
index e1899106b..790fd3e52 100644
--- a/src/admin/pages/seo/tabs/MetaTab.tsx
+++ b/src/admin/pages/seo/tabs/MetaTab.tsx
@@ -1,13 +1,19 @@
 /**
- * MetaTab — the SEO workspace's editing surface.
+ * MetaTab — the SEO workspace's control center.
  *
- * Two persistent columns:
- *   - Left: sticky preview editor. Platform switcher (Search / Open Graph /
- *     X / Schema) over live 1:1 platform previews, editable snippet fields
- *     with inherited-value placeholders and pixel length meters. The pinned
- *     "Site defaults" row opens the site-level editor instead.
- *   - Right: target index — search, kind filters, issues summary chips,
- *     dense rows with per-field health dots, full keyboard navigation.
+ * Three persistent regions:
+ *   - Top: scoreboard — site-wide SEO score in a liquid-progress ring plus
+ *     coverage tiles (search snippets, social cards, indexability, issues),
+ *     all computed from the same per-target reports the index shows.
+ *   - Left: the active editor. Platform previews over editable snippet
+ *     fields with inherited-value placeholders, ideal-band length meters,
+ *     a live per-target score, and an actionable improvements list. The
+ *     pinned "Site defaults" row opens the site-level editor instead.
+ *   - Right: target index — search, kind filters, dense rows with score
+ *     pills, full keyboard navigation.
+ *
+ * Save/publish lives in the workspace toolbar: the active editor registers
+ * itself on the save bridge passed down from SeoPage.
  *
  * The homepage is selected by default so the user lands on a live preview,
  * not an empty defaults form. Switching targets with unsaved changes asks
@@ -18,7 +24,10 @@ import { Button } from '@ui/components/Button'
 import { Dialog } from '@ui/components/Dialog'
 import type { SeoTarget } from '../lib/seoApi'
 import type { SeoWorkspace } from '../hooks/useSeoWorkspace'
-import { SeoTargetIndex } from '../components/SeoTargetIndex'
+import type { SeoSaveBridge } from '../hooks/useSeoSaveBridge'
+import { indexSeoTargets } from '../lib/indexTargets'
+import { SeoScoreboard } from '../components/SeoScoreboard'
+import { SeoTargetIndex, type SeoTargetFilter } from '../components/SeoTargetIndex'
 import { SeoPreviewEditor } from '../components/SeoPreviewEditor'
 import { SiteDefaultsEditor } from '../components/SiteDefaultsEditor'
 import styles from './MetaTab.module.css'
@@ -29,6 +38,7 @@ export const SITE_DEFAULTS_ID = 'site:defaults'
 interface MetaTabProps {
   workspace: SeoWorkspace
   canManage: boolean
+  bridge: SeoSaveBridge
 }
 
 /** Homepage first, then any page, then the site defaults row. */
@@ -40,11 +50,16 @@ function defaultSelectionId(targets: SeoTarget[]): string {
   )
 }
 
-export function MetaTab({ workspace, canManage }: MetaTabProps) {
+export function MetaTab({ workspace, canManage, bridge }: MetaTabProps) {
   const [selection, setSelection] = useState<string | null>(null)
-  const [editorDirty, setEditorDirty] = useState(false)
   const [pendingSelection, setPendingSelection] = useState<string | null>(null)
+  const [filter, setFilter] = useState<SeoTargetFilter>('all')
+
+  // One report per target, shared by the scoreboard and the index so both
+  // agree on scores and what counts as an issue.
+  const indexed = indexSeoTargets(workspace.targets, workspace.resolveContext)
 
+  const editorDirty = bridge.status?.dirty ?? false
   const selectedId = selection ?? defaultSelectionId(workspace.targets)
 
   const selectedTarget: SeoTarget | null =
@@ -64,39 +79,44 @@ export function MetaTab({ workspace, canManage }: MetaTabProps) {
   function discardAndSwitch(): void {
     if (pendingSelection !== null) {
       setSelection(pendingSelection)
-      setEditorDirty(false)
       setPendingSelection(null)
     }
   }
 
   return (
-    <div className={styles.columns}>
-      <div className={styles.editorColumn}>
-        {selectedTarget ? (
-          <SeoPreviewEditor
-            key={selectedTarget.id}
-            target={selectedTarget}
-            workspace={workspace}
-            canManage={canManage}
-            onDirtyChange={setEditorDirty}
-          />
-        ) : (
-          <SiteDefaultsEditor
-            key={SITE_DEFAULTS_ID}
-            workspace={workspace}
-            canManage={canManage}
-            onDirtyChange={setEditorDirty}
-          />
-        )}
-      </div>
+    <div className={styles.layout}>
+      <SeoScoreboard indexed={indexed} onReviewIssues={() => setFilter('issues')} />
+
+      <div className={styles.columns}>
+        <div className={styles.editorColumn}>
+          {selectedTarget ? (
+            <SeoPreviewEditor
+              key={selectedTarget.id}
+              target={selectedTarget}
+              workspace={workspace}
+              canManage={canManage}
+              bridge={bridge}
+            />
+          ) : (
+            <SiteDefaultsEditor
+              key={SITE_DEFAULTS_ID}
+              workspace={workspace}
+              canManage={canManage}
+              bridge={bridge}
+            />
+          )}
+        </div>
 
-      <div className={styles.indexColumn}>
-        <SeoTargetIndex
-          workspace={workspace}
-          selectedId={selectedId}
-          siteDefaultsId={SITE_DEFAULTS_ID}
-          onSelect={handleSelect}
-        />
+        <div className={styles.indexColumn}>
+          <SeoTargetIndex
+            indexed={indexed}
+            filter={filter}
+            onFilterChange={setFilter}
+            selectedId={selectedId}
+            siteDefaultsId={SITE_DEFAULTS_ID}
+            onSelect={handleSelect}
+          />
+        </div>
       </div>
 
       <Dialog
diff --git a/src/admin/pages/seo/tabs/RobotsTab.tsx b/src/admin/pages/seo/tabs/RobotsTab.tsx
index 2f9ebef01..38bc51d70 100644
--- a/src/admin/pages/seo/tabs/RobotsTab.tsx
+++ b/src/admin/pages/seo/tabs/RobotsTab.tsx
@@ -11,27 +11,36 @@ import { useState } from 'react'
 import { Switch } from '@ui/components/Switch'
 import { FormField } from '@ui/components/FormField'
 import { getErrorMessage } from '@core/utils/errorMessage'
+import { publishCmsDraft } from '@core/persistence'
+import { hasCapability } from '@admin/access'
+import { useCurrentAdminUser } from '@admin/sessionContext'
+import { StepUpCancelledMessage, useStepUp } from '@admin/shared/StepUp'
 import {
   generateRobotsTxt,
   AI_TRAINING_CRAWLERS,
   AI_ANSWER_CRAWLERS,
   type SeoRobotsSettings,
 } from '@core/seo'
-import { SaveControls } from '../components/SeoPreviewEditor'
 import { SeoCodeViewer } from '../components/SeoCodeViewer'
 import type { SeoWorkspace } from '../hooks/useSeoWorkspace'
+import type { SeoSaveBridge } from '../hooks/useSeoSaveBridge'
+import { useSeoSaveSurface } from '../hooks/useSeoSaveBridge'
 import styles from './SettingsTabs.module.css'
 
 interface RobotsTabProps {
   workspace: SeoWorkspace
   canManage: boolean
+  bridge: SeoSaveBridge
 }
 
-export function RobotsTab({ workspace, canManage }: RobotsTabProps) {
+export function RobotsTab({ workspace, canManage, bridge }: RobotsTabProps) {
   const stored = workspace.siteSeo?.robots ?? {}
   const [draft, setDraft] = useState<SeoRobotsSettings>(stored)
-  const [saveState, setSaveState] = useState<'idle' | 'saving' | 'saved' | 'error'>('idle')
+  const [saveState, setSaveState] = useState<'idle' | 'saving' | 'saved' | 'publishing' | 'published' | 'error'>('idle')
   const [saveError, setSaveError] = useState<string | null>(null)
+  const currentUser = useCurrentAdminUser()
+  const { runStepUp } = useStepUp()
+  const canPublish = !currentUser || hasCapability(currentUser, 'pages.publish')
 
   const isDirty = JSON.stringify(draft) !== JSON.stringify(stored)
 
@@ -46,19 +55,52 @@ export function RobotsTab({ workspace, canManage }: RobotsTabProps) {
     if (saveState !== 'idle') setSaveState('idle')
   }
 
-  async function handleSave(): Promise<void> {
+  async function handleSave(): Promise<boolean> {
     setSaveState('saving')
     setSaveError(null)
     try {
       await workspace.saveSite({ ...(workspace.siteSeo ?? {}), robots: draft })
       setSaveState('saved')
+      return true
     } catch (err) {
       console.error('[seo-page] robots save failed:', err)
       setSaveState('error')
       setSaveError(getErrorMessage(err, 'Could not save robots settings'))
+      return false
     }
   }
 
+  async function handlePublish(): Promise<void> {
+    if (isDirty && !(await handleSave())) return
+    setSaveState('publishing')
+    try {
+      // Full site publish — step-up gated, same as the Site toolbar.
+      await runStepUp(() => publishCmsDraft())
+      setSaveState('published')
+    } catch (err) {
+      if (err instanceof Error && err.message === StepUpCancelledMessage) {
+        setSaveState('saved')
+        return
+      }
+      console.error('[seo-page] publish failed:', err)
+      setSaveState('error')
+      setSaveError(getErrorMessage(err, 'Could not publish'))
+    }
+  }
+
+  useSeoSaveSurface(
+    bridge,
+    {
+      dirty: isDirty,
+      state: saveState,
+      canSave: canManage,
+      canPublish,
+      publishScope: 'site',
+      liveUrl: workspace.publicOrigin ? `${workspace.publicOrigin}/robots.txt` : null,
+    },
+    { save: () => void handleSave(), publish: () => void handlePublish() },
+  )
+
   return (
     <section className={styles.tab} aria-label="Robots.txt settings">
       <header className={styles.header}>
@@ -68,7 +110,6 @@ export function RobotsTab({ workspace, canManage }: RobotsTabProps) {
             Generated automatically and served at <code>/robots.txt</code>. Changes go live on the next publish.
           </p>
         </div>
-        <SaveControls dirty={isDirty} state={saveState} canManage={canManage} onSave={() => void handleSave()} />
       </header>
       {saveError && <p className={styles.error} role="alert">{saveError}</p>}
       {!workspace.publicOrigin && (
diff --git a/src/admin/pages/seo/tabs/SitemapTab.tsx b/src/admin/pages/seo/tabs/SitemapTab.tsx
index b8f4278a2..b589cacfc 100644
--- a/src/admin/pages/seo/tabs/SitemapTab.tsx
+++ b/src/admin/pages/seo/tabs/SitemapTab.tsx
@@ -10,22 +10,31 @@ import { useState } from 'react'
 import { Switch } from '@ui/components/Switch'
 import { FormField } from '@ui/components/FormField'
 import { getErrorMessage } from '@core/utils/errorMessage'
+import { publishCmsDraft } from '@core/persistence'
+import { hasCapability } from '@admin/access'
+import { useCurrentAdminUser } from '@admin/sessionContext'
+import { StepUpCancelledMessage, useStepUp } from '@admin/shared/StepUp'
 import type { SeoSitemapSettings } from '@core/seo'
-import { SaveControls } from '../components/SeoPreviewEditor'
 import { SeoCodeViewer } from '../components/SeoCodeViewer'
 import type { SeoWorkspace } from '../hooks/useSeoWorkspace'
+import type { SeoSaveBridge } from '../hooks/useSeoSaveBridge'
+import { useSeoSaveSurface } from '../hooks/useSeoSaveBridge'
 import styles from './SettingsTabs.module.css'
 
 interface SitemapTabProps {
   workspace: SeoWorkspace
   canManage: boolean
+  bridge: SeoSaveBridge
 }
 
-export function SitemapTab({ workspace, canManage }: SitemapTabProps) {
+export function SitemapTab({ workspace, canManage, bridge }: SitemapTabProps) {
   const stored = workspace.siteSeo?.sitemap ?? {}
   const [draft, setDraft] = useState<SeoSitemapSettings>(stored)
-  const [saveState, setSaveState] = useState<'idle' | 'saving' | 'saved' | 'error'>('idle')
+  const [saveState, setSaveState] = useState<'idle' | 'saving' | 'saved' | 'publishing' | 'published' | 'error'>('idle')
   const [saveError, setSaveError] = useState<string | null>(null)
+  const currentUser = useCurrentAdminUser()
+  const { runStepUp } = useStepUp()
+  const canPublish = !currentUser || hasCapability(currentUser, 'pages.publish')
 
   const isDirty = JSON.stringify(draft) !== JSON.stringify(stored)
   const enabled = draft.enabled !== false
@@ -53,19 +62,52 @@ export function SitemapTab({ workspace, canManage }: SitemapTabProps) {
     if (saveState !== 'idle') setSaveState('idle')
   }
 
-  async function handleSave(): Promise<void> {
+  async function handleSave(): Promise<boolean> {
     setSaveState('saving')
     setSaveError(null)
     try {
       await workspace.saveSite({ ...(workspace.siteSeo ?? {}), sitemap: draft })
       setSaveState('saved')
+      return true
     } catch (err) {
       console.error('[seo-page] sitemap save failed:', err)
       setSaveState('error')
       setSaveError(getErrorMessage(err, 'Could not save sitemap settings'))
+      return false
     }
   }
 
+  async function handlePublish(): Promise<void> {
+    if (isDirty && !(await handleSave())) return
+    setSaveState('publishing')
+    try {
+      // Full site publish — step-up gated, same as the Site toolbar.
+      await runStepUp(() => publishCmsDraft())
+      setSaveState('published')
+    } catch (err) {
+      if (err instanceof Error && err.message === StepUpCancelledMessage) {
+        setSaveState('saved')
+        return
+      }
+      console.error('[seo-page] publish failed:', err)
+      setSaveState('error')
+      setSaveError(getErrorMessage(err, 'Could not publish'))
+    }
+  }
+
+  useSeoSaveSurface(
+    bridge,
+    {
+      dirty: isDirty,
+      state: saveState,
+      canSave: canManage,
+      canPublish,
+      publishScope: 'site',
+      liveUrl: workspace.publicOrigin ? `${workspace.publicOrigin}/sitemap.xml` : null,
+    },
+    { save: () => void handleSave(), publish: () => void handlePublish() },
+  )
+
   return (
     <section className={styles.tab} aria-label="Sitemap settings">
       <header className={styles.header}>
@@ -75,7 +117,6 @@ export function SitemapTab({ workspace, canManage }: SitemapTabProps) {
             Generated from published content and served at <code>/sitemap.xml</code>. Changes go live on the next publish.
           </p>
         </div>
-        <SaveControls dirty={isDirty} state={saveState} canManage={canManage} onSave={() => void handleSave()} />
       </header>
       {saveError && <p className={styles.error} role="alert">{saveError}</p>}
       {!workspace.publicOrigin && (
diff --git a/src/core/seo/__tests__/health.test.ts b/src/core/seo/__tests__/health.test.ts
index 89b3bc542..19f850684 100644
--- a/src/core/seo/__tests__/health.test.ts
+++ b/src/core/seo/__tests__/health.test.ts
@@ -1,42 +1,89 @@
 import { describe, expect, test } from 'bun:test'
-import { computeSeoHealth } from '../health'
+import { computeSeoReport, aggregateSeoScore, seoScoreTier } from '../health'
 import { resolveSeoMetadata } from '../resolve'
-import { approxPixelWidth, meterZone, TITLE_PIXEL_BUDGET } from '../lengthMeter'
+import {
+  approxPixelWidth,
+  meterZone,
+  TITLE_PIXEL_BUDGET,
+  TITLE_PIXEL_MIN,
+} from '../lengthMeter'
 
-const BASE = { siteName: 'Acme', routeKind: 'page' as const, routePath: '/about' }
+const BASE = {
+  siteName: 'Acme',
+  routeKind: 'page' as const,
+  routePath: '/about',
+  origin: 'https://acme.com',
+}
 
-describe('computeSeoHealth', () => {
-  test('healthy target has zero issues', () => {
+function check(report: ReturnType<typeof computeSeoReport>, id: string) {
+  return report.checks.find((c) => c.id === id)!
+}
+
+describe('computeSeoReport', () => {
+  test('fully optimized target scores 100 with zero issues', () => {
     const target = {
-      title: 'Nice short title',
-      description: 'A reasonable description for the page.',
+      title: 'A descriptive title in the ideal band',
+      description:
+        'A reasonably detailed description for the page that lands inside the ideal length band for snippets.',
       ogImage: '/img.png',
       ogImageAlt: 'An image',
     }
-    const health = computeSeoHealth(target, resolveSeoMetadata({ ...BASE, target }))
-    expect(health).toEqual({
-      title: 'ok',
-      description: 'ok',
-      image: 'ok',
-      indexable: true,
-      issueCount: 0,
-    })
+    const report = computeSeoReport(target, resolveSeoMetadata({ ...BASE, target }))
+    expect(report.score).toBe(100)
+    expect(report.issueCount).toBe(0)
+    expect(report.checks.every((c) => c.status === 'pass')).toBe(true)
+  })
+
+  test('flags missing description, missing alt, and noindex', () => {
+    const target = { title: 'A descriptive title in the ideal band', noindex: true, ogImage: '/img.png' }
+    const report = computeSeoReport(target, resolveSeoMetadata({ ...BASE, target }))
+    expect(check(report, 'description').status).toBe('fail')
+    expect(check(report, 'imageAlt').status).toBe('warn')
+    expect(check(report, 'indexable').status).toBe('fail')
+    expect(report.issueCount).toBe(3)
+    expect(report.score).toBeLessThan(60)
   })
 
-  test('flags missing description, image, alt, and noindex', () => {
-    const target = { title: 'T', noindex: true, ogImage: '/img.png' }
-    const health = computeSeoHealth(target, resolveSeoMetadata({ ...BASE, target }))
-    expect(health.description).toBe('missing')
-    expect(health.image).toBe('missingAlt')
-    expect(health.indexable).toBe(false)
-    expect(health.issueCount).toBe(3)
+  test('short title warns instead of passing — green only in the ideal band', () => {
+    expect(meterZone(approxPixelWidth('Home'), TITLE_PIXEL_BUDGET, TITLE_PIXEL_MIN)).toBe('short')
+    const target = { title: 'Home' }
+    const report = computeSeoReport(target, resolveSeoMetadata({ ...BASE, target }))
+    expect(check(report, 'title').status).toBe('warn')
+    expect(check(report, 'title').advice).toContain('Short')
   })
 
-  test('flags over-budget title as long', () => {
+  test('over-budget title warns about truncation', () => {
     const longTitle = 'Wide MMMM Words '.repeat(8)
-    expect(meterZone(approxPixelWidth(longTitle), TITLE_PIXEL_BUDGET)).toBe('over')
+    expect(meterZone(approxPixelWidth(longTitle), TITLE_PIXEL_BUDGET, TITLE_PIXEL_MIN)).toBe('over')
     const target = { title: longTitle }
-    const health = computeSeoHealth(target, resolveSeoMetadata({ ...BASE, target }))
-    expect(health.title).toBe('long')
+    const report = computeSeoReport(target, resolveSeoMetadata({ ...BASE, target }))
+    expect(check(report, 'title').status).toBe('warn')
+    expect(check(report, 'title').advice).toContain('truncate')
+  })
+
+  test('alt check is omitted when there is no social image', () => {
+    const target = { title: 'A descriptive title in the ideal band' }
+    const report = computeSeoReport(target, resolveSeoMetadata({ ...BASE, target }))
+    expect(check(report, 'socialImage').status).toBe('fail')
+    expect(report.checks.some((c) => c.id === 'imageAlt')).toBe(false)
+  })
+
+  test('missing public origin downgrades the canonical check to warn', () => {
+    const target = { title: 'A descriptive title in the ideal band' }
+    const report = computeSeoReport(
+      target,
+      resolveSeoMetadata({ siteName: 'Acme', routeKind: 'page', routePath: '/about', target }),
+    )
+    expect(check(report, 'canonical').status).toBe('warn')
+  })
+})
+
+describe('aggregateSeoScore / seoScoreTier', () => {
+  test('aggregates the mean and maps tiers', () => {
+    expect(aggregateSeoScore([])).toBe(0)
+    expect(aggregateSeoScore([{ checks: [], score: 100, issueCount: 0 }, { checks: [], score: 50, issueCount: 1 }])).toBe(75)
+    expect(seoScoreTier(92)).toBe('good')
+    expect(seoScoreTier(64)).toBe('fair')
+    expect(seoScoreTier(31)).toBe('poor')
   })
 })
diff --git a/src/core/seo/health.ts b/src/core/seo/health.ts
index c41dccb2a..51fb1440e 100644
--- a/src/core/seo/health.ts
+++ b/src/core/seo/health.ts
@@ -1,7 +1,12 @@
 /**
- * SEO health indicators — computed client-side from raw target values plus
- * the resolved metadata, so the target index, the preview editor, and
- * published output agree by construction (one resolver, one health rule set).
+ * SEO report — granular per-target checks plus a weighted 0–100 score,
+ * computed client-side from raw target values and the resolved metadata, so
+ * the target index, the preview editor, and published output agree by
+ * construction (one resolver, one rule set).
+ *
+ * Each check carries the advice line the editor shows in its improvements
+ * list; the score is the weighted pass ratio (warn earns half credit). The
+ * site-wide score is the plain mean of the per-target scores.
  */
 
 import type { SeoMetadata } from './schema'
@@ -10,53 +15,152 @@ import {
   approxPixelWidth,
   meterZone,
   TITLE_PIXEL_BUDGET,
+  TITLE_PIXEL_MIN,
   DESCRIPTION_PIXEL_BUDGET,
+  DESCRIPTION_PIXEL_MIN,
 } from './lengthMeter'
 
-export type TextHealth = 'ok' | 'missing' | 'long'
-export type ImageHealth = 'ok' | 'missing' | 'missingAlt'
+export type SeoCheckStatus = 'pass' | 'warn' | 'fail'
 
-export interface SeoHealth {
-  title: TextHealth
-  description: TextHealth
-  image: ImageHealth
-  /** false when the target is set to noindex. */
-  indexable: boolean
-  /** Count of non-ok indicators, for index sorting / summary chips. */
+export type SeoCheckId =
+  | 'title'
+  | 'description'
+  | 'socialImage'
+  | 'imageAlt'
+  | 'indexable'
+  | 'canonical'
+
+export interface SeoCheck {
+  id: SeoCheckId
+  label: string
+  status: SeoCheckStatus
+  /** One actionable sentence; present whenever status is not 'pass'. */
+  advice?: string
+  /** Relative score weight — pass earns it, warn earns half, fail none. */
+  weight: number
+}
+
+export interface SeoReport {
+  checks: SeoCheck[]
+  /** Weighted pass ratio, 0–100. */
+  score: number
+  /** Count of non-pass checks, for index filtering / summary chips. */
   issueCount: number
 }
 
-export function computeSeoHealth(
+export type SeoScoreTier = 'good' | 'fair' | 'poor'
+
+export function seoScoreTier(score: number): SeoScoreTier {
+  if (score >= 80) return 'good'
+  if (score >= 50) return 'fair'
+  return 'poor'
+}
+
+function titleCheck(resolved: ResolvedSeoMetadata): SeoCheck {
+  const base = { id: 'title' as const, label: 'Title', weight: 30 }
+  if (resolved.title === '') {
+    return { ...base, status: 'fail', advice: 'Add one — the title is the strongest ranking signal on the page.' }
+  }
+  const zone = meterZone(approxPixelWidth(resolved.title), TITLE_PIXEL_BUDGET, TITLE_PIXEL_MIN)
+  if (zone === 'over') {
+    return { ...base, status: 'warn', advice: 'Will truncate in results — keep it under ~60 characters.' }
+  }
+  if (zone === 'short') {
+    return { ...base, status: 'warn', advice: 'Short — 30–60 characters use the snippet space search engines give it.' }
+  }
+  return { ...base, status: 'pass' }
+}
+
+function descriptionCheck(resolved: ResolvedSeoMetadata): SeoCheck {
+  const base = { id: 'description' as const, label: 'Description', weight: 30 }
+  const description = resolved.description ?? ''
+  if (description === '') {
+    return { ...base, status: 'fail', advice: 'Add one — without it, search engines improvise a snippet from page content.' }
+  }
+  const zone = meterZone(approxPixelWidth(description), DESCRIPTION_PIXEL_BUDGET, DESCRIPTION_PIXEL_MIN)
+  if (zone === 'over') {
+    return { ...base, status: 'warn', advice: 'Will truncate in results — keep it under ~160 characters.' }
+  }
+  if (zone === 'short') {
+    return { ...base, status: 'warn', advice: 'Short — 70–160 characters make a fuller snippet.' }
+  }
+  return { ...base, status: 'pass' }
+}
+
+export function computeSeoReport(
   target: SeoMetadata | undefined,
   resolved: ResolvedSeoMetadata,
-): SeoHealth {
-  const title: TextHealth =
-    resolved.title === ''
-      ? 'missing'
-      : meterZone(approxPixelWidth(resolved.title), TITLE_PIXEL_BUDGET) === 'over'
-        ? 'long'
-        : 'ok'
-
-  const description: TextHealth =
-    resolved.description === undefined || resolved.description === ''
-      ? 'missing'
-      : meterZone(approxPixelWidth(resolved.description), DESCRIPTION_PIXEL_BUDGET) === 'over'
-        ? 'long'
-        : 'ok'
-
-  const image: ImageHealth = !resolved.ogImage
-    ? 'missing'
-    : !resolved.ogImageAlt
-      ? 'missingAlt'
-      : 'ok'
-
-  const indexable = target?.noindex !== true
-
-  const issueCount =
-    (title === 'ok' ? 0 : 1) +
-    (description === 'ok' ? 0 : 1) +
-    (image === 'ok' ? 0 : 1) +
-    (indexable ? 0 : 1)
-
-  return { title, description, image, indexable, issueCount }
+): SeoReport {
+  const checks: SeoCheck[] = [titleCheck(resolved), descriptionCheck(resolved)]
+
+  checks.push(
+    resolved.ogImage
+      ? { id: 'socialImage', label: 'Social image', status: 'pass', weight: 15 }
+      : {
+          id: 'socialImage',
+          label: 'Social image',
+          status: 'fail',
+          advice: 'Add one — links without an image render as bare text cards when shared.',
+          weight: 15,
+        },
+  )
+
+  // Alt text is only assessable once an image exists; with no image the
+  // check is omitted so the missing image isn't punished twice.
+  if (resolved.ogImage) {
+    checks.push(
+      resolved.ogImageAlt
+        ? { id: 'imageAlt', label: 'Image alt text', status: 'pass', weight: 10 }
+        : {
+            id: 'imageAlt',
+            label: 'Image alt text',
+            status: 'warn',
+            advice: 'Describe the social image — alt text feeds accessibility and answer engines.',
+            weight: 10,
+          },
+    )
+  }
+
+  checks.push(
+    target?.noindex === true
+      ? {
+          id: 'indexable',
+          label: 'Indexing',
+          status: 'fail',
+          advice: 'noindex is set — intentional for utility pages, fatal for anything that should rank.',
+          weight: 15,
+        }
+      : { id: 'indexable', label: 'Indexing', status: 'pass', weight: 15 },
+  )
+
+  checks.push(
+    resolved.canonicalUrl
+      ? { id: 'canonical', label: 'Canonical URL', status: 'pass', weight: 10 }
+      : {
+          id: 'canonical',
+          label: 'Canonical URL',
+          status: 'warn',
+          advice: 'Set the public origin in Settings so a canonical URL derives automatically.',
+          weight: 10,
+        },
+  )
+
+  const totalWeight = checks.reduce((sum, check) => sum + check.weight, 0)
+  const earned = checks.reduce(
+    (sum, check) =>
+      sum + (check.status === 'pass' ? check.weight : check.status === 'warn' ? check.weight / 2 : 0),
+    0,
+  )
+
+  return {
+    checks,
+    score: Math.round((earned / totalWeight) * 100),
+    issueCount: checks.filter((check) => check.status !== 'pass').length,
+  }
+}
+
+/** Site-wide score: plain mean of per-target scores (0 with no targets). */
+export function aggregateSeoScore(reports: SeoReport[]): number {
+  if (reports.length === 0) return 0
+  return Math.round(reports.reduce((sum, report) => sum + report.score, 0) / reports.length)
 }
diff --git a/src/core/seo/index.ts b/src/core/seo/index.ts
index 7d77b294f..18be177bc 100644
--- a/src/core/seo/index.ts
+++ b/src/core/seo/index.ts
@@ -2,8 +2,8 @@
  * @core/seo — public barrel.
  *
  * The SEO engine: persisted schemas, the shared fallback resolver, JSON-LD
- * builders, robots.txt generation, AI-crawler lists, health indicators, and
- * length meters. Imported by the publisher, server handlers, and the admin
+ * builders, robots.txt generation, AI-crawler lists, per-target check
+ * reports with weighted scores, and length meters. Imported by the publisher, server handlers, and the admin
  * SEO workspace. Deep imports are gated by
  * `src/__tests__/architecture/no-core-barrel-deep-imports.test.ts`.
  */
@@ -46,13 +46,24 @@ export { AI_TRAINING_CRAWLERS, AI_ANSWER_CRAWLERS } from './aiCrawlers'
 
 export { generateRobotsTxt, type GenerateRobotsTxtInput } from './robots'
 
-export { computeSeoHealth, type SeoHealth, type TextHealth, type ImageHealth } from './health'
+export {
+  computeSeoReport,
+  aggregateSeoScore,
+  seoScoreTier,
+  type SeoReport,
+  type SeoCheck,
+  type SeoCheckId,
+  type SeoCheckStatus,
+  type SeoScoreTier,
+} from './health'
 
 export {
   approxPixelWidth,
   meterZone,
   TITLE_PIXEL_BUDGET,
+  TITLE_PIXEL_MIN,
   DESCRIPTION_PIXEL_BUDGET,
+  DESCRIPTION_PIXEL_MIN,
   TITLE_CHAR_GUIDE,
   DESCRIPTION_CHAR_GUIDE,
   type MeterZone,
diff --git a/src/core/seo/lengthMeter.ts b/src/core/seo/lengthMeter.ts
index f6e224f83..85a030302 100644
--- a/src/core/seo/lengthMeter.ts
+++ b/src/core/seo/lengthMeter.ts
@@ -13,6 +13,16 @@
 export const TITLE_PIXEL_BUDGET = 580
 export const DESCRIPTION_PIXEL_BUDGET = 990
 
+/**
+ * Lower bound of the ideal band. Below this the text fits, but it wastes
+ * most of the snippet space Google gives it — classic "Home" titles and
+ * one-line descriptions. Calibrated to the usual SEO guidance (titles
+ * 30–60 chars, descriptions 70–160) through the same per-class width table
+ * as the budgets.
+ */
+export const TITLE_PIXEL_MIN = 260
+export const DESCRIPTION_PIXEL_MIN = 620
+
 /** Sensible character guides shown alongside the pixel meter. */
 export const TITLE_CHAR_GUIDE = 60
 export const DESCRIPTION_CHAR_GUIDE = 160
@@ -37,14 +47,18 @@ export function approxPixelWidth(text: string): number {
   return width
 }
 
-export type MeterZone = 'ok' | 'amber' | 'over'
+export type MeterZone = 'empty' | 'short' | 'ok' | 'amber' | 'over'
 
 /**
- * Zone for a measured width against a budget: green up to 85%, amber from
- * 85% to the budget, over beyond it.
+ * Zone for a measured width against an ideal band. The text is only "ok"
+ * (green) INSIDE the band: below `min` it's "short" (present but wasting
+ * the snippet), within the last 15% before the budget it's "amber"
+ * (approaching truncation), past the budget it's "over".
  */
-export function meterZone(pixelWidth: number, budget: number): MeterZone {
+export function meterZone(pixelWidth: number, budget: number, min: number): MeterZone {
+  if (pixelWidth === 0) return 'empty'
   if (pixelWidth > budget) return 'over'
   if (pixelWidth > budget * 0.85) return 'amber'
+  if (pixelWidth < min) return 'short'
   return 'ok'
 }
diff --git a/src/admin/pages/dashboard/components/LiquidProgressRing.module.css b/src/ui/components/LiquidProgressRing/LiquidProgressRing.module.css
similarity index 94%
rename from src/admin/pages/dashboard/components/LiquidProgressRing.module.css
rename to src/ui/components/LiquidProgressRing/LiquidProgressRing.module.css
index 90904651b..544c0d12f 100644
--- a/src/admin/pages/dashboard/components/LiquidProgressRing.module.css
+++ b/src/ui/components/LiquidProgressRing/LiquidProgressRing.module.css
@@ -21,12 +21,20 @@
 .ring {
     position: relative;
     flex-shrink: 0;
-    /* A subtle drop-shadow gives the toxic liquid a faint glow halo
-       around the bottle. Achromatic light isn't quite right here —
-       the green tint is the whole point of the component. */
+    /* A subtle drop-shadow gives the liquid a faint glow halo around
+       the bottle. Achromatic light isn't quite right here — the tint
+       matching the liquid is the whole point of the component. */
     filter: drop-shadow(0 0 6px var(--editor-mint-tint-15));
 }
 
+.toneAmber {
+    filter: drop-shadow(0 0 6px var(--editor-warning-tint-22));
+}
+
+.toneDanger {
+    filter: drop-shadow(0 0 6px var(--editor-danger-tint-30));
+}
+
 .svg {
     display: block;
     overflow: visible;
diff --git a/src/admin/pages/dashboard/components/LiquidProgressRing.tsx b/src/ui/components/LiquidProgressRing/LiquidProgressRing.tsx
similarity index 74%
rename from src/admin/pages/dashboard/components/LiquidProgressRing.tsx
rename to src/ui/components/LiquidProgressRing/LiquidProgressRing.tsx
index 4e632ac6f..a9f40a19a 100644
--- a/src/admin/pages/dashboard/components/LiquidProgressRing.tsx
+++ b/src/ui/components/LiquidProgressRing/LiquidProgressRing.tsx
@@ -1,6 +1,8 @@
 /**
  * LiquidProgressRing — circular progress badge filled with animated
- * toxic-green liquid, complete with rising bubbles and a wavy surface.
+ * liquid, complete with rising bubbles and a wavy surface. Tones: the
+ * default toxic-green "mint", plus "amber" and "danger" palettes so score
+ * displays can tier the liquid color.
  *
  * Composition (all inside one SVG, layered front-to-back):
  *
@@ -26,14 +28,55 @@
  * scrolling, bubbles disappear, and the liquid renders as a static
  * shape at the right level. The progress data is still legible.
  */
-import { useId, type CSSProperties } from 'react'
+import { useId, type CSSProperties, type ReactNode } from 'react'
+import { cn } from '@ui/cn'
 import styles from './LiquidProgressRing.module.css'
 
+export type LiquidProgressRingTone = 'mint' | 'amber' | 'danger'
+
 export interface LiquidProgressRingProps {
   value: number
   total: number
   /** Pixel size of the ring. Defaults to 112. */
   size?: number
+  /** Liquid palette. Defaults to 'mint'. */
+  tone?: LiquidProgressRingTone
+  /** Replaces the default "value/total" fraction in the center. */
+  label?: ReactNode
+  /** Defaults to "value of total steps complete". */
+  ariaLabel?: string
+}
+
+/**
+ * Per-tone gradient stops for the three liquid layers + the bottle ring.
+ * SVG gradient stops can't read CSS custom properties reliably, so the
+ * palettes live here as literals — same approach the original mint-only
+ * palette used.
+ */
+const PALETTES: Record<LiquidProgressRingTone, {
+  front: [string, string, string]
+  back: [string, string]
+  deep: [string, string, string]
+  ring: string
+}> = {
+  mint: {
+    front: ['rgba(167, 243, 208, 0.95)', 'rgba(142, 230, 200, 0.9)', 'rgba(52, 211, 153, 0.85)'],
+    back: ['rgba(74, 222, 128, 0.45)', 'rgba(34, 197, 94, 0.4)'],
+    deep: ['rgba(6, 95, 70, 0.9)', 'rgba(6, 78, 59, 0.85)', 'rgba(2, 44, 34, 0.85)'],
+    ring: 'rgba(142, 230, 200, 0.55)',
+  },
+  amber: {
+    front: ['rgba(253, 230, 138, 0.95)', 'rgba(252, 211, 77, 0.9)', 'rgba(245, 158, 11, 0.85)'],
+    back: ['rgba(251, 191, 36, 0.45)', 'rgba(217, 119, 6, 0.4)'],
+    deep: ['rgba(146, 64, 14, 0.9)', 'rgba(120, 53, 15, 0.85)', 'rgba(69, 26, 3, 0.85)'],
+    ring: 'rgba(252, 211, 77, 0.55)',
+  },
+  danger: {
+    front: ['rgba(254, 202, 202, 0.95)', 'rgba(252, 165, 165, 0.9)', 'rgba(239, 68, 68, 0.85)'],
+    back: ['rgba(248, 113, 113, 0.45)', 'rgba(220, 38, 38, 0.4)'],
+    deep: ['rgba(153, 27, 27, 0.9)', 'rgba(127, 29, 29, 0.85)', 'rgba(69, 10, 10, 0.85)'],
+    ring: 'rgba(252, 165, 165, 0.55)',
+  },
 }
 
 // SVG user-coordinate space — independent of the rendered pixel size.
@@ -109,7 +152,15 @@ const BUBBLES: readonly BubbleSpec[] = [
   { cx: 48, r: 1.6, delay: 1.4, duration: 3.5 },
 ]
 
-export function LiquidProgressRing({ value, total, size = 112 }: LiquidProgressRingProps) {
+export function LiquidProgressRing({
+  value,
+  total,
+  size = 112,
+  tone = 'mint',
+  label,
+  ariaLabel,
+}: LiquidProgressRingProps) {
+  const palette = PALETTES[tone]
   const pct = total === 0 ? 0 : Math.max(0, Math.min(1, value / total))
   // Wave surface Y in user units. At pct=0 the surface is at the bottom
   // (y=100), at pct=1 it's at the top (y=0). Bubbles rise from y≈96
@@ -144,7 +195,12 @@ export function LiquidProgressRing({ value, total, size = 112 }: LiquidProgressR
   }
 
   return (
-    <div className={styles.ring} style={containerStyle} role="img" aria-label={`${value} of ${total} steps complete`}>
+    <div
+      className={cn(styles.ring, tone === 'amber' && styles.toneAmber, tone === 'danger' && styles.toneDanger)}
+      style={containerStyle}
+      role="img"
+      aria-label={ariaLabel ?? `${value} of ${total} steps complete`}
+    >
       <svg
         width={size}
         height={size}
@@ -158,29 +214,28 @@ export function LiquidProgressRing({ value, total, size = 112 }: LiquidProgressR
             <circle cx={CX} cy={CY} r={R} />
           </clipPath>
 
-          {/* Primary liquid: a vertical gradient from a bright mint
-              crest down to a slightly darker mint base for depth. */}
+          {/* Primary liquid: a vertical gradient from a bright crest
+              down to a slightly darker base for depth. */}
           <linearGradient id={liquidGrad} x1="0" x2="0" y1="0" y2="1">
-            <stop offset="0%" stopColor="rgba(167, 243, 208, 0.95)" />
-            <stop offset="55%" stopColor="rgba(142, 230, 200, 0.9)" />
-            <stop offset="100%" stopColor="rgba(52, 211, 153, 0.85)" />
+            <stop offset="0%" stopColor={palette.front[0]} />
+            <stop offset="55%" stopColor={palette.front[1]} />
+            <stop offset="100%" stopColor={palette.front[2]} />
           </linearGradient>
 
           {/* Secondary back-wave — lower opacity for the parallax look. */}
           <linearGradient id={liquidGradBack} x1="0" x2="0" y1="0" y2="1">
-            <stop offset="0%" stopColor="rgba(74, 222, 128, 0.45)" />
-            <stop offset="100%" stopColor="rgba(34, 197, 94, 0.4)" />
+            <stop offset="0%" stopColor={palette.back[0]} />
+            <stop offset="100%" stopColor={palette.back[1]} />
           </linearGradient>
 
-          {/* Deep wave — saturated forest-green tones for the "shadow
-              of a deeper swell" effect. Higher opacity at the crest
-              (where it peeks above the brighter front wave) so the
-              parallax silhouette reads as a real shape, not just a
-              tint. */}
+          {/* Deep wave — saturated dark tones for the "shadow of a
+              deeper swell" effect. Higher opacity at the crest (where
+              it peeks above the brighter front wave) so the parallax
+              silhouette reads as a real shape, not just a tint. */}
           <linearGradient id={liquidGradDeep} x1="0" x2="0" y1="0" y2="1">
-            <stop offset="0%" stopColor="rgba(6, 95, 70, 0.9)" />
-            <stop offset="55%" stopColor="rgba(6, 78, 59, 0.85)" />
-            <stop offset="100%" stopColor="rgba(2, 44, 34, 0.85)" />
+            <stop offset="0%" stopColor={palette.deep[0]} />
+            <stop offset="55%" stopColor={palette.deep[1]} />
+            <stop offset="100%" stopColor={palette.deep[2]} />
           </linearGradient>
 
           {/* Soft inner glow on the empty bottle. Pure white at low
@@ -268,16 +323,18 @@ export function LiquidProgressRing({ value, total, size = 112 }: LiquidProgressR
           cy={CY}
           r={R}
           fill="none"
-          stroke="rgba(142, 230, 200, 0.55)"
+          stroke={palette.ring}
           strokeWidth={1.2}
         />
       </svg>
 
       <div className={styles.label}>
-        <span className={styles.fraction}>
-          {value}
-          <small>/{total}</small>
-        </span>
+        {label ?? (
+          <span className={styles.fraction}>
+            {value}
+            <small>/{total}</small>
+          </span>
+        )}
       </div>
     </div>
   )
diff --git a/src/ui/components/LiquidProgressRing/index.ts b/src/ui/components/LiquidProgressRing/index.ts
new file mode 100644
index 000000000..67273c8af
--- /dev/null
+++ b/src/ui/components/LiquidProgressRing/index.ts
@@ -0,0 +1,2 @@
+export { LiquidProgressRing } from './LiquidProgressRing'
+export type { LiquidProgressRingProps, LiquidProgressRingTone } from './LiquidProgressRing'

From ad1302359cb0285169543e092c212af8e21c9530 Mon Sep 17 00:00:00 2001
From: DavidBabinec <hello@davidbabinec.com>
Date: Fri, 12 Jun 2026 15:26:40 +0200
Subject: [PATCH 11/26] refactor(seo): rebuild SeoImageField on the shared
 media-picker pattern
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

The OG/X image fields hand-rolled a URL input + Browse button while the
property panel already had the Library/URL segmented toggle over the
shared MediaPickerField tile (thumbnail, Change/Clear, fullscreen
MediaPickerModal). SeoImageField now uses the same pieces: Library mode
shows the picked tile with asset metadata, URL mode keeps external
images with an inline preview and validation, and a purely inherited
image renders through the tile's fallback state with an "Inherited —
pick one to override" hint.

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
---
 src/__tests__/admin/seoWorkspace.test.tsx     |  10 +-
 .../seo/components/SeoImageField.module.css   |  38 ++++-
 .../pages/seo/components/SeoImageField.tsx    | 161 ++++++++++++++----
 .../pages/seo/components/SeoPreviewEditor.tsx |   2 +-
 4 files changed, 164 insertions(+), 47 deletions(-)

diff --git a/src/__tests__/admin/seoWorkspace.test.tsx b/src/__tests__/admin/seoWorkspace.test.tsx
index 8f54db268..2f75ceac4 100644
--- a/src/__tests__/admin/seoWorkspace.test.tsx
+++ b/src/__tests__/admin/seoWorkspace.test.tsx
@@ -164,6 +164,10 @@ function mockSeoFetch(): FetchCall[] {
         },
       })
     }
+    if (url === '/admin/api/cms/media') {
+      // SeoImageField resolves picked-tile thumbnails from the asset list.
+      return json({ assets: [] })
+    }
     if (url === '/admin/api/cms/seo/site' && init?.method === 'PUT') {
       const body = JSON.parse(String(init.body)) as { seo: Record<string, unknown> }
       return json({ seo: body.seo })
@@ -327,9 +331,11 @@ describe('SEO Meta tab', () => {
     fireEvent.click(await screen.findByTestId('seo-target-page_about'))
     const editor = await screen.findByRole('region', { name: 'SEO for About' })
 
-    // "About Acme" has no social image — the improvement row points at it.
+    // "About Acme" has no social image — the improvement row points at the
+    // OG image field (a tabIndex=-1 container, since the Library mode has no
+    // single input to land on).
     fireEvent.click(within(editor).getByTestId('seo-improvement-socialImage'))
-    expect(document.activeElement).toBe(within(editor).getByLabelText('OG image URL'))
+    expect((document.activeElement as HTMLElement).id.endsWith('-ogImage')).toBe(true)
   })
 
   it('guards target switching while the editor is dirty', async () => {
diff --git a/src/admin/pages/seo/components/SeoImageField.module.css b/src/admin/pages/seo/components/SeoImageField.module.css
index 3b0e3e0ae..948725fcb 100644
--- a/src/admin/pages/seo/components/SeoImageField.module.css
+++ b/src/admin/pages/seo/components/SeoImageField.module.css
@@ -1,28 +1,52 @@
 /* Mirrors SeoPreviewEditor's two-column field grid — the shared
- * --seo-label-col is defined on the parent .form. */
+ * --seo-label-col is defined on the parent .form. The control column stacks
+ * the Library/URL toggle over the picker tile, so labels top-align. */
 .field {
     display: grid;
     grid-template-columns: var(--seo-label-col) minmax(0, 1fr);
     column-gap: 18px;
-    align-items: center;
+    align-items: start;
+    outline: none;
 }
 
 .label {
     font-size: 12.5px;
     font-weight: 600;
     color: var(--editor-text-muted);
+    padding-top: 6px;
 }
 
-.controls {
+.body {
     display: flex;
-    align-items: center;
+    flex-direction: column;
     gap: 6px;
     min-width: 0;
 }
 
-.controls > :first-child {
-    flex: 1;
-    min-width: 0;
+.status {
+    margin: 0;
+    font-size: 11px;
+    color: var(--editor-danger-text);
+}
+
+.urlBody {
+    display: flex;
+    flex-direction: column;
+    gap: 6px;
+}
+
+.urlPreview {
+    display: block;
+    overflow: hidden;
+    border-radius: var(--editor-radius);
+    background: var(--editor-surface-3);
+}
+
+.urlPreview img {
+    display: block;
+    width: 100%;
+    max-height: 140px;
+    object-fit: cover;
 }
 
 @media (max-width: 700px) {
diff --git a/src/admin/pages/seo/components/SeoImageField.tsx b/src/admin/pages/seo/components/SeoImageField.tsx
index 3621482a1..f3cd9b633 100644
--- a/src/admin/pages/seo/components/SeoImageField.tsx
+++ b/src/admin/pages/seo/components/SeoImageField.tsx
@@ -1,16 +1,21 @@
 /**
- * SeoImageField — social-image picker for OG/X images.
+ * SeoImageField — social-image picker for OG/X images and site-default
+ * images.
  *
- * Primary affordance: the media library picker (same `MediaPickerModal` the
- * favicon picker uses). A URL input stays available as the secondary path
- * for externally-hosted images. Empty value falls back through the resolver
- * chain — the inherited value renders as a muted preview row.
+ * Same Library/URL pattern as the property panel's `MediaLibraryControl`:
+ * a segmented source toggle over the shared `MediaPickerField` tile
+ * (thumbnail + Change/Clear, fullscreen `MediaPickerModal`), or a plain URL
+ * input with inline preview for externally-hosted images. Empty value falls
+ * back through the resolver chain — the inherited image renders in the tile
+ * with an "Inherited" hint until overridden.
  */
-import { lazy, Suspense, useState } from 'react'
-import { Button } from '@ui/components/Button'
+import { lazy, Suspense, useEffect, useState } from 'react'
 import { Input } from '@ui/components/Input'
-import { ImagesSolidIcon } from 'pixel-art-icons/icons/images-solid'
-import type { CmsMediaAsset } from '@core/persistence'
+import { SegmentedControl } from '@ui/components/SegmentedControl'
+import { listCmsMediaAssets, type CmsMediaAsset } from '@core/persistence/cmsMedia'
+import { isValidImageUrl } from '@core/utils/urlValidation'
+import { getErrorMessage } from '@core/utils/errorMessage'
+import { MediaPickerField } from '@admin/pages/media/components/MediaPickerField'
 import styles from './SeoImageField.module.css'
 
 const MediaPickerModal = lazy(() =>
@@ -19,10 +24,17 @@ const MediaPickerModal = lazy(() =>
   ),
 )
 
+type Mode = 'library' | 'url'
+
+const SOURCE_OPTIONS = [
+  { value: 'library', label: 'Library', ariaLabel: 'Media library' },
+  { value: 'url', label: 'URL', ariaLabel: 'Custom URL' },
+] satisfies ReadonlyArray<{ value: Mode; label: string; ariaLabel: string }>
+
 interface SeoImageFieldProps {
   label: string
-  /** Id for the URL input — lets the improvements list focus this field. */
-  inputId?: string
+  /** Anchor id — the improvements list scrolls to / focuses this field. */
+  fieldId?: string
   /** Explicit value ('' when inheriting). */
   value: string
   /** Resolved fallback shown when no explicit value is set. */
@@ -31,41 +43,116 @@ interface SeoImageFieldProps {
   onChange: (next: string) => void
 }
 
-export function SeoImageField({ label, inputId, value, inheritedValue, disabled, onChange }: SeoImageFieldProps) {
+/** Local upload paths and absolute http(s)/data:image URLs are accepted. */
+function isValidSeoImageValue(value: string): boolean {
+  if (value === '') return true
+  if (value.startsWith('/') && !value.startsWith('//')) return true
+  return isValidImageUrl(value)
+}
+
+export function SeoImageField({ label, fieldId, value, inheritedValue, disabled, onChange }: SeoImageFieldProps) {
+  const [mode, setMode] = useState<Mode>(() =>
+    value !== '' && !value.startsWith('/uploads/') ? 'url' : 'library',
+  )
   const [pickerOpen, setPickerOpen] = useState(false)
+  // Fetched once so the picked tile can render the right thumbnail +
+  // metadata for a saved publicPath — same approach as MediaLibraryControl.
+  // The modal mounts its own workspace when opened.
+  const [assets, setAssets] = useState<CmsMediaAsset[]>([])
+  const [libraryError, setLibraryError] = useState('')
+
+  useEffect(() => {
+    let cancelled = false
+    listCmsMediaAssets()
+      .then((next) => {
+        if (!cancelled) setAssets(next)
+      })
+      .catch((err: unknown) => {
+        if (!cancelled) setLibraryError(getErrorMessage(err, 'Unable to load media library'))
+      })
+    return () => {
+      cancelled = true
+    }
+  }, [])
 
-  function handlePick(asset: CmsMediaAsset): void {
-    onChange(asset.publicPath)
+  // The tile resolves a thumbnail only for the EXPLICIT value; a purely
+  // inherited image renders through the fallback branch so the "Inherited"
+  // hint stays visible.
+  const asset = value !== '' ? assets.find((a) => a.publicPath === value) ?? null : null
+  const inheriting = value === '' && inheritedValue !== null
+  const urlInvalid = !isValidSeoImageValue(value)
+
+  function handlePick(picked: CmsMediaAsset): void {
+    setAssets((current) => (current.some((a) => a.id === picked.id) ? current : [picked, ...current]))
+    onChange(picked.publicPath)
     setPickerOpen(false)
   }
 
   return (
-    <div className={styles.field}>
+    /* tabIndex -1: programmatic focus target for the improvements list. */
+    <div id={fieldId} tabIndex={-1} className={styles.field}>
       <span className={styles.label}>{label}</span>
-      <div className={styles.controls}>
-        <Input
-          type="text"
-          id={inputId}
-          value={value}
-          placeholder={inheritedValue ?? 'No image — pick from the library'}
-          disabled={disabled}
-          aria-label={`${label} URL`}
-          onChange={(e) => onChange(e.target.value)}
-        />
-        <Button
-          variant="secondary"
+      <div className={styles.body}>
+        <SegmentedControl<Mode>
+          value={mode}
+          options={SOURCE_OPTIONS}
+          onChange={setMode}
           size="sm"
+          fullWidth
           disabled={disabled}
-          onClick={() => setPickerOpen(true)}
-          aria-label={`Browse media library for ${label}`}
-        >
-          <ImagesSolidIcon size={13} aria-hidden="true" />
-          <span>Browse</span>
-        </Button>
-        {value !== '' && (
-          <Button variant="ghost" size="sm" disabled={disabled} onClick={() => onChange('')} aria-label={`Clear ${label}`}>
-            Clear
-          </Button>
+          aria-label={`${label} source`}
+        />
+
+        {mode === 'library' ? (
+          <>
+            <MediaPickerField
+              asset={asset}
+              hasValue={value !== '' || inheriting}
+              fallbackLabel={
+                inheriting
+                  ? inheritedValue.split('/').pop() ?? inheritedValue
+                  : value.split('/').pop() ?? value
+              }
+              fallbackHint={inheriting ? 'Inherited — pick one to override' : 'Saved path'}
+              mediaKind="image"
+              subjectLabel={label}
+              disabled={disabled}
+              onBrowse={() => setPickerOpen(true)}
+              onClear={value !== '' ? () => onChange('') : undefined}
+            />
+            {libraryError && (
+              <p className={styles.status} role="alert">{libraryError}</p>
+            )}
+          </>
+        ) : (
+          <div className={styles.urlBody}>
+            {value !== '' && !urlInvalid && (
+              <span className={styles.urlPreview}>
+                <img
+                  src={value}
+                  alt=""
+                  loading="lazy"
+                  onError={(event) => {
+                    ;(event.target as HTMLImageElement).style.display = 'none'
+                  }}
+                />
+              </span>
+            )}
+            <Input
+              type="url"
+              value={value}
+              placeholder={inheritedValue ?? 'https://example.com/image.png'}
+              disabled={disabled}
+              invalid={urlInvalid}
+              aria-label={`${label} URL`}
+              onChange={(e) => onChange(e.target.value)}
+            />
+            {urlInvalid && (
+              <p className={styles.status} role="alert">
+                Must be an absolute http(s) URL or a local upload path.
+              </p>
+            )}
+          </div>
         )}
       </div>
       {pickerOpen && (
diff --git a/src/admin/pages/seo/components/SeoPreviewEditor.tsx b/src/admin/pages/seo/components/SeoPreviewEditor.tsx
index b9e4be4d3..96c54a98b 100644
--- a/src/admin/pages/seo/components/SeoPreviewEditor.tsx
+++ b/src/admin/pages/seo/components/SeoPreviewEditor.tsx
@@ -322,7 +322,7 @@ export function SeoPreviewEditor({ target, workspace, canManage, bridge }: SeoPr
         {field('ogDescription', 'OG description', { textarea: true, sparkle: true })}
         <SeoImageField
           label="OG image"
-          inputId={`${fieldIdBase}-ogImage`}
+          fieldId={`${fieldIdBase}-ogImage`}
           value={draft.draft.ogImage ?? ''}
           inheritedValue={resolved.ogImage ?? null}
           disabled={!canManage}

From 48401104eb862df8f1b99443bd483e778ae41c70 Mon Sep 17 00:00:00 2001
From: DavidBabinec <hello@davidbabinec.com>
Date: Fri, 12 Jun 2026 15:31:45 +0200
Subject: [PATCH 12/26] fix(seo): render AI sparkle errors and bubbles under
 the input, not in the label cell

The grid layout left AiSuggestionSparkle's whole output (trigger + error +
suggestion bubbles) inside the 140px label column, so a provider-not-
configured error wrapped one word per line. The state machine moves to
hooks/useAiSuggestions.ts; the sparkle trigger stays in the label cell
while AiSuggestionResults (error line + bubbles) renders in the control
column under the input, via the new per-field MetaField component.

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
---
 .../components/AiSuggestionBubbles.module.css |   9 --
 .../seo/components/AiSuggestionBubbles.tsx    | 108 +++++---------
 .../pages/seo/components/SeoPreviewEditor.tsx | 136 ++++++++++++------
 src/admin/pages/seo/hooks/useAiSuggestions.ts |  68 +++++++++
 4 files changed, 196 insertions(+), 125 deletions(-)
 create mode 100644 src/admin/pages/seo/hooks/useAiSuggestions.ts

diff --git a/src/admin/pages/seo/components/AiSuggestionBubbles.module.css b/src/admin/pages/seo/components/AiSuggestionBubbles.module.css
index 304c7cde8..1a043525c 100644
--- a/src/admin/pages/seo/components/AiSuggestionBubbles.module.css
+++ b/src/admin/pages/seo/components/AiSuggestionBubbles.module.css
@@ -1,10 +1,3 @@
-.wrap {
-  display: flex;
-  flex-direction: column;
-  gap: 6px;
-  align-items: flex-end;
-}
-
 .loadingText {
   font-size: 11px;
   color: var(--editor-text-muted);
@@ -14,14 +7,12 @@
   margin: 0;
   font-size: 11px;
   color: var(--editor-danger-text);
-  text-align: right;
 }
 
 .bubbles {
   display: flex;
   flex-wrap: wrap;
   gap: 6px;
-  justify-content: flex-end;
 }
 
 .bubble {
diff --git a/src/admin/pages/seo/components/AiSuggestionBubbles.tsx b/src/admin/pages/seo/components/AiSuggestionBubbles.tsx
index 7720e1284..b6eed62f4 100644
--- a/src/admin/pages/seo/components/AiSuggestionBubbles.tsx
+++ b/src/admin/pages/seo/components/AiSuggestionBubbles.tsx
@@ -1,64 +1,30 @@
 /**
- * AiSuggestionSparkle — the ✨ action on metadata inputs.
+ * AI metadata suggestions — the ✨ action on metadata inputs.
  *
- * Click → `POST /admin/api/cms/seo/generate` → three suggestions render as
- * tappable bubbles under the input. Tapping fills the input through the
- * normal dirty/save flow (nothing auto-saves). Two trailing bubbles:
- * "More options" regenerates (excluding already-shown texts) and "Reject"
- * dismisses the row.
+ * Split to fit the editor's two-column field grid (state machine in
+ * `hooks/useAiSuggestions.ts`):
+ *   - `AiSuggestionSparkle` is the trigger button riding the label cell.
+ *   - `AiSuggestionResults` renders the error line and the tappable
+ *     suggestion bubbles UNDER the input, in the control column.
  *
  * Gating: requires `ai.chat` — without it the sparkle renders disabled with
  * an inline reason (never available-then-blocked). Provider-not-configured
  * surfaces as an inline error with a pointer to the AI workspace, matching
  * the AgentPanel's handling.
  */
-import { useState } from 'react'
 import { Button } from '@ui/components/Button'
 import { AiBoxSolidIcon } from 'pixel-art-icons/icons/ai-box-solid'
 import { hasCapability } from '@admin/access'
 import { useCurrentAdminUser } from '@admin/sessionContext'
-import { getErrorMessage } from '@core/utils/errorMessage'
-import { generateSeoSuggestions, type SeoTarget } from '../lib/seoApi'
-import type { SeoDraftField } from '../hooks/useSeoDraft'
+import type { AiSuggestions } from '../hooks/useAiSuggestions'
 import styles from './AiSuggestionBubbles.module.css'
 
-interface AiSuggestionSparkleProps {
-  target: SeoTarget
-  field: SeoDraftField
-  canManage: boolean
-  onPick: (suggestion: string) => void
-}
-
-export function AiSuggestionSparkle({ target, field, canManage, onPick }: AiSuggestionSparkleProps) {
+/** The trigger — rides the label cell next to the field label. */
+export function AiSuggestionSparkle({ ai, canManage }: { ai: AiSuggestions; canManage: boolean }) {
   const currentUser = useCurrentAdminUser()
   const unrestricted = !currentUser
   const canChat = unrestricted || hasCapability(currentUser, 'ai.chat')
 
-  const [suggestions, setSuggestions] = useState<string[] | null>(null)
-  const [seen, setSeen] = useState<string[]>([])
-  const [loading, setLoading] = useState(false)
-  const [error, setError] = useState<string | null>(null)
-
-  async function generate(exclude: string[]): Promise<void> {
-    setLoading(true)
-    setError(null)
-    try {
-      const next = await generateSeoSuggestions(target.kind, target.id, field, exclude)
-      setSuggestions(next)
-      setSeen([...exclude, ...next])
-    } catch (err) {
-      console.error('[seo-page] suggestion generation failed:', err)
-      setError(getErrorMessage(err, 'Could not generate suggestions'))
-    } finally {
-      setLoading(false)
-    }
-  }
-
-  function pick(suggestion: string): void {
-    onPick(suggestion)
-    setSuggestions(null)
-  }
-
   const disabledReason = !canManage
     ? 'Your role does not include Manage SEO'
     : !canChat
@@ -66,33 +32,38 @@ export function AiSuggestionSparkle({ target, field, canManage, onPick }: AiSugg
       : undefined
 
   return (
-    <div className={styles.wrap}>
-      <Button
-        type="button"
-        variant="ghost"
-        size="xs"
-        disabled={disabledReason !== undefined || loading}
-        tooltip={disabledReason ?? 'Generate suggestions with AI'}
-        aria-label={`Generate ${field} suggestions with AI`}
-        onClick={() => void generate([])}
-        data-testid={`seo-sparkle-${field}`}
-      >
-        <AiBoxSolidIcon size={13} aria-hidden="true" />
-        {loading && <span className={styles.loadingText}>Generating…</span>}
-      </Button>
+    <Button
+      type="button"
+      variant="ghost"
+      size="xs"
+      disabled={disabledReason !== undefined || ai.loading}
+      tooltip={disabledReason ?? 'Generate suggestions with AI'}
+      aria-label={`Generate ${ai.field} suggestions with AI`}
+      onClick={ai.generate}
+      data-testid={`seo-sparkle-${ai.field}`}
+    >
+      <AiBoxSolidIcon size={13} aria-hidden="true" />
+      {ai.loading && <span className={styles.loadingText}>Generating…</span>}
+    </Button>
+  )
+}
 
-      {error && <p className={styles.error} role="alert">{error}</p>}
+/** Error line + suggestion bubbles — renders under the input. */
+export function AiSuggestionResults({ ai }: { ai: AiSuggestions }) {
+  return (
+    <>
+      {ai.error && <p className={styles.error} role="alert">{ai.error}</p>}
 
-      {suggestions !== null && suggestions.length > 0 && (
+      {ai.suggestions !== null && ai.suggestions.length > 0 && (
         <div className={styles.bubbles} role="group" aria-label="AI suggestions">
-          {suggestions.map((suggestion) => (
+          {ai.suggestions.map((suggestion) => (
             <Button
               key={suggestion}
               type="button"
               variant="secondary"
               size="xs"
               className={styles.bubble}
-              onClick={() => pick(suggestion)}
+              onClick={() => ai.pick(suggestion)}
             >
               {suggestion}
             </Button>
@@ -102,9 +73,9 @@ export function AiSuggestionSparkle({ target, field, canManage, onPick }: AiSugg
             variant="ghost"
             size="xs"
             className={styles.bubbleAction}
-            disabled={loading}
-            onClick={() => void generate(seen)}
-            data-testid={`seo-sparkle-${field}-more`}
+            disabled={ai.loading}
+            onClick={ai.more}
+            data-testid={`seo-sparkle-${ai.field}-more`}
           >
             More options
           </Button>
@@ -113,16 +84,13 @@ export function AiSuggestionSparkle({ target, field, canManage, onPick }: AiSugg
             variant="ghost"
             size="xs"
             className={styles.bubbleAction}
-            onClick={() => {
-              setSuggestions(null)
-              setError(null)
-            }}
-            data-testid={`seo-sparkle-${field}-reject`}
+            onClick={ai.reject}
+            data-testid={`seo-sparkle-${ai.field}-reject`}
           >
             Reject
           </Button>
         </div>
       )}
-    </div>
+    </>
   )
 }
diff --git a/src/admin/pages/seo/components/SeoPreviewEditor.tsx b/src/admin/pages/seo/components/SeoPreviewEditor.tsx
index 96c54a98b..fecec0afe 100644
--- a/src/admin/pages/seo/components/SeoPreviewEditor.tsx
+++ b/src/admin/pages/seo/components/SeoPreviewEditor.tsx
@@ -42,7 +42,8 @@ import { SeoPreviewRail } from './SeoPreviewRail'
 import { SeoScoreChip } from './SeoScoreChip'
 import { MetaLengthMeter } from './MetaLengthMeter'
 import { SeoImageField } from './SeoImageField'
-import { AiSuggestionSparkle } from './AiSuggestionBubbles'
+import { useAiSuggestions } from '../hooks/useAiSuggestions'
+import { AiSuggestionSparkle, AiSuggestionResults } from './AiSuggestionBubbles'
 import styles from './SeoPreviewEditor.module.css'
 
 interface SeoPreviewEditorProps {
@@ -161,52 +162,23 @@ export function SeoPreviewEditor({ target, workspace, canManage, bridge }: SeoPr
     invalid?: boolean
     sparkle?: boolean
   }) {
-    const id = `${fieldIdBase}-${field}`
-    const value = draft.draft[field] ?? ''
-    const placeholder = resolvedPlaceholder(field)
-    const common = {
-      id,
-      value,
-      placeholder,
-      disabled: !canManage,
-      'aria-invalid': opts?.invalid || undefined,
-    }
     return (
-      <div className={styles.field}>
-        <div className={styles.fieldLabelRow}>
-          <label htmlFor={id} className={styles.fieldLabel}>{label}</label>
-          {opts?.sparkle && (
-            <AiSuggestionSparkle
-              target={target}
-              field={field}
-              canManage={canManage}
-              onPick={(suggestion) => draft.setField(field, suggestion)}
-            />
-          )}
-        </div>
-        {opts?.textarea ? (
-          <Textarea
-            {...common}
-            rows={3}
-            onChange={(e) => draft.setField(field, e.target.value)}
-          />
-        ) : (
-          <Input
-            {...common}
-            type="text"
-            onChange={(e) => draft.setField(field, e.target.value)}
-          />
-        )}
-        {opts?.meterBudget && (
-          /* Inherited values meter against the RESOLVED text, never the
-             input's hint placeholder ("No description — add one…"). */
-          <MetaLengthMeter
-            text={value !== '' ? value : opts.meterBudget === 'title' ? resolved.title : resolved.description ?? ''}
-            budget={opts.meterBudget}
-            explicit={value !== ''}
-          />
-        )}
-      </div>
+      <MetaField
+        field={field}
+        label={label}
+        id={`${fieldIdBase}-${field}`}
+        value={draft.draft[field] ?? ''}
+        placeholder={resolvedPlaceholder(field)}
+        disabled={!canManage}
+        target={target}
+        canManage={canManage}
+        textarea={opts?.textarea}
+        invalid={opts?.invalid}
+        sparkle={opts?.sparkle}
+        meterBudget={opts?.meterBudget}
+        meterText={opts?.meterBudget === 'title' ? resolved.title : resolved.description ?? ''}
+        onChange={(value) => draft.setField(field, value)}
+      />
     )
   }
 
@@ -385,3 +357,75 @@ export function SeoPreviewEditor({ target, workspace, canManage, bridge }: SeoPr
     </div>
   )
 }
+
+interface MetaFieldProps {
+  field: SeoDraftField
+  label: string
+  id: string
+  value: string
+  placeholder: string
+  disabled: boolean
+  target: SeoTarget
+  canManage: boolean
+  textarea?: boolean
+  invalid?: boolean
+  sparkle?: boolean
+  meterBudget?: 'title' | 'description'
+  /** Resolved text the meter measures when the value is inherited. */
+  meterText?: string
+  onChange: (value: string) => void
+}
+
+/**
+ * One metadata field row in the two-column grid: label (+ AI sparkle
+ * trigger) in the label cell; input, length meter, and the sparkle's
+ * error/suggestion bubbles stacked in the control column.
+ */
+function MetaField({
+  field,
+  label,
+  id,
+  value,
+  placeholder,
+  disabled,
+  target,
+  canManage,
+  textarea,
+  invalid,
+  sparkle,
+  meterBudget,
+  meterText,
+  onChange,
+}: MetaFieldProps) {
+  const ai = useAiSuggestions(target, field, onChange)
+  const common = {
+    id,
+    value,
+    placeholder,
+    disabled,
+    'aria-invalid': invalid || undefined,
+  }
+  return (
+    <div className={styles.field}>
+      <div className={styles.fieldLabelRow}>
+        <label htmlFor={id} className={styles.fieldLabel}>{label}</label>
+        {sparkle && <AiSuggestionSparkle ai={ai} canManage={canManage} />}
+      </div>
+      {textarea ? (
+        <Textarea {...common} rows={3} onChange={(e) => onChange(e.target.value)} />
+      ) : (
+        <Input {...common} type="text" onChange={(e) => onChange(e.target.value)} />
+      )}
+      {meterBudget && (
+        /* Inherited values meter against the RESOLVED text, never the
+           input's hint placeholder ("No description — add one…"). */
+        <MetaLengthMeter
+          text={value !== '' ? value : meterText ?? ''}
+          budget={meterBudget}
+          explicit={value !== ''}
+        />
+      )}
+      <AiSuggestionResults ai={ai} />
+    </div>
+  )
+}
diff --git a/src/admin/pages/seo/hooks/useAiSuggestions.ts b/src/admin/pages/seo/hooks/useAiSuggestions.ts
new file mode 100644
index 000000000..cd2192ce5
--- /dev/null
+++ b/src/admin/pages/seo/hooks/useAiSuggestions.ts
@@ -0,0 +1,68 @@
+/**
+ * useAiSuggestions — state machine behind the ✨ metadata suggestions:
+ * generate / more (exclude-aware regenerate) / pick / reject against
+ * `POST /admin/api/cms/seo/generate`. Picking fills the input through the
+ * normal dirty/save flow — nothing auto-saves.
+ *
+ * Rendered by the `AiSuggestionSparkle` trigger (label cell) and
+ * `AiSuggestionResults` (error + bubbles under the input) in
+ * `components/AiSuggestionBubbles.tsx`.
+ */
+import { useState } from 'react'
+import { getErrorMessage } from '@core/utils/errorMessage'
+import { generateSeoSuggestions, type SeoTarget } from '../lib/seoApi'
+import type { SeoDraftField } from './useSeoDraft'
+
+export interface AiSuggestions {
+  field: SeoDraftField
+  suggestions: string[] | null
+  loading: boolean
+  error: string | null
+  generate: () => void
+  more: () => void
+  pick: (suggestion: string) => void
+  reject: () => void
+}
+
+export function useAiSuggestions(
+  target: SeoTarget,
+  field: SeoDraftField,
+  onPick: (suggestion: string) => void,
+): AiSuggestions {
+  const [suggestions, setSuggestions] = useState<string[] | null>(null)
+  const [seen, setSeen] = useState<string[]>([])
+  const [loading, setLoading] = useState(false)
+  const [error, setError] = useState<string | null>(null)
+
+  async function generate(exclude: string[]): Promise<void> {
+    setLoading(true)
+    setError(null)
+    try {
+      const next = await generateSeoSuggestions(target.kind, target.id, field, exclude)
+      setSuggestions(next)
+      setSeen([...exclude, ...next])
+    } catch (err) {
+      console.error('[seo-page] suggestion generation failed:', err)
+      setError(getErrorMessage(err, 'Could not generate suggestions'))
+    } finally {
+      setLoading(false)
+    }
+  }
+
+  return {
+    field,
+    suggestions,
+    loading,
+    error,
+    generate: () => void generate([]),
+    more: () => void generate(seen),
+    pick: (suggestion) => {
+      onPick(suggestion)
+      setSuggestions(null)
+    },
+    reject: () => {
+      setSuggestions(null)
+      setError(null)
+    },
+  }
+}

From f2f2b62f18bffb90e77405c33f80ffea0573de40 Mon Sep 17 00:00:00 2001
From: DavidBabinec <hello@davidbabinec.com>
Date: Fri, 12 Jun 2026 15:37:15 +0200
Subject: [PATCH 13/26] =?UTF-8?q?style(seo):=20inline=20index=20rows=20?=
 =?UTF-8?q?=E2=80=94=20title=20+=20route=20on=20one=20baseline,=20no=20acc?=
 =?UTF-8?q?ent=20bar?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Target index rows render title and route/descriptor in a single
baseline-aligned line with a 6px gap instead of two stacked lines, and
the selected row drops the inset left accent shadow.

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
---
 .../pages/seo/components/SeoTargetIndex.module.css   | 12 +++++++++---
 1 file changed, 9 insertions(+), 3 deletions(-)

diff --git a/src/admin/pages/seo/components/SeoTargetIndex.module.css b/src/admin/pages/seo/components/SeoTargetIndex.module.css
index b5418e18d..192ff16ef 100644
--- a/src/admin/pages/seo/components/SeoTargetIndex.module.css
+++ b/src/admin/pages/seo/components/SeoTargetIndex.module.css
@@ -126,13 +126,13 @@
 .selected,
 .selected:hover {
     background: var(--editor-surface-4);
-    box-shadow: inset 2px 0 0 var(--editor-accent);
 }
 
+/* Title + route/descriptor inline on one baseline. */
 .rowText {
     display: flex;
-    flex-direction: column;
-    gap: 1px;
+    align-items: baseline;
+    gap: 6px;
     min-width: 0;
 }
 
@@ -144,8 +144,10 @@
     white-space: nowrap;
     overflow: hidden;
     text-overflow: ellipsis;
+    min-width: 0;
 }
 
+/* Route/descriptor gives way before the title when space runs out. */
 .rowRoute {
     font-size: 10.5px;
     line-height: 15px;
@@ -154,6 +156,8 @@
     white-space: nowrap;
     overflow: hidden;
     text-overflow: ellipsis;
+    min-width: 0;
+    flex-shrink: 4;
 }
 
 .rowDescriptor {
@@ -163,6 +167,8 @@
     white-space: nowrap;
     overflow: hidden;
     text-overflow: ellipsis;
+    min-width: 0;
+    flex-shrink: 4;
 }
 
 /* Tiered score pill — tinted background + matching text, mono digits. */

From 2438e267c1474ed6318a87a13c9f1ac447ad9944 Mon Sep 17 00:00:00 2001
From: DavidBabinec <hello@davidbabinec.com>
Date: Fri, 12 Jun 2026 15:55:18 +0200
Subject: [PATCH 14/26] refactor(seo): shared SeoFormRow + two-column
 Robots/Sitemap workbench
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Every form row in the SEO workspace now renders through one component:
SeoFormRow (muted label + control-stack grid) with a SeoSwitchRow boolean
variant. The Meta editor's MetaField, the noindex and select rows, the
site-defaults form, and SeoImageField all migrate onto it, deleting the
per-file copies of the grid CSS.

The Robots.txt and Sitemap tabs drop their single stacked column for the
same workbench split the Meta tab uses: settings card (large heading,
switch rows, counts) on the left, a sticky code preview on the right.
SeoCodeViewer becomes a proper surface card — CM6's own editor/gutter
backgrounds are flattened to the card surface and the read-only
active-line stripe is removed.

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
---
 docs/features/seo.md                          |  14 +-
 .../seo/components/SeoCodeViewer.module.css   |  24 ++-
 .../seo/components/SeoFormRow.module.css      |  63 ++++++++
 src/admin/pages/seo/components/SeoFormRow.tsx |  80 ++++++++++
 .../seo/components/SeoImageField.module.css   |  35 +---
 .../pages/seo/components/SeoImageField.tsx    |  11 +-
 .../components/SeoPreviewEditor.module.css    |  62 +-------
 .../pages/seo/components/SeoPreviewEditor.tsx |  50 +++---
 .../seo/components/SiteDefaultsEditor.tsx     |  31 ++--
 src/admin/pages/seo/tabs/RobotsTab.tsx        | 119 +++++++-------
 .../pages/seo/tabs/SettingsTabs.module.css    |  66 +++++---
 src/admin/pages/seo/tabs/SitemapTab.tsx       | 150 +++++++++---------
 12 files changed, 395 insertions(+), 310 deletions(-)
 create mode 100644 src/admin/pages/seo/components/SeoFormRow.module.css
 create mode 100644 src/admin/pages/seo/components/SeoFormRow.tsx

diff --git a/docs/features/seo.md b/docs/features/seo.md
index e35c008b2..2217c8d76 100644
--- a/docs/features/seo.md
+++ b/docs/features/seo.md
@@ -125,10 +125,16 @@ publish — the same machinery as the Site toolbar, not a parallel path.
   fields hide behind "Customize X preview" until set; switching targets
   while dirty asks via an in-app dialog. The Schema view pretty-prints the
   exact JSON-LD the publisher will emit.
-- **Robots.txt tab** — indexing + AI-crawler toggles over a live preview
-  generated by the same `generateRobotsTxt` the endpoint serves.
-- **Sitemap tab** — enable/disable, inclusion counts, per-target
-  include/exclude switches (noindex targets shown as auto-excluded).
+- **Robots.txt tab** — settings card (indexing + AI-crawler switch rows)
+  beside a sticky live preview generated by the same `generateRobotsTxt`
+  the endpoint serves.
+- **Sitemap tab** — settings card (enable switch + inclusion counts) and
+  per-target include/exclude list beside a sticky entry-format sample
+  (noindex targets shown as auto-excluded).
+
+All workspace forms render rows through the shared
+`components/SeoFormRow.tsx` (`SeoFormRow` / `SeoSwitchRow`): a two-column
+grid with muted labels left and the control stack right.
 
 ### AI suggestions
 
diff --git a/src/admin/pages/seo/components/SeoCodeViewer.module.css b/src/admin/pages/seo/components/SeoCodeViewer.module.css
index 44f305e91..28bfc57d3 100644
--- a/src/admin/pages/seo/components/SeoCodeViewer.module.css
+++ b/src/admin/pages/seo/components/SeoCodeViewer.module.css
@@ -1,11 +1,29 @@
+/* Card surface matching the workspace's form cards. The CM6 theme paints
+ * its own editor/gutter backgrounds for the code panel — flatten them here
+ * so the viewer reads as one quiet surface, and drop the active-line
+ * highlight (meaningless in a read-only viewer). */
 .viewer {
-    border-radius: var(--editor-radius);
-    overflow: hidden;
-    background: var(--editor-surface);
+    border-radius: 16px;
+    background: var(--editor-surface-2);
+    padding: 8px 4px;
     max-height: 420px;
     overflow-y: auto;
 }
 
+.viewer :global(.cm-editor) {
+    background: transparent;
+}
+
+.viewer :global(.cm-gutters) {
+    background: transparent;
+    border-right: 1px solid var(--panel-border);
+}
+
+.viewer :global(.cm-activeLine),
+.viewer :global(.cm-activeLineGutter) {
+    background: transparent;
+}
+
 .fallback {
     font-size: 11px;
 }
diff --git a/src/admin/pages/seo/components/SeoFormRow.module.css b/src/admin/pages/seo/components/SeoFormRow.module.css
new file mode 100644
index 000000000..60f56f79c
--- /dev/null
+++ b/src/admin/pages/seo/components/SeoFormRow.module.css
@@ -0,0 +1,63 @@
+/* Two-column field row: muted label (+ inline action) left, control stack
+ * right. Labels center against the control block; extra children (meters,
+ * hints, suggestion bubbles) stack under the control in the right column. */
+.row {
+    --seo-label-col: 140px;
+    display: grid;
+    grid-template-columns: var(--seo-label-col) minmax(0, 1fr);
+    column-gap: 18px;
+    row-gap: 6px;
+    align-items: center;
+    outline: none;
+}
+
+.row > * {
+    grid-column: 2;
+    min-width: 0;
+}
+
+.row > .labelCell {
+    grid-column: 1;
+    grid-row: 1;
+}
+
+.labelCell {
+    display: flex;
+    align-items: center;
+    justify-content: space-between;
+    gap: 8px;
+}
+
+.label {
+    font-size: 12.5px;
+    font-weight: 600;
+    color: var(--editor-text-muted);
+}
+
+/* Boolean rows: hint left, switch pinned right. */
+.switchRow {
+    display: flex;
+    align-items: center;
+    justify-content: space-between;
+    gap: 12px;
+}
+
+.hint {
+    font-size: 11px;
+    line-height: 1.4;
+    color: var(--editor-text-muted);
+}
+
+@media (max-width: 700px) {
+    .row {
+        grid-template-columns: 1fr;
+    }
+
+    .row > * {
+        grid-column: 1;
+    }
+
+    .row > .labelCell {
+        grid-row: auto;
+    }
+}
diff --git a/src/admin/pages/seo/components/SeoFormRow.tsx b/src/admin/pages/seo/components/SeoFormRow.tsx
new file mode 100644
index 000000000..92a13775e
--- /dev/null
+++ b/src/admin/pages/seo/components/SeoFormRow.tsx
@@ -0,0 +1,80 @@
+/**
+ * SeoFormRow — the SEO workspace's shared form row: a two-column grid with
+ * a muted label (plus optional inline action) on the left and the control
+ * stack on the right. Every form in the workspace — the Meta editor, the
+ * image fields, the Robots/Sitemap tabs — renders rows through this one
+ * component so they all read the same.
+ *
+ * SeoSwitchRow is the boolean variant: hint text left, Switch pinned right
+ * in the control column.
+ */
+import type { ReactNode } from 'react'
+import { Switch } from '@ui/components/Switch'
+import styles from './SeoFormRow.module.css'
+
+interface SeoFormRowProps {
+  label: string
+  /** Associates the label element with a control id. */
+  htmlFor?: string
+  /** Inline action rendered next to the label (e.g. the AI sparkle). */
+  labelAction?: ReactNode
+  /**
+   * Anchor id + programmatic focus target (tabIndex -1) — used by the Meta
+   * editor's improvements list for rows without a single focusable input.
+   */
+  anchorId?: string
+  children: ReactNode
+}
+
+export function SeoFormRow({ label, htmlFor, labelAction, anchorId, children }: SeoFormRowProps) {
+  return (
+    <div id={anchorId} tabIndex={anchorId !== undefined ? -1 : undefined} className={styles.row}>
+      <div className={styles.labelCell}>
+        {htmlFor !== undefined ? (
+          <label htmlFor={htmlFor} className={styles.label}>{label}</label>
+        ) : (
+          <span className={styles.label}>{label}</span>
+        )}
+        {labelAction}
+      </div>
+      {children}
+    </div>
+  )
+}
+
+interface SeoSwitchRowProps {
+  id: string
+  label: string
+  hint: string
+  checked: boolean
+  disabled?: boolean
+  onCheckedChange: (value: boolean) => void
+  'data-testid'?: string
+}
+
+export function SeoSwitchRow({
+  id,
+  label,
+  hint,
+  checked,
+  disabled,
+  onCheckedChange,
+  'data-testid': testId,
+}: SeoSwitchRowProps) {
+  return (
+    <SeoFormRow label={label} htmlFor={id}>
+      <div className={styles.switchRow}>
+        <span className={styles.hint}>{hint}</span>
+        <Switch
+          id={id}
+          checked={checked}
+          disabled={disabled}
+          onCheckedChange={onCheckedChange}
+          aria-label={label}
+          switchSize="sm"
+          data-testid={testId}
+        />
+      </div>
+    </SeoFormRow>
+  )
+}
diff --git a/src/admin/pages/seo/components/SeoImageField.module.css b/src/admin/pages/seo/components/SeoImageField.module.css
index 948725fcb..9c704cb50 100644
--- a/src/admin/pages/seo/components/SeoImageField.module.css
+++ b/src/admin/pages/seo/components/SeoImageField.module.css
@@ -1,28 +1,5 @@
-/* Mirrors SeoPreviewEditor's two-column field grid — the shared
- * --seo-label-col is defined on the parent .form. The control column stacks
- * the Library/URL toggle over the picker tile, so labels top-align. */
-.field {
-    display: grid;
-    grid-template-columns: var(--seo-label-col) minmax(0, 1fr);
-    column-gap: 18px;
-    align-items: start;
-    outline: none;
-}
-
-.label {
-    font-size: 12.5px;
-    font-weight: 600;
-    color: var(--editor-text-muted);
-    padding-top: 6px;
-}
-
-.body {
-    display: flex;
-    flex-direction: column;
-    gap: 6px;
-    min-width: 0;
-}
-
+/* Row layout comes from the shared SeoFormRow; this module only styles the
+ * URL-mode body and inline status lines. */
 .status {
     margin: 0;
     font-size: 11px;
@@ -33,6 +10,7 @@
     display: flex;
     flex-direction: column;
     gap: 6px;
+    min-width: 0;
 }
 
 .urlPreview {
@@ -48,10 +26,3 @@
     max-height: 140px;
     object-fit: cover;
 }
-
-@media (max-width: 700px) {
-    .field {
-        grid-template-columns: 1fr;
-        row-gap: 6px;
-    }
-}
diff --git a/src/admin/pages/seo/components/SeoImageField.tsx b/src/admin/pages/seo/components/SeoImageField.tsx
index f3cd9b633..2c163d608 100644
--- a/src/admin/pages/seo/components/SeoImageField.tsx
+++ b/src/admin/pages/seo/components/SeoImageField.tsx
@@ -16,6 +16,7 @@ import { listCmsMediaAssets, type CmsMediaAsset } from '@core/persistence/cmsMed
 import { isValidImageUrl } from '@core/utils/urlValidation'
 import { getErrorMessage } from '@core/utils/errorMessage'
 import { MediaPickerField } from '@admin/pages/media/components/MediaPickerField'
+import { SeoFormRow } from './SeoFormRow'
 import styles from './SeoImageField.module.css'
 
 const MediaPickerModal = lazy(() =>
@@ -89,11 +90,8 @@ export function SeoImageField({ label, fieldId, value, inheritedValue, disabled,
   }
 
   return (
-    /* tabIndex -1: programmatic focus target for the improvements list. */
-    <div id={fieldId} tabIndex={-1} className={styles.field}>
-      <span className={styles.label}>{label}</span>
-      <div className={styles.body}>
-        <SegmentedControl<Mode>
+    <SeoFormRow label={label} anchorId={fieldId}>
+      <SegmentedControl<Mode>
           value={mode}
           options={SOURCE_OPTIONS}
           onChange={setMode}
@@ -154,7 +152,6 @@ export function SeoImageField({ label, fieldId, value, inheritedValue, disabled,
             )}
           </div>
         )}
-      </div>
       {pickerOpen && (
         <Suspense fallback={null}>
           <MediaPickerModal
@@ -166,6 +163,6 @@ export function SeoImageField({ label, fieldId, value, inheritedValue, disabled,
           />
         </Suspense>
       )}
-    </div>
+    </SeoFormRow>
   )
 }
diff --git a/src/admin/pages/seo/components/SeoPreviewEditor.module.css b/src/admin/pages/seo/components/SeoPreviewEditor.module.css
index f80326629..bded0e902 100644
--- a/src/admin/pages/seo/components/SeoPreviewEditor.module.css
+++ b/src/admin/pages/seo/components/SeoPreviewEditor.module.css
@@ -21,9 +21,6 @@
     border-radius: 16px;
     padding: 20px;
     min-width: 0;
-    /* Shared label-column width for every field row in the form, including
-       the SeoImageField rows rendered inside it. */
-    --seo-label-col: 140px;
 }
 
 .header {
@@ -136,63 +133,8 @@
     color: var(--editor-text-bright);
 }
 
-/* Field shell — two-column grid row: muted label (+ sparkle) on the left,
- * control + meter/hint stacked on the right. Labels center against the
- * control block. */
-.field {
-    display: grid;
-    grid-template-columns: var(--seo-label-col) minmax(0, 1fr);
-    column-gap: 18px;
-    row-gap: 6px;
-    align-items: center;
-}
-
-.field > * {
-    grid-column: 2;
-    min-width: 0;
-}
-
-.field > .fieldLabelRow,
-.field > .fieldLabel {
-    grid-column: 1;
-    grid-row: 1;
-}
-
-.fieldLabelRow {
-    display: flex;
-    align-items: center;
-    justify-content: space-between;
-    gap: 8px;
-}
-
-.fieldLabel {
-    font-size: 12.5px;
-    font-weight: 600;
-    color: var(--editor-text-muted);
-}
-
-/* noindex row: hint left, switch pinned right — same grid as every field. */
-.switchRow {
-    display: flex;
-    align-items: center;
-    justify-content: space-between;
-    gap: 12px;
-}
-
-@media (max-width: 700px) {
-    .field {
-        grid-template-columns: 1fr;
-    }
-
-    .field > * {
-        grid-column: 1;
-    }
-
-    .field > .fieldLabelRow,
-    .field > .fieldLabel {
-        grid-row: auto;
-    }
-}
+/* Field rows render through the shared SeoFormRow component — see
+ * SeoFormRow.module.css for the two-column grid. */
 
 .fieldHint {
     margin: 0;
diff --git a/src/admin/pages/seo/components/SeoPreviewEditor.tsx b/src/admin/pages/seo/components/SeoPreviewEditor.tsx
index fecec0afe..68c0e6fad 100644
--- a/src/admin/pages/seo/components/SeoPreviewEditor.tsx
+++ b/src/admin/pages/seo/components/SeoPreviewEditor.tsx
@@ -23,7 +23,6 @@ import { useId, useState } from 'react'
 import { Button } from '@ui/components/Button'
 import { Input, Textarea } from '@ui/components/Input'
 import { Select } from '@ui/components/Select'
-import { Switch } from '@ui/components/Switch'
 import { Separator } from '@ui/components/Separator'
 import { getErrorMessage } from '@core/utils/errorMessage'
 import { isSafeCanonicalUrl, computeSeoReport, type SeoCheckId } from '@core/seo'
@@ -44,6 +43,7 @@ import { MetaLengthMeter } from './MetaLengthMeter'
 import { SeoImageField } from './SeoImageField'
 import { useAiSuggestions } from '../hooks/useAiSuggestions'
 import { AiSuggestionSparkle, AiSuggestionResults } from './AiSuggestionBubbles'
+import { SeoFormRow, SeoSwitchRow } from './SeoFormRow'
 import styles from './SeoPreviewEditor.module.css'
 
 interface SeoPreviewEditorProps {
@@ -269,24 +269,14 @@ export function SeoPreviewEditor({ target, workspace, canManage, bridge }: SeoPr
         {canonicalInvalid && (
           <p className={styles.error} role="alert">Canonical URL must be an absolute http(s) URL.</p>
         )}
-        <div className={styles.field}>
-          <label htmlFor={`${fieldIdBase}-noindex`} className={styles.fieldLabel}>
-            Exclude from search engines
-          </label>
-          <div className={styles.switchRow}>
-            <span className={styles.fieldHint}>
-              Emits noindex — the page disappears from search and answer engines.
-            </span>
-            <Switch
-              id={`${fieldIdBase}-noindex`}
-              checked={draft.draft.noindex === true}
-              onCheckedChange={draft.setNoindex}
-              disabled={!canManage}
-              aria-label="Exclude from search engines (noindex)"
-              switchSize="sm"
-            />
-          </div>
-        </div>
+        <SeoSwitchRow
+          id={`${fieldIdBase}-noindex`}
+          label="Exclude from search engines"
+          hint="Emits noindex — the page disappears from search and answer engines."
+          checked={draft.draft.noindex === true}
+          disabled={!canManage}
+          onCheckedChange={draft.setNoindex}
+        />
 
         <Separator />
         <h3 className={styles.sectionHeading}>Social card (Open Graph)</h3>
@@ -301,8 +291,7 @@ export function SeoPreviewEditor({ target, workspace, canManage, bridge }: SeoPr
           onChange={(next) => draft.setField('ogImage', next)}
         />
         {field('ogImageAlt', 'OG image alt')}
-        <div className={styles.field}>
-          <label htmlFor={`${fieldIdBase}-ogType`} className={styles.fieldLabel}>OG type</label>
+        <SeoFormRow label="OG type" htmlFor={`${fieldIdBase}-ogType`}>
           <Select
             id={`${fieldIdBase}-ogType`}
             value={draft.draft.ogType ?? ''}
@@ -313,7 +302,7 @@ export function SeoPreviewEditor({ target, workspace, canManage, bridge }: SeoPr
             <option value="website">website</option>
             <option value="article">article</option>
           </Select>
-        </div>
+        </SeoFormRow>
 
         <Separator />
         <h3 className={styles.sectionHeading}>X card</h3>
@@ -338,8 +327,7 @@ export function SeoPreviewEditor({ target, workspace, canManage, bridge }: SeoPr
               onChange={(next) => draft.setField('xImage', next)}
             />
             {field('xImageAlt', 'X image alt')}
-            <div className={styles.field}>
-              <label htmlFor={`${fieldIdBase}-xCard`} className={styles.fieldLabel}>Card type</label>
+            <SeoFormRow label="Card type" htmlFor={`${fieldIdBase}-xCard`}>
               <Select
                 id={`${fieldIdBase}-xCard`}
                 value={draft.draft.xCard ?? ''}
@@ -350,7 +338,7 @@ export function SeoPreviewEditor({ target, workspace, canManage, bridge }: SeoPr
                 <option value="summary">summary</option>
                 <option value="summary_large_image">summary_large_image</option>
               </Select>
-            </div>
+            </SeoFormRow>
           </>
         )}
       </section>
@@ -406,11 +394,11 @@ function MetaField({
     'aria-invalid': invalid || undefined,
   }
   return (
-    <div className={styles.field}>
-      <div className={styles.fieldLabelRow}>
-        <label htmlFor={id} className={styles.fieldLabel}>{label}</label>
-        {sparkle && <AiSuggestionSparkle ai={ai} canManage={canManage} />}
-      </div>
+    <SeoFormRow
+      label={label}
+      htmlFor={id}
+      labelAction={sparkle ? <AiSuggestionSparkle ai={ai} canManage={canManage} /> : undefined}
+    >
       {textarea ? (
         <Textarea {...common} rows={3} onChange={(e) => onChange(e.target.value)} />
       ) : (
@@ -426,6 +414,6 @@ function MetaField({
         />
       )}
       <AiSuggestionResults ai={ai} />
-    </div>
+    </SeoFormRow>
   )
 }
diff --git a/src/admin/pages/seo/components/SiteDefaultsEditor.tsx b/src/admin/pages/seo/components/SiteDefaultsEditor.tsx
index be6399586..c34981a5b 100644
--- a/src/admin/pages/seo/components/SiteDefaultsEditor.tsx
+++ b/src/admin/pages/seo/components/SiteDefaultsEditor.tsx
@@ -24,6 +24,7 @@ import { useSeoSaveSurface } from '../hooks/useSeoSaveBridge'
 import { resolveTargetSeo } from '../lib/resolveTargetSeo'
 import { SeoPreviewRail } from './SeoPreviewRail'
 import { SeoImageField } from './SeoImageField'
+import { SeoFormRow } from './SeoFormRow'
 import styles from './SeoPreviewEditor.module.css'
 
 type SiteStringField =
@@ -198,8 +199,7 @@ export function SiteDefaultsEditor({ workspace, canManage, bridge }: SiteDefault
         )}
 
         <h3 className={styles.sectionHeading}>Defaults</h3>
-        <div className={styles.field}>
-          <label htmlFor={`${idBase}-pattern`} className={styles.fieldLabel}>Title pattern</label>
+        <SeoFormRow label="Title pattern" htmlFor={`${idBase}-pattern`}>
           <Input
             id={`${idBase}-pattern`}
             type="text"
@@ -212,10 +212,9 @@ export function SiteDefaultsEditor({ workspace, canManage, bridge }: SiteDefault
             Tokens: <code>{'{page.title}'}</code>, <code>{'{site.name}'}</code>, <code>{'{currentEntry.title}'}</code>.
             Targets with an explicit SEO title skip the pattern.
           </p>
-        </div>
+        </SeoFormRow>
 
-        <div className={styles.field}>
-          <label htmlFor={`${idBase}-description`} className={styles.fieldLabel}>Site description</label>
+        <SeoFormRow label="Site description" htmlFor={`${idBase}-description`}>
           <Textarea
             id={`${idBase}-description`}
             rows={3}
@@ -224,7 +223,7 @@ export function SiteDefaultsEditor({ workspace, canManage, bridge }: SiteDefault
             disabled={!canManage}
             onChange={(e) => setField('description', e.target.value)}
           />
-        </div>
+        </SeoFormRow>
 
         <SeoImageField
           label="Default social image"
@@ -234,8 +233,7 @@ export function SiteDefaultsEditor({ workspace, canManage, bridge }: SiteDefault
           onChange={(next) => setField('defaultOgImage', next)}
         />
 
-        <div className={styles.field}>
-          <label htmlFor={`${idBase}-ogalt`} className={styles.fieldLabel}>Default image alt text</label>
+        <SeoFormRow label="Default image alt text" htmlFor={`${idBase}-ogalt`}>
           <Input
             id={`${idBase}-ogalt`}
             type="text"
@@ -243,10 +241,9 @@ export function SiteDefaultsEditor({ workspace, canManage, bridge }: SiteDefault
             disabled={!canManage}
             onChange={(e) => setField('defaultOgImageAlt', e.target.value)}
           />
-        </div>
+        </SeoFormRow>
 
-        <div className={styles.field}>
-          <label htmlFor={`${idBase}-xcard`} className={styles.fieldLabel}>Default X card</label>
+        <SeoFormRow label="Default X card" htmlFor={`${idBase}-xcard`}>
           <Select
             id={`${idBase}-xcard`}
             value={draft.defaultXCard ?? ''}
@@ -266,10 +263,9 @@ export function SiteDefaultsEditor({ workspace, canManage, bridge }: SiteDefault
             <option value="summary">summary</option>
             <option value="summary_large_image">summary_large_image</option>
           </Select>
-        </div>
+        </SeoFormRow>
 
-        <div className={styles.field}>
-          <label htmlFor={`${idBase}-xhandle`} className={styles.fieldLabel}>X site handle</label>
+        <SeoFormRow label="X site handle" htmlFor={`${idBase}-xhandle`}>
           <Input
             id={`${idBase}-xhandle`}
             type="text"
@@ -278,7 +274,7 @@ export function SiteDefaultsEditor({ workspace, canManage, bridge }: SiteDefault
             disabled={!canManage}
             onChange={(e) => setField('xSiteHandle', e.target.value)}
           />
-        </div>
+        </SeoFormRow>
 
         <Separator />
         <h3 className={styles.sectionHeading}>Organization (structured data)</h3>
@@ -287,8 +283,7 @@ export function SiteDefaultsEditor({ workspace, canManage, bridge }: SiteDefault
           how answer engines identify who runs this site.
         </p>
 
-        <div className={styles.field}>
-          <label htmlFor={`${idBase}-orgname`} className={styles.fieldLabel}>Organization name</label>
+        <SeoFormRow label="Organization name" htmlFor={`${idBase}-orgname`}>
           <Input
             id={`${idBase}-orgname`}
             type="text"
@@ -296,7 +291,7 @@ export function SiteDefaultsEditor({ workspace, canManage, bridge }: SiteDefault
             disabled={!canManage}
             onChange={(e) => setOrgField('name', e.target.value)}
           />
-        </div>
+        </SeoFormRow>
 
         <SeoImageField
           label="Organization logo"
diff --git a/src/admin/pages/seo/tabs/RobotsTab.tsx b/src/admin/pages/seo/tabs/RobotsTab.tsx
index 38bc51d70..3235bd09b 100644
--- a/src/admin/pages/seo/tabs/RobotsTab.tsx
+++ b/src/admin/pages/seo/tabs/RobotsTab.tsx
@@ -1,15 +1,14 @@
 /**
  * RobotsTab — generated robots.txt controls + live preview.
  *
- * Three FormField-wrapped switches (indexing, AI training crawlers, AI
- * answer crawlers) over a byte-identical CodeMirror preview of the served
- * file — the preview calls the same `generateRobotsTxt` the server endpoint
- * uses. Saving writes `site.settings.seo.robots`; output goes live with the
+ * Two-column workbench: the settings card (shared SeoSwitchRow rows —
+ * indexing, AI training crawlers, AI answer crawlers) on the left, a sticky
+ * byte-identical CodeMirror preview of the served file on the right — the
+ * preview calls the same `generateRobotsTxt` the server endpoint uses.
+ * Saving writes `site.settings.seo.robots`; output goes live with the
  * publish lifecycle.
  */
 import { useState } from 'react'
-import { Switch } from '@ui/components/Switch'
-import { FormField } from '@ui/components/FormField'
 import { getErrorMessage } from '@core/utils/errorMessage'
 import { publishCmsDraft } from '@core/persistence'
 import { hasCapability } from '@admin/access'
@@ -22,6 +21,7 @@ import {
   type SeoRobotsSettings,
 } from '@core/seo'
 import { SeoCodeViewer } from '../components/SeoCodeViewer'
+import { SeoSwitchRow } from '../components/SeoFormRow'
 import type { SeoWorkspace } from '../hooks/useSeoWorkspace'
 import type { SeoSaveBridge } from '../hooks/useSeoSaveBridge'
 import { useSeoSaveSurface } from '../hooks/useSeoSaveBridge'
@@ -103,66 +103,59 @@ export function RobotsTab({ workspace, canManage, bridge }: RobotsTabProps) {
 
   return (
     <section className={styles.tab} aria-label="Robots.txt settings">
-      <header className={styles.header}>
-        <div>
-          <h2 className={styles.heading}>Robots.txt</h2>
-          <p className={styles.subheading}>
-            Generated automatically and served at <code>/robots.txt</code>. Changes go live on the next publish.
-          </p>
+      <div className={styles.workbench}>
+        <div className={styles.settingsColumn}>
+          {saveError && <p className={styles.error} role="alert">{saveError}</p>}
+          {!workspace.publicOrigin && (
+            <p className={styles.notice} role="status">
+              No public origin configured — set the <code>PUBLIC_ORIGINS</code> environment
+              variable so the sitemap link (and canonical URLs) use your real domain.
+            </p>
+          )}
+
+          <div className={styles.card}>
+            <header className={styles.cardHeader}>
+              <h2 className={styles.heading}>Robots.txt</h2>
+              <p className={styles.subheading}>
+                Generated automatically and served at <code>/robots.txt</code>. Changes go live on the next publish.
+              </p>
+            </header>
+
+            <SeoSwitchRow
+              id="seo-robots-indexing-switch"
+              label="Search indexing"
+              hint="Turning this off serves a global Disallow — the whole site disappears from search."
+              checked={draft.indexingEnabled !== false}
+              disabled={!canManage}
+              onCheckedChange={(value) => setFlag('indexingEnabled', value)}
+              data-testid="seo-robots-indexing"
+            />
+            <SeoSwitchRow
+              id="seo-robots-ai-training-switch"
+              label="AI training crawlers"
+              hint={`Bots that ingest content for model training: ${AI_TRAINING_CRAWLERS.join(', ')}.`}
+              checked={draft.allowAiTrainingCrawlers !== false}
+              disabled={!canManage || draft.indexingEnabled === false}
+              onCheckedChange={(value) => setFlag('allowAiTrainingCrawlers', value)}
+              data-testid="seo-robots-ai-training"
+            />
+            <SeoSwitchRow
+              id="seo-robots-ai-answer-switch"
+              label="AI answer crawlers"
+              hint={`Bots that fetch content to ground live AI answers: ${AI_ANSWER_CRAWLERS.join(', ')}. Blocking these removes the site from AI search results.`}
+              checked={draft.allowAiAnswerCrawlers !== false}
+              disabled={!canManage || draft.indexingEnabled === false}
+              onCheckedChange={(value) => setFlag('allowAiAnswerCrawlers', value)}
+              data-testid="seo-robots-ai-answer"
+            />
+          </div>
         </div>
-      </header>
-      {saveError && <p className={styles.error} role="alert">{saveError}</p>}
-      {!workspace.publicOrigin && (
-        <p className={styles.notice} role="status">
-          No public origin configured — set the <code>PUBLIC_ORIGINS</code> environment
-          variable so the sitemap link (and canonical URLs) use your real domain.
-        </p>
-      )}
 
-      <div className={styles.controls}>
-        <FormField
-          layout="inline-end"
-          label="Allow search engine indexing"
-          description="Turning this off serves a global Disallow — the whole site disappears from search."
-        >
-          <Switch
-            checked={draft.indexingEnabled !== false}
-            onCheckedChange={(value) => setFlag('indexingEnabled', value)}
-            disabled={!canManage}
-            aria-label="Allow search engine indexing"
-            data-testid="seo-robots-indexing"
-          />
-        </FormField>
-        <FormField
-          layout="inline-end"
-          label="Allow AI training crawlers"
-          description={`Bots that ingest content for model training: ${AI_TRAINING_CRAWLERS.join(', ')}.`}
-        >
-          <Switch
-            checked={draft.allowAiTrainingCrawlers !== false}
-            onCheckedChange={(value) => setFlag('allowAiTrainingCrawlers', value)}
-            disabled={!canManage || draft.indexingEnabled === false}
-            aria-label="Allow AI training crawlers"
-            data-testid="seo-robots-ai-training"
-          />
-        </FormField>
-        <FormField
-          layout="inline-end"
-          label="Allow AI search & answer crawlers"
-          description={`Bots that fetch content to ground live AI answers: ${AI_ANSWER_CRAWLERS.join(', ')}. Blocking these removes the site from AI search results.`}
-        >
-          <Switch
-            checked={draft.allowAiAnswerCrawlers !== false}
-            onCheckedChange={(value) => setFlag('allowAiAnswerCrawlers', value)}
-            disabled={!canManage || draft.indexingEnabled === false}
-            aria-label="Allow AI search & answer crawlers"
-            data-testid="seo-robots-ai-answer"
-          />
-        </FormField>
+        <aside className={styles.previewColumn} aria-label="robots.txt preview">
+          <h3 className={styles.previewHeading}>Preview</h3>
+          <SeoCodeViewer docKey="robots-preview" value={preview} language="text" data-testid="seo-robots-preview" />
+        </aside>
       </div>
-
-      <h3 className={styles.previewHeading}>Preview</h3>
-      <SeoCodeViewer docKey="robots-preview" value={preview} language="text" data-testid="seo-robots-preview" />
     </section>
   )
 }
diff --git a/src/admin/pages/seo/tabs/SettingsTabs.module.css b/src/admin/pages/seo/tabs/SettingsTabs.module.css
index b965bd101..acf1b9a9a 100644
--- a/src/admin/pages/seo/tabs/SettingsTabs.module.css
+++ b/src/admin/pages/seo/tabs/SettingsTabs.module.css
@@ -1,28 +1,67 @@
-/* Shared layout for the Robots.txt and Sitemap settings tabs. */
+/* Shared layout for the Robots.txt and Sitemap settings tabs: a two-column
+ * workbench — settings card (left) and a sticky code preview (right) —
+ * mirroring the Meta tab's editor/preview split. */
 
 .tab {
+    min-width: 0;
+}
+
+.workbench {
+    display: grid;
+    grid-template-columns: minmax(0, 1fr) minmax(320px, 440px);
+    gap: 24px;
+    align-items: start;
+}
+
+@media (max-width: 1100px) {
+    .workbench {
+        grid-template-columns: 1fr;
+    }
+}
+
+.settingsColumn {
     display: flex;
     flex-direction: column;
     gap: 18px;
-    max-width: 720px;
+    min-width: 0;
 }
 
-.header {
+.previewColumn {
+    position: sticky;
+    top: 0;
+    align-self: start;
     display: flex;
-    align-items: flex-start;
-    justify-content: space-between;
-    gap: 12px;
+    flex-direction: column;
+    gap: 8px;
+    min-width: 0;
+}
+
+/* Same card shell as the Meta editor's form. */
+.card {
+    display: flex;
+    flex-direction: column;
+    gap: 16px;
+    background: var(--editor-surface-2);
+    border-radius: 16px;
+    padding: 20px;
+    min-width: 0;
+}
+
+.cardHeader {
+    display: flex;
+    flex-direction: column;
+    gap: 2px;
 }
 
 .heading {
     margin: 0;
-    font-size: 16px;
+    font-size: 18px;
     font-weight: 700;
     color: var(--editor-text-bright);
 }
 
 .subheading {
-    margin: 4px 0 0;
+    margin: 0;
     font-size: 12px;
     color: var(--editor-text-muted);
 }
@@ -42,17 +81,8 @@
     color: var(--editor-warning-text);
 }
 
-.controls {
-    display: flex;
-    flex-direction: column;
-    gap: 14px;
-    background: var(--editor-surface-2);
-    border-radius: 16px;
-    padding: 16px 20px;
-}
-
 .previewHeading {
-    margin: 4px 0 0;
+    margin: 0;
     font-size: 13px;
     font-weight: 700;
     color: var(--editor-text-bright);
diff --git a/src/admin/pages/seo/tabs/SitemapTab.tsx b/src/admin/pages/seo/tabs/SitemapTab.tsx
index b589cacfc..6519c6d65 100644
--- a/src/admin/pages/seo/tabs/SitemapTab.tsx
+++ b/src/admin/pages/seo/tabs/SitemapTab.tsx
@@ -1,14 +1,14 @@
 /**
  * SitemapTab — sitemap.xml generation settings.
  *
- * Enable/disable, inclusion counts (computed from the same target data the
- * Meta tab uses), and per-target include/exclude switches for routable
- * targets. Noindex targets are excluded automatically and shown as such —
- * the control is disabled with the reason inline.
+ * Two-column workbench: the settings card (enable switch + inclusion
+ * counts) and the per-target include/exclude list on the left, a sticky
+ * entry-format sample on the right. Noindex targets are excluded
+ * automatically and shown as such — the control is disabled with the
+ * reason inline.
  */
 import { useState } from 'react'
 import { Switch } from '@ui/components/Switch'
-import { FormField } from '@ui/components/FormField'
 import { getErrorMessage } from '@core/utils/errorMessage'
 import { publishCmsDraft } from '@core/persistence'
 import { hasCapability } from '@admin/access'
@@ -16,6 +16,7 @@ import { useCurrentAdminUser } from '@admin/sessionContext'
 import { StepUpCancelledMessage, useStepUp } from '@admin/shared/StepUp'
 import type { SeoSitemapSettings } from '@core/seo'
 import { SeoCodeViewer } from '../components/SeoCodeViewer'
+import { SeoSwitchRow } from '../components/SeoFormRow'
 import type { SeoWorkspace } from '../hooks/useSeoWorkspace'
 import type { SeoSaveBridge } from '../hooks/useSeoSaveBridge'
 import { useSeoSaveSurface } from '../hooks/useSeoSaveBridge'
@@ -110,80 +111,81 @@ export function SitemapTab({ workspace, canManage, bridge }: SitemapTabProps) {
 
   return (
     <section className={styles.tab} aria-label="Sitemap settings">
-      <header className={styles.header}>
-        <div>
-          <h2 className={styles.heading}>Sitemap</h2>
-          <p className={styles.subheading}>
-            Generated from published content and served at <code>/sitemap.xml</code>. Changes go live on the next publish.
-          </p>
-        </div>
-      </header>
-      {saveError && <p className={styles.error} role="alert">{saveError}</p>}
-      {!workspace.publicOrigin && (
-        <p className={styles.notice} role="status">
-          No public origin configured — set the <code>PUBLIC_ORIGINS</code> environment
-          variable so sitemap URLs use your real domain.
-        </p>
-      )}
+      <div className={styles.workbench}>
+        <div className={styles.settingsColumn}>
+          {saveError && <p className={styles.error} role="alert">{saveError}</p>}
+          {!workspace.publicOrigin && (
+            <p className={styles.notice} role="status">
+              No public origin configured — set the <code>PUBLIC_ORIGINS</code> environment
+              variable so sitemap URLs use your real domain.
+            </p>
+          )}
 
-      <div className={styles.controls}>
-        <FormField
-          layout="inline-end"
-          label="Generate sitemap.xml"
-          description="Search and answer engines use the sitemap to discover published pages and posts."
-        >
-          <Switch
-            checked={enabled}
-            disabled={!canManage}
-            onCheckedChange={(value) => {
-              setDraft((current) => {
-                const next = { ...current }
-                if (value) delete next.enabled
-                else next.enabled = false
-                return next
-              })
-              if (saveState !== 'idle') setSaveState('idle')
-            }}
-            aria-label="Generate sitemap.xml"
-            data-testid="seo-sitemap-enabled"
-          />
-        </FormField>
-      </div>
+          <div className={styles.card}>
+            <header className={styles.cardHeader}>
+              <h2 className={styles.heading}>Sitemap</h2>
+              <p className={styles.subheading}>
+                Generated from published content and served at <code>/sitemap.xml</code>. Changes go live on the next publish.
+              </p>
+            </header>
 
-      <p className={styles.counts} role="status" data-testid="seo-sitemap-counts">
-        {enabled
-          ? `${included.length} of ${routable.length} routable targets included.`
-          : 'Sitemap generation is disabled — /sitemap.xml returns 404.'}
-      </p>
+            <SeoSwitchRow
+              id="seo-sitemap-enabled-switch"
+              label="Generate sitemap.xml"
+              hint="Search and answer engines use the sitemap to discover published pages and posts."
+              checked={enabled}
+              disabled={!canManage}
+              onCheckedChange={(value) => {
+                setDraft((current) => {
+                  const next = { ...current }
+                  if (value) delete next.enabled
+                  else next.enabled = false
+                  return next
+                })
+                if (saveState !== 'idle') setSaveState('idle')
+              }}
+              data-testid="seo-sitemap-enabled"
+            />
 
-      {enabled && (
-        <div className={styles.targetList} aria-label="Sitemap inclusion">
-          {routable.map((target) => {
-            const kindKey = target.kind === 'post' ? 'row' as const : 'page' as const
-            const noindexed = target.seo?.noindex === true
-            const isIncluded = !noindexed && !excluded.has(`${kindKey}:${target.id}`)
-            return (
-              <div key={target.id} className={styles.targetRow}>
-                <Switch
-                  checked={isIncluded}
-                  disabled={!canManage || noindexed}
-                  onCheckedChange={(value) => toggleTarget(kindKey, target.id, value)}
-                  aria-label={`Include ${target.title} in the sitemap`}
-                  switchSize="sm"
-                />
-                <span className={styles.targetTitle}>{target.title}</span>
-                <span className={styles.targetRoute}>{target.route}</span>
-                {noindexed && (
-                  <span className={styles.targetNote}>noindex — excluded automatically</span>
-                )}
-              </div>
-            )
-          })}
+            <p className={styles.counts} role="status" data-testid="seo-sitemap-counts">
+              {enabled
+                ? `${included.length} of ${routable.length} routable targets included.`
+                : 'Sitemap generation is disabled — /sitemap.xml returns 404.'}
+            </p>
+          </div>
+
+          {enabled && (
+            <div className={styles.targetList} aria-label="Sitemap inclusion">
+              {routable.map((target) => {
+                const kindKey = target.kind === 'post' ? 'row' as const : 'page' as const
+                const noindexed = target.seo?.noindex === true
+                const isIncluded = !noindexed && !excluded.has(`${kindKey}:${target.id}`)
+                return (
+                  <div key={target.id} className={styles.targetRow}>
+                    <Switch
+                      checked={isIncluded}
+                      disabled={!canManage || noindexed}
+                      onCheckedChange={(value) => toggleTarget(kindKey, target.id, value)}
+                      aria-label={`Include ${target.title} in the sitemap`}
+                      switchSize="sm"
+                    />
+                    <span className={styles.targetTitle}>{target.title}</span>
+                    <span className={styles.targetRoute}>{target.route}</span>
+                    {noindexed && (
+                      <span className={styles.targetNote}>noindex — excluded automatically</span>
+                    )}
+                  </div>
+                )
+              })}
+            </div>
+          )}
         </div>
-      )}
 
-      <h3 className={styles.previewHeading}>Entry format</h3>
-      <SeoCodeViewer docKey="sitemap-sample" value={sampleEntry(workspace)} language="html" />
+        <aside className={styles.previewColumn} aria-label="Sitemap entry format">
+          <h3 className={styles.previewHeading}>Entry format</h3>
+          <SeoCodeViewer docKey="sitemap-sample" value={sampleEntry(workspace)} language="html" />
+        </aside>
+      </div>
     </section>
   )
 }

From 92e990d84cf2b32f53a7e4df6e34f009b1e31e83 Mon Sep 17 00:00:00 2001
From: DavidBabinec <hello@davidbabinec.com>
Date: Fri, 12 Jun 2026 17:04:17 +0200
Subject: [PATCH 15/26] style(seo,ui): high-contrast switches, bigger row text,
 roomier cards
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

The Switch primitive's on-state was surface-3 on surface-2 — nearly
invisible. Globally: on = white (accent) track with a dark thumb, off =
raised surface-4 track with a light thumb, plus a real disabled
treatment. The unused hitArea variant is deleted. SEO switch rows move
from the sm switch to the full-size one.

Form rows step up for contrast: labels 13px --editor-text, hints 12px
weight-500 --editor-text-secondary; card subheadings match. Settings
cards gain padding (24px) and row spacing (22px); the Meta form
breathes a little more too.

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
---
 .../seo/components/SeoFormRow.module.css      | 15 +++----
 src/admin/pages/seo/components/SeoFormRow.tsx |  1 -
 .../components/SeoPreviewEditor.module.css    |  9 +++--
 .../pages/seo/tabs/SettingsTabs.module.css    | 13 +++---
 src/ui/components/Switch/Switch.module.css    | 40 +++++--------------
 src/ui/components/Switch/Switch.tsx           |  3 --
 6 files changed, 29 insertions(+), 52 deletions(-)

diff --git a/src/admin/pages/seo/components/SeoFormRow.module.css b/src/admin/pages/seo/components/SeoFormRow.module.css
index 60f56f79c..7d1521b6e 100644
--- a/src/admin/pages/seo/components/SeoFormRow.module.css
+++ b/src/admin/pages/seo/components/SeoFormRow.module.css
@@ -2,7 +2,7 @@
  * right. Labels center against the control block; extra children (meters,
  * hints, suggestion bubbles) stack under the control in the right column. */
 .row {
-    --seo-label-col: 140px;
+    --seo-label-col: 150px;
     display: grid;
     grid-template-columns: var(--seo-label-col) minmax(0, 1fr);
     column-gap: 18px;
@@ -29,9 +29,9 @@
 }
 
 .label {
-    font-size: 12.5px;
+    font-size: 13px;
     font-weight: 600;
-    color: var(--editor-text-muted);
+    color: var(--editor-text);
 }
 
 /* Boolean rows: hint left, switch pinned right. */
@@ -39,13 +39,14 @@
     display: flex;
     align-items: center;
     justify-content: space-between;
-    gap: 12px;
+    gap: 16px;
 }
 
 .hint {
-    font-size: 11px;
-    line-height: 1.4;
-    color: var(--editor-text-muted);
+    font-size: 12px;
+    font-weight: 500;
+    line-height: 1.5;
+    color: var(--editor-text-secondary);
 }
 
 @media (max-width: 700px) {
diff --git a/src/admin/pages/seo/components/SeoFormRow.tsx b/src/admin/pages/seo/components/SeoFormRow.tsx
index 92a13775e..6d9338d3f 100644
--- a/src/admin/pages/seo/components/SeoFormRow.tsx
+++ b/src/admin/pages/seo/components/SeoFormRow.tsx
@@ -71,7 +71,6 @@ export function SeoSwitchRow({
           disabled={disabled}
           onCheckedChange={onCheckedChange}
           aria-label={label}
-          switchSize="sm"
           data-testid={testId}
         />
       </div>
diff --git a/src/admin/pages/seo/components/SeoPreviewEditor.module.css b/src/admin/pages/seo/components/SeoPreviewEditor.module.css
index bded0e902..3475de704 100644
--- a/src/admin/pages/seo/components/SeoPreviewEditor.module.css
+++ b/src/admin/pages/seo/components/SeoPreviewEditor.module.css
@@ -16,7 +16,7 @@
 .form {
     display: flex;
     flex-direction: column;
-    gap: 16px;
+    gap: 18px;
     background: var(--editor-surface-2);
     border-radius: 16px;
     padding: 20px;
@@ -138,9 +138,10 @@
 
 .fieldHint {
     margin: 0;
-    font-size: 11px;
-    color: var(--editor-text-muted);
-    line-height: 1.4;
+    font-size: 12px;
+    font-weight: 500;
+    color: var(--editor-text-secondary);
+    line-height: 1.5;
 }
 
 .customizeRow {
diff --git a/src/admin/pages/seo/tabs/SettingsTabs.module.css b/src/admin/pages/seo/tabs/SettingsTabs.module.css
index acf1b9a9a..0182fe915 100644
--- a/src/admin/pages/seo/tabs/SettingsTabs.module.css
+++ b/src/admin/pages/seo/tabs/SettingsTabs.module.css
@@ -36,21 +36,21 @@
     min-width: 0;
 }
 
-/* Same card shell as the Meta editor's form. */
+/* Same card shell as the Meta editor's form, with roomier spacing. */
 .card {
     display: flex;
     flex-direction: column;
-    gap: 16px;
+    gap: 22px;
     background: var(--editor-surface-2);
     border-radius: 16px;
-    padding: 20px;
+    padding: 24px;
     min-width: 0;
 }
 
 .cardHeader {
     display: flex;
     flex-direction: column;
-    gap: 2px;
+    gap: 4px;
 }
 
 .heading {
@@ -62,8 +62,9 @@
 
 .subheading {
     margin: 0;
-    font-size: 12px;
-    color: var(--editor-text-muted);
+    font-size: 13px;
+    font-weight: 500;
+    color: var(--editor-text-secondary);
 }
 
 .error {
diff --git a/src/ui/components/Switch/Switch.module.css b/src/ui/components/Switch/Switch.module.css
index 1f7eab4b0..b32861acb 100644
--- a/src/ui/components/Switch/Switch.module.css
+++ b/src/ui/components/Switch/Switch.module.css
@@ -1,4 +1,6 @@
-/* Extracted from ToggleControl and Settings PreferencesSection switch styles. */
+/* Extracted from ToggleControl and Settings PreferencesSection switch styles.
+ * High-contrast achromatic states: on = white track + dark thumb, off =
+ * raised gray track + light thumb — readable on every editor surface. */
 
 .switch {
     display: inline-flex;
@@ -11,13 +13,9 @@
     cursor: pointer;
 }
 
-.switch[data-hit-area="true"] {
-    min-width: 44px;
-    min-height: 44px;
-}
-
 .switch:disabled {
     cursor: not-allowed;
+    opacity: 0.55;
 }
 
 .track {
@@ -32,29 +30,13 @@
 }
 
 .trackOn {
-    background: var(--editor-surface-3);
-    border-color: var(--editor-surface-3);
-}
-
-.trackOff {
-    background: transparent;
-}
-
-.switch[data-hit-area="true"] .track {
-    width: 32px;
-    height: 16px;
-    padding: 2px;
-    box-sizing: content-box;
-    border: 0;
-    border-radius: 10px;
-}
-
-.switch[data-hit-area="true"] .trackOn {
     background: var(--editor-accent);
+    border-color: var(--editor-accent);
 }
 
-.switch[data-hit-area="true"] .trackOff {
-    background: var(--editor-border-med);
+.trackOff {
+    background: var(--editor-surface-4);
+    border-color: var(--editor-surface-4);
 }
 
 .thumb {
@@ -68,7 +50,7 @@
 
 .thumbOn {
     left: 18px;
-    background: var(--editor-text);
+    background: var(--editor-surface);
 }
 
 .thumbOff {
@@ -94,7 +76,3 @@
 .switch[data-size="sm"] .thumbOff {
     left: 3px;
 }
-
-.switch[data-hit-area="true"] .thumbOff {
-    left: 2px;
-}
diff --git a/src/ui/components/Switch/Switch.tsx b/src/ui/components/Switch/Switch.tsx
index 7e4b9bcea..5abaf5e8e 100644
--- a/src/ui/components/Switch/Switch.tsx
+++ b/src/ui/components/Switch/Switch.tsx
@@ -6,7 +6,6 @@ interface SwitchProps
   extends Omit<ButtonHTMLAttributes<HTMLButtonElement>, 'role' | 'onChange'> {
   checked: boolean
   onCheckedChange?: (checked: boolean) => void
-  hitArea?: boolean
   switchSize?: 'sm' | 'md'
   /** React 19: ref is a regular prop on function components. */
   ref?: Ref<HTMLButtonElement>
@@ -15,7 +14,6 @@ interface SwitchProps
 export function Switch({
   checked,
   onCheckedChange,
-  hitArea = false,
   switchSize = 'md',
   className,
   disabled,
@@ -32,7 +30,6 @@ export function Switch({
       role="switch"
       aria-checked={checked}
       disabled={disabled}
-      data-hit-area={hitArea ? 'true' : undefined}
       data-size={switchSize}
       className={cn(styles.switch, className)}
       onClick={(event) => {

From 34e3be7387fc62ca3fc3c984a062259ef5ed59ab Mon Sep 17 00:00:00 2001
From: DavidBabinec <hello@davidbabinec.com>
Date: Fri, 12 Jun 2026 17:11:18 +0200
Subject: [PATCH 16/26] refactor(seo): move the site score into the index
 sidebar, drop the tile band
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

The full-width scoreboard with coverage tiles compressed the editor and
duplicated what the index already shows. The liquid-progress score ring
plus its explainer now sits at the top of the right sidebar
(SeoScoreSummary), directly over the target search; the editor starts at
the top of the page. The tiles and their Review-issues action are gone —
the index's own issues line covers the jump — so the kind filter moves
back into SeoTargetIndex as local state.

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
---
 docs/features/seo.md                          |  12 +-
 src/__tests__/admin/seoWorkspace.test.tsx     |   6 +-
 .../seo/components/SeoScoreSummary.module.css |  40 ++++++
 .../pages/seo/components/SeoScoreSummary.tsx  |  36 +++++
 .../seo/components/SeoScoreboard.module.css   | 125 ------------------
 .../pages/seo/components/SeoScoreboard.tsx    | 116 ----------------
 .../pages/seo/components/SeoTargetIndex.tsx   |  16 +--
 src/admin/pages/seo/tabs/MetaTab.module.css   |   9 +-
 src/admin/pages/seo/tabs/MetaTab.tsx          |  79 +++++------
 9 files changed, 130 insertions(+), 309 deletions(-)
 create mode 100644 src/admin/pages/seo/components/SeoScoreSummary.module.css
 create mode 100644 src/admin/pages/seo/components/SeoScoreSummary.tsx
 delete mode 100644 src/admin/pages/seo/components/SeoScoreboard.module.css
 delete mode 100644 src/admin/pages/seo/components/SeoScoreboard.tsx

diff --git a/docs/features/seo.md b/docs/features/seo.md
index 2217c8d76..0333dc22b 100644
--- a/docs/features/seo.md
+++ b/docs/features/seo.md
@@ -109,12 +109,12 @@ button, Save draft + Open live URL menu). Posts publish through the
 incremental row endpoint; everything else runs the step-up-gated full site
 publish — the same machinery as the Site toolbar, not a parallel path.
 
-- **Meta tab** — top: scoreboard — site-wide SEO score in a
-  `LiquidProgressRing` (tier-toned liquid) plus coverage tiles (search
-  snippets / social cards / indexable / needs-work with a jump to the issues
-  filter), computed from one shared `indexSeoTargets` pass. Right: target
-  index (search, All/Pages/Posts/Templates/Issues filters, tiered score
-  pills per row, ↑/↓/Enter + `/` keyboard nav, pinned Site defaults row).
+- **Meta tab** — right sidebar: site-wide SEO score in a
+  `LiquidProgressRing` (tier-toned liquid, computed from one shared
+  `indexSeoTargets` pass) over the target index (search,
+  All/Pages/Posts/Templates/Issues filters, clickable issues line, tiered
+  score pills per row, ↑/↓/Enter + `/` keyboard nav, pinned Site defaults
+  row).
   Left: sticky preview editor with Search / Open Graph / X / Schema platform
   views, a live score chip, and a clickable improvements list (each row
   focuses the field it describes). Controlled `Input`/`Textarea` primitives
diff --git a/src/__tests__/admin/seoWorkspace.test.tsx b/src/__tests__/admin/seoWorkspace.test.tsx
index 2f75ceac4..117e21843 100644
--- a/src/__tests__/admin/seoWorkspace.test.tsx
+++ b/src/__tests__/admin/seoWorkspace.test.tsx
@@ -309,7 +309,7 @@ describe('SEO Meta tab', () => {
     expect(publish).toBeDefined()
   })
 
-  it('renders the scoreboard and jumps the index to the issues filter', async () => {
+  it('renders the sidebar score summary and jumps the index to the issues filter', async () => {
     mockSeoFetch()
     renderWithSession(<MetaHarness />)
 
@@ -317,9 +317,9 @@ describe('SEO Meta tab', () => {
     await screen.findByLabelText(/Site SEO score: \d+ out of 100/)
     expect(screen.getByTestId('seo-score-chip')).toBeDefined()
 
-    // Every seeded target has at least one open check, so the review action
+    // Every seeded target has at least one open check, so the issues line
     // is present; clicking it narrows the index to issue targets only.
-    fireEvent.click(screen.getByTestId('seo-scoreboard-review-issues'))
+    fireEvent.click(screen.getByTestId('seo-issues-line'))
     expect(screen.queryByTestId('seo-issues-line')).toBeNull()
     expect(screen.getByTestId('seo-target-page_home')).toBeDefined()
   })
diff --git a/src/admin/pages/seo/components/SeoScoreSummary.module.css b/src/admin/pages/seo/components/SeoScoreSummary.module.css
new file mode 100644
index 000000000..38636f525
--- /dev/null
+++ b/src/admin/pages/seo/components/SeoScoreSummary.module.css
@@ -0,0 +1,40 @@
+.summary {
+    display: flex;
+    align-items: center;
+    gap: 16px;
+    min-width: 0;
+}
+
+.value {
+    font-family: var(--font-mono);
+    font-size: 34px;
+    font-weight: 600;
+    letter-spacing: -0.04em;
+    line-height: 1;
+    color: var(--editor-text-bright);
+    text-shadow:
+        0 1px 2px var(--editor-overlay-black-45),
+        0 0 8px var(--editor-overlay-black-25);
+}
+
+.text {
+    display: flex;
+    flex-direction: column;
+    gap: 4px;
+    min-width: 0;
+}
+
+.title {
+    margin: 0;
+    font-size: 14px;
+    font-weight: 700;
+    color: var(--editor-text-bright);
+}
+
+.sub {
+    margin: 0;
+    font-size: 12px;
+    font-weight: 500;
+    line-height: 1.5;
+    color: var(--editor-text-secondary);
+}
diff --git a/src/admin/pages/seo/components/SeoScoreSummary.tsx b/src/admin/pages/seo/components/SeoScoreSummary.tsx
new file mode 100644
index 000000000..9c1f9d0a2
--- /dev/null
+++ b/src/admin/pages/seo/components/SeoScoreSummary.tsx
@@ -0,0 +1,36 @@
+/**
+ * SeoScoreSummary — the site-wide SEO score at the top of the Meta tab's
+ * right sidebar: liquid-progress ring (tier-toned) beside a short
+ * explanation of what the score aggregates.
+ */
+import { LiquidProgressRing } from '@ui/components/LiquidProgressRing'
+import { aggregateSeoScore, seoScoreTier } from '@core/seo'
+import type { IndexedSeoTarget } from '../lib/indexTargets'
+import styles from './SeoScoreSummary.module.css'
+
+const TIER_TONE = { good: 'mint', fair: 'amber', poor: 'danger' } as const
+
+export function SeoScoreSummary({ indexed }: { indexed: IndexedSeoTarget[] }) {
+  const total = indexed.length
+  const score = aggregateSeoScore(indexed.map(({ report }) => report))
+
+  return (
+    <section className={styles.summary} aria-label="Site SEO score">
+      <LiquidProgressRing
+        value={score}
+        total={100}
+        size={104}
+        tone={TIER_TONE[seoScoreTier(score)]}
+        label={<span className={styles.value}>{score}</span>}
+        ariaLabel={`Site SEO score: ${score} out of 100`}
+      />
+      <div className={styles.text}>
+        <h3 className={styles.title}>Site SEO score</h3>
+        <p className={styles.sub}>
+          Average across {total} {total === 1 ? 'target' : 'targets'} — weighted checks on
+          titles, descriptions, social cards, and indexability.
+        </p>
+      </div>
+    </section>
+  )
+}
diff --git a/src/admin/pages/seo/components/SeoScoreboard.module.css b/src/admin/pages/seo/components/SeoScoreboard.module.css
deleted file mode 100644
index 1c61ddc7e..000000000
--- a/src/admin/pages/seo/components/SeoScoreboard.module.css
+++ /dev/null
@@ -1,125 +0,0 @@
-/* Borderless card pattern: surface-2 cells over the darker surface parent
- * with a 1px grid gap, 16px outer radius. */
-.scoreboard {
-    display: grid;
-    grid-template-columns: minmax(280px, 1.6fr) repeat(4, minmax(0, 1fr));
-    gap: 1px;
-    background: var(--editor-surface);
-    border-radius: 16px;
-    overflow: hidden;
-}
-
-.cell {
-    background: var(--editor-surface-2);
-    padding: 16px 18px;
-    min-width: 0;
-}
-
-.scoreCell {
-    display: flex;
-    align-items: center;
-    gap: 18px;
-}
-
-.scoreValue {
-    font-family: var(--font-mono);
-    font-size: 30px;
-    font-weight: 600;
-    letter-spacing: -0.04em;
-    line-height: 1;
-    color: var(--editor-text-bright);
-    text-shadow:
-        0 1px 2px var(--editor-overlay-black-45),
-        0 0 8px var(--editor-overlay-black-25);
-}
-
-.scoreText {
-    display: flex;
-    flex-direction: column;
-    gap: 3px;
-    min-width: 0;
-}
-
-.scoreTitle {
-    margin: 0;
-    font-size: 13px;
-    font-weight: 700;
-    color: var(--editor-text-bright);
-}
-
-.scoreHeadline {
-    margin: 0;
-    font-size: 12px;
-    color: var(--editor-text);
-}
-
-.scoreSub {
-    margin: 0;
-    font-size: 11px;
-    line-height: 1.45;
-    color: var(--editor-text-muted);
-}
-
-/* ── Coverage tiles ──────────────────────────────────────────────────────── */
-.tile {
-    display: flex;
-    flex-direction: column;
-    justify-content: center;
-    gap: 3px;
-    transition: background 120ms ease;
-}
-
-.tile:hover {
-    background: var(--editor-surface-3);
-}
-
-.tileValue {
-    font-family: var(--font-mono);
-    font-size: 22px;
-    font-weight: 600;
-    letter-spacing: -0.03em;
-    line-height: 1.1;
-    color: var(--editor-text-bright);
-}
-
-.tileValue[data-good] {
-    color: var(--editor-success-green);
-}
-
-.tileValue[data-attention] {
-    color: var(--editor-warning);
-}
-
-.tileTotal {
-    font-size: 13px;
-    font-weight: 500;
-    color: var(--editor-text-subtle);
-}
-
-.tileLabel {
-    font-size: 11.5px;
-    font-weight: 600;
-    color: var(--editor-text);
-}
-
-.tileHint {
-    font-size: 10.5px;
-    line-height: 1.4;
-    color: var(--editor-text-muted);
-}
-
-.tileAction {
-    align-self: flex-start;
-    margin-left: -6px;
-    color: var(--editor-warning-text);
-}
-
-@media (max-width: 1100px) {
-    .scoreboard {
-        grid-template-columns: repeat(2, minmax(0, 1fr));
-    }
-
-    .scoreCell {
-        grid-column: 1 / -1;
-    }
-}
diff --git a/src/admin/pages/seo/components/SeoScoreboard.tsx b/src/admin/pages/seo/components/SeoScoreboard.tsx
deleted file mode 100644
index d19468d1e..000000000
--- a/src/admin/pages/seo/components/SeoScoreboard.tsx
+++ /dev/null
@@ -1,116 +0,0 @@
-/**
- * SeoScoreboard — the Meta tab's control-center band: site-wide SEO score
- * in a liquid-progress ring plus coverage tiles, all derived from the same
- * per-target reports the index renders.
- *
- * Tiles follow the borderless card pattern (surface-2 cells over a darker
- * surface parent with a 1px grid gap). The issues tile carries the one
- * action — jump the index to the issues filter.
- */
-import { Button } from '@ui/components/Button'
-import { LiquidProgressRing } from '@ui/components/LiquidProgressRing'
-import { aggregateSeoScore, seoScoreTier, type SeoCheckId } from '@core/seo'
-import { cn } from '@ui/cn'
-import type { IndexedSeoTarget } from '../lib/indexTargets'
-import styles from './SeoScoreboard.module.css'
-
-interface SeoScoreboardProps {
-  indexed: IndexedSeoTarget[]
-  onReviewIssues: () => void
-}
-
-const TIER_TONE = { good: 'mint', fair: 'amber', poor: 'danger' } as const
-
-const TIER_HEADLINE = {
-  good: 'Looking sharp — keep it green.',
-  fair: 'Solid base — a few targets need attention.',
-  poor: 'Search engines are flying blind — start with titles and descriptions.',
-} as const
-
-function passCount(indexed: IndexedSeoTarget[], ids: SeoCheckId[]): number {
-  return indexed.filter(({ report }) =>
-    ids.every((id) => {
-      const check = report.checks.find((c) => c.id === id)
-      // Omitted checks (alt with no image) don't count as covered.
-      return check !== undefined && check.status === 'pass'
-    }),
-  ).length
-}
-
-export function SeoScoreboard({ indexed, onReviewIssues }: SeoScoreboardProps) {
-  const total = indexed.length
-  const score = aggregateSeoScore(indexed.map(({ report }) => report))
-  const tier = seoScoreTier(score)
-
-  const searchReady = passCount(indexed, ['title', 'description'])
-  const socialReady = passCount(indexed, ['socialImage', 'imageAlt'])
-  const indexable = passCount(indexed, ['indexable'])
-  const issues = indexed.filter(({ report }) => report.issueCount > 0).length
-
-  return (
-    <section className={styles.scoreboard} aria-label="Site SEO score">
-      <div className={cn(styles.cell, styles.scoreCell)}>
-        <LiquidProgressRing
-          value={score}
-          total={100}
-          size={88}
-          tone={TIER_TONE[tier]}
-          label={<span className={styles.scoreValue}>{score}</span>}
-          ariaLabel={`Site SEO score: ${score} out of 100`}
-        />
-        <div className={styles.scoreText}>
-          <h3 className={styles.scoreTitle}>Site SEO score</h3>
-          <p className={styles.scoreHeadline}>{TIER_HEADLINE[tier]}</p>
-          <p className={styles.scoreSub}>
-            Average across {total} {total === 1 ? 'target' : 'targets'} — weighted checks on
-            titles, descriptions, social cards, and indexability.
-          </p>
-        </div>
-      </div>
-
-      <div className={cn(styles.cell, styles.tile)}>
-        <span className={styles.tileValue} data-good={searchReady === total || undefined}>
-          {searchReady}<span className={styles.tileTotal}>/{total}</span>
-        </span>
-        <span className={styles.tileLabel}>Search snippets</span>
-        <span className={styles.tileHint}>Title and description in the ideal band</span>
-      </div>
-
-      <div className={cn(styles.cell, styles.tile)}>
-        <span className={styles.tileValue} data-good={socialReady === total || undefined}>
-          {socialReady}<span className={styles.tileTotal}>/{total}</span>
-        </span>
-        <span className={styles.tileLabel}>Social cards</span>
-        <span className={styles.tileHint}>Image with alt text for link shares</span>
-      </div>
-
-      <div className={cn(styles.cell, styles.tile)}>
-        <span className={styles.tileValue} data-good={indexable === total || undefined}>
-          {indexable}<span className={styles.tileTotal}>/{total}</span>
-        </span>
-        <span className={styles.tileLabel}>Indexable</span>
-        <span className={styles.tileHint}>Visible to search and answer engines</span>
-      </div>
-
-      <div className={cn(styles.cell, styles.tile)}>
-        <span className={styles.tileValue} data-attention={issues > 0 || undefined}>
-          {issues}
-        </span>
-        <span className={styles.tileLabel}>{issues === 1 ? 'Target needs work' : 'Targets need work'}</span>
-        {issues > 0 ? (
-          <Button
-            variant="ghost"
-            size="xs"
-            className={styles.tileAction}
-            onClick={onReviewIssues}
-            data-testid="seo-scoreboard-review-issues"
-          >
-            Review issues
-          </Button>
-        ) : (
-          <span className={styles.tileHint}>Nothing flagged right now</span>
-        )}
-      </div>
-    </section>
-  )
-}
diff --git a/src/admin/pages/seo/components/SeoTargetIndex.tsx b/src/admin/pages/seo/components/SeoTargetIndex.tsx
index 578e27523..3774b09fc 100644
--- a/src/admin/pages/seo/components/SeoTargetIndex.tsx
+++ b/src/admin/pages/seo/components/SeoTargetIndex.tsx
@@ -1,9 +1,8 @@
 /**
  * SeoTargetIndex — the Meta tab's right column: navigation + audit context.
  *
- * Search, kind filters (lifted to MetaTab so the scoreboard can jump to the
- * issues view), a clickable issues line, the pinned Site defaults card
- * (globe icon), then targets grouped under "Pages · N" style section
+ * Search, kind filters, a clickable issues line, the pinned Site defaults
+ * card (globe icon), then targets grouped under "Pages · N" style section
  * headers. Rows are bare <button> list rows (§8.8 in
  * `button-primitive-usage.test.ts`) — two lines (title + route/descriptor)
  * with a tiered score pill on the right; the Button primitive's fixed
@@ -22,7 +21,7 @@ import type { SeoTarget } from '../lib/seoApi'
 import type { IndexedSeoTarget } from '../lib/indexTargets'
 import styles from './SeoTargetIndex.module.css'
 
-export type SeoTargetFilter = 'all' | 'pages' | 'posts' | 'templates' | 'issues'
+type SeoTargetFilter = 'all' | 'pages' | 'posts' | 'templates' | 'issues'
 
 const FILTER_OPTIONS: { value: SeoTargetFilter; label: string }[] = [
   { value: 'all', label: 'All' },
@@ -39,8 +38,6 @@ interface TargetGroup {
 
 interface SeoTargetIndexProps {
   indexed: IndexedSeoTarget[]
-  filter: SeoTargetFilter
-  onFilterChange: (filter: SeoTargetFilter) => void
   selectedId: string
   siteDefaultsId: string
   onSelect: (id: string) => void
@@ -48,13 +45,12 @@ interface SeoTargetIndexProps {
 
 export function SeoTargetIndex({
   indexed,
-  filter,
-  onFilterChange,
   selectedId,
   siteDefaultsId,
   onSelect,
 }: SeoTargetIndexProps) {
   const [query, setQuery] = useState('')
+  const [filter, setFilter] = useState<SeoTargetFilter>('all')
   const searchRef = useRef<HTMLInputElement>(null)
 
   const issueCount = indexed.filter((item) => item.report.issueCount > 0).length
@@ -112,7 +108,7 @@ export function SeoTargetIndex({
       <SegmentedControl
         value={filter}
         options={FILTER_OPTIONS}
-        onChange={onFilterChange}
+        onChange={setFilter}
         size="xs"
         fullWidth
         aria-label="Filter targets"
@@ -125,7 +121,7 @@ export function SeoTargetIndex({
           variant="ghost"
           size="xs"
           className={styles.issuesLine}
-          onClick={() => onFilterChange('issues')}
+          onClick={() => setFilter('issues')}
           data-testid="seo-issues-line"
         >
           <span className={styles.issuesDot} aria-hidden="true" />
diff --git a/src/admin/pages/seo/tabs/MetaTab.module.css b/src/admin/pages/seo/tabs/MetaTab.module.css
index b6f291fb1..f201c976a 100644
--- a/src/admin/pages/seo/tabs/MetaTab.module.css
+++ b/src/admin/pages/seo/tabs/MetaTab.module.css
@@ -1,9 +1,3 @@
-.layout {
-    display: flex;
-    flex-direction: column;
-    gap: 24px;
-}
-
 .columns {
     display: grid;
     grid-template-columns: minmax(0, 1fr) 300px;
@@ -19,6 +13,9 @@
     position: sticky;
     top: 0;
     align-self: start;
+    display: flex;
+    flex-direction: column;
+    gap: 18px;
     min-width: 0;
 }
 
diff --git a/src/admin/pages/seo/tabs/MetaTab.tsx b/src/admin/pages/seo/tabs/MetaTab.tsx
index 790fd3e52..e80cd28b5 100644
--- a/src/admin/pages/seo/tabs/MetaTab.tsx
+++ b/src/admin/pages/seo/tabs/MetaTab.tsx
@@ -1,16 +1,15 @@
 /**
  * MetaTab — the SEO workspace's control center.
  *
- * Three persistent regions:
- *   - Top: scoreboard — site-wide SEO score in a liquid-progress ring plus
- *     coverage tiles (search snippets, social cards, indexability, issues),
- *     all computed from the same per-target reports the index shows.
+ * Two persistent columns:
  *   - Left: the active editor. Platform previews over editable snippet
  *     fields with inherited-value placeholders, ideal-band length meters,
  *     a live per-target score, and an actionable improvements list. The
  *     pinned "Site defaults" row opens the site-level editor instead.
- *   - Right: target index — search, kind filters, dense rows with score
- *     pills, full keyboard navigation.
+ *   - Right: the site-wide SEO score (liquid-progress ring) over the target
+ *     index — search, kind filters, dense rows with score pills, full
+ *     keyboard navigation. Score and index rows derive from the same
+ *     per-target reports.
  *
  * Save/publish lives in the workspace toolbar: the active editor registers
  * itself on the save bridge passed down from SeoPage.
@@ -26,8 +25,8 @@ import type { SeoTarget } from '../lib/seoApi'
 import type { SeoWorkspace } from '../hooks/useSeoWorkspace'
 import type { SeoSaveBridge } from '../hooks/useSeoSaveBridge'
 import { indexSeoTargets } from '../lib/indexTargets'
-import { SeoScoreboard } from '../components/SeoScoreboard'
-import { SeoTargetIndex, type SeoTargetFilter } from '../components/SeoTargetIndex'
+import { SeoScoreSummary } from '../components/SeoScoreSummary'
+import { SeoTargetIndex } from '../components/SeoTargetIndex'
 import { SeoPreviewEditor } from '../components/SeoPreviewEditor'
 import { SiteDefaultsEditor } from '../components/SiteDefaultsEditor'
 import styles from './MetaTab.module.css'
@@ -53,10 +52,9 @@ function defaultSelectionId(targets: SeoTarget[]): string {
 export function MetaTab({ workspace, canManage, bridge }: MetaTabProps) {
   const [selection, setSelection] = useState<string | null>(null)
   const [pendingSelection, setPendingSelection] = useState<string | null>(null)
-  const [filter, setFilter] = useState<SeoTargetFilter>('all')
 
-  // One report per target, shared by the scoreboard and the index so both
-  // agree on scores and what counts as an issue.
+  // One report per target, shared by the score summary and the index so
+  // both agree on scores and what counts as an issue.
   const indexed = indexSeoTargets(workspace.targets, workspace.resolveContext)
 
   const editorDirty = bridge.status?.dirty ?? false
@@ -84,39 +82,34 @@ export function MetaTab({ workspace, canManage, bridge }: MetaTabProps) {
   }
 
   return (
-    <div className={styles.layout}>
-      <SeoScoreboard indexed={indexed} onReviewIssues={() => setFilter('issues')} />
-
-      <div className={styles.columns}>
-        <div className={styles.editorColumn}>
-          {selectedTarget ? (
-            <SeoPreviewEditor
-              key={selectedTarget.id}
-              target={selectedTarget}
-              workspace={workspace}
-              canManage={canManage}
-              bridge={bridge}
-            />
-          ) : (
-            <SiteDefaultsEditor
-              key={SITE_DEFAULTS_ID}
-              workspace={workspace}
-              canManage={canManage}
-              bridge={bridge}
-            />
-          )}
-        </div>
-
-        <div className={styles.indexColumn}>
-          <SeoTargetIndex
-            indexed={indexed}
-            filter={filter}
-            onFilterChange={setFilter}
-            selectedId={selectedId}
-            siteDefaultsId={SITE_DEFAULTS_ID}
-            onSelect={handleSelect}
+    <div className={styles.columns}>
+      <div className={styles.editorColumn}>
+        {selectedTarget ? (
+          <SeoPreviewEditor
+            key={selectedTarget.id}
+            target={selectedTarget}
+            workspace={workspace}
+            canManage={canManage}
+            bridge={bridge}
+          />
+        ) : (
+          <SiteDefaultsEditor
+            key={SITE_DEFAULTS_ID}
+            workspace={workspace}
+            canManage={canManage}
+            bridge={bridge}
           />
-        </div>
+        )}
+      </div>
+
+      <div className={styles.indexColumn}>
+        <SeoScoreSummary indexed={indexed} />
+        <SeoTargetIndex
+          indexed={indexed}
+          selectedId={selectedId}
+          siteDefaultsId={SITE_DEFAULTS_ID}
+          onSelect={handleSelect}
+        />
       </div>
 
       <Dialog

From 4713f7414fe33b5629b3b7573a55e16c5496ac56 Mon Sep 17 00:00:00 2001
From: DavidBabinec <hello@davidbabinec.com>
Date: Fri, 12 Jun 2026 17:17:47 +0200
Subject: [PATCH 17/26] refactor(seo): flip Meta tab into one flat three-column
 grid
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Index sidebar (score + targets) moves to the left, the editor form sits
in the middle, and the platform-preview rail goes right — and the
nested-grid structure goes away: SeoPreviewEditor/SiteDefaultsEditor
render form + rail as fragment siblings, so MetaTab owns a single
display: grid with three tracks instead of a two-column grid wrapping
another two-column workbench.

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
---
 docs/features/seo.md                          | 11 ++--
 .../components/SeoPreviewEditor.module.css    | 17 +-----
 .../pages/seo/components/SeoPreviewEditor.tsx | 28 +++++-----
 .../seo/components/SiteDefaultsEditor.tsx     | 37 +++++++------
 src/admin/pages/seo/tabs/MetaTab.module.css   | 14 +++--
 src/admin/pages/seo/tabs/MetaTab.tsx          | 53 ++++++++++---------
 6 files changed, 75 insertions(+), 85 deletions(-)

diff --git a/docs/features/seo.md b/docs/features/seo.md
index 0333dc22b..e9b951b4c 100644
--- a/docs/features/seo.md
+++ b/docs/features/seo.md
@@ -109,15 +109,16 @@ button, Save draft + Open live URL menu). Posts publish through the
 incremental row endpoint; everything else runs the step-up-gated full site
 publish — the same machinery as the Site toolbar, not a parallel path.
 
-- **Meta tab** — right sidebar: site-wide SEO score in a
+- **Meta tab** — one flat three-column grid. Left: site-wide SEO score in a
   `LiquidProgressRing` (tier-toned liquid, computed from one shared
   `indexSeoTargets` pass) over the target index (search,
   All/Pages/Posts/Templates/Issues filters, clickable issues line, tiered
   score pills per row, ↑/↓/Enter + `/` keyboard nav, pinned Site defaults
-  row).
-  Left: sticky preview editor with Search / Open Graph / X / Schema platform
-  views, a live score chip, and a clickable improvements list (each row
-  focuses the field it describes). Controlled `Input`/`Textarea` primitives
+  row). Middle: the editor form with a live score chip and a clickable
+  improvements list (each row focuses the field it describes). Right: the
+  sticky Search / Open Graph / X / Schema preview rail — the editors render
+  form + rail as fragment siblings so the grid stays flat.
+  Controlled `Input`/`Textarea` primitives
   (no contentEditable); empty fields show their RESOLVED fallback as
   placeholder; title/description carry ideal-band pixel meters (green only
   inside the band; inherited values render muted with an Inherited/Missing
diff --git a/src/admin/pages/seo/components/SeoPreviewEditor.module.css b/src/admin/pages/seo/components/SeoPreviewEditor.module.css
index 3475de704..d0317b336 100644
--- a/src/admin/pages/seo/components/SeoPreviewEditor.module.css
+++ b/src/admin/pages/seo/components/SeoPreviewEditor.module.css
@@ -1,18 +1,5 @@
-/* Workbench: sticky preview rail (left) + sectioned form (right). */
-.workbench {
-    display: grid;
-    grid-template-columns: minmax(320px, 400px) minmax(0, 1fr);
-    gap: 24px;
-    align-items: start;
-    min-width: 0;
-}
-
-@media (max-width: 1100px) {
-    .workbench {
-        grid-template-columns: 1fr;
-    }
-}
-
+/* The editor's grid cells (form + rail) live in MetaTab's three-column
+ * grid — there is no wrapper element. */
 .form {
     display: flex;
     flex-direction: column;
diff --git a/src/admin/pages/seo/components/SeoPreviewEditor.tsx b/src/admin/pages/seo/components/SeoPreviewEditor.tsx
index 68c0e6fad..753f872c2 100644
--- a/src/admin/pages/seo/components/SeoPreviewEditor.tsx
+++ b/src/admin/pages/seo/components/SeoPreviewEditor.tsx
@@ -1,9 +1,11 @@
 /**
  * SeoPreviewEditor — the Meta tab's workbench for one page / template / post
- * target: a sticky rail of live 1:1 platform previews on the left (Google,
- * Open Graph, X, collapsible JSON-LD) and the sectioned metadata form on the
- * right. One draft, one resolver — every keystroke re-resolves and the rail
- * re-renders, so what's previewed is exactly what the publisher will emit.
+ * target: the sectioned metadata form plus a sticky rail of live 1:1
+ * platform previews (Google, Open Graph, X, collapsible JSON-LD). Rendered
+ * as a fragment — form and rail are siblings in MetaTab's three-column
+ * grid (index | form | previews). One draft, one resolver — every
+ * keystroke re-resolves and the rail re-renders, so what's previewed is
+ * exactly what the publisher will emit.
  *
  * The header carries a live score chip and an actionable improvements list
  * (both recomputed from the draft on every keystroke — fixing a check turns
@@ -201,14 +203,7 @@ export function SeoPreviewEditor({ target, workspace, canManage, bridge }: SeoPr
   const openIssues = report.checks.filter((check) => check.status !== 'pass')
 
   return (
-    <div className={styles.workbench}>
-      <SeoPreviewRail
-        resolved={resolved}
-        workspace={workspace}
-        routePath={routePath}
-        schemaTarget={target}
-      />
-
+    <>
       <section className={styles.form} aria-label={`SEO for ${target.title}`}>
         <header className={styles.header}>
           <div className={styles.headerText}>
@@ -342,7 +337,14 @@ export function SeoPreviewEditor({ target, workspace, canManage, bridge }: SeoPr
           </>
         )}
       </section>
-    </div>
+
+      <SeoPreviewRail
+        resolved={resolved}
+        workspace={workspace}
+        routePath={routePath}
+        schemaTarget={target}
+      />
+    </>
   )
 }
 
diff --git a/src/admin/pages/seo/components/SiteDefaultsEditor.tsx b/src/admin/pages/seo/components/SiteDefaultsEditor.tsx
index c34981a5b..5291dd1bb 100644
--- a/src/admin/pages/seo/components/SiteDefaultsEditor.tsx
+++ b/src/admin/pages/seo/components/SiteDefaultsEditor.tsx
@@ -1,12 +1,13 @@
 /**
  * SiteDefaultsEditor — the pinned "Site defaults" target's workbench.
  *
- * Left rail: live previews of the HOMEPAGE resolved with the draft defaults
- * applied — the user sees exactly what a typical page inherits while they
- * type the pattern. Right: the sectioned defaults form (`site.settings.seo`:
- * title pattern, description, default social image, X handle/card, and the
- * Organization fields feeding site-wide JSON-LD). Robots/sitemap settings
- * live on the same object but are edited in their own tabs.
+ * Rendered as a fragment into MetaTab's three-column grid: the sectioned
+ * defaults form (`site.settings.seo`: title pattern, description, default
+ * social image, X handle/card, and the Organization fields feeding
+ * site-wide JSON-LD), then a rail of live previews of the HOMEPAGE
+ * resolved with the draft defaults applied — the user sees exactly what a
+ * typical page inherits while they type the pattern. Robots/sitemap
+ * settings live on the same object but are edited in their own tabs.
  */
 import { useId, useState } from 'react'
 import { Input, Textarea } from '@ui/components/Input'
@@ -164,18 +165,7 @@ export function SiteDefaultsEditor({ workspace, canManage, bridge }: SiteDefault
   )
 
   return (
-    <div className={styles.workbench}>
-      {sampleResolved && sampleTarget ? (
-        <SeoPreviewRail
-          resolved={sampleResolved}
-          workspace={workspace}
-          routePath={sampleTarget.route ?? '/'}
-          schemaTarget={sampleTarget}
-        />
-      ) : (
-        <div />
-      )}
-
+    <>
       <section className={styles.form} aria-label="Site SEO defaults">
         <header className={styles.header}>
           <div className={styles.headerText}>
@@ -301,6 +291,15 @@ export function SiteDefaultsEditor({ workspace, canManage, bridge }: SiteDefault
           onChange={(next) => setOrgField('logoUrl', next)}
         />
       </section>
-    </div>
+
+      {sampleResolved && sampleTarget && (
+        <SeoPreviewRail
+          resolved={sampleResolved}
+          workspace={workspace}
+          routePath={sampleTarget.route ?? '/'}
+          schemaTarget={sampleTarget}
+        />
+      )}
+    </>
   )
 }
diff --git a/src/admin/pages/seo/tabs/MetaTab.module.css b/src/admin/pages/seo/tabs/MetaTab.module.css
index f201c976a..6f370ec24 100644
--- a/src/admin/pages/seo/tabs/MetaTab.module.css
+++ b/src/admin/pages/seo/tabs/MetaTab.module.css
@@ -1,14 +1,13 @@
+/* One flat three-column grid: index sidebar | editor form | preview rail.
+ * The editors render form + rail as fragment siblings, so auto-placement
+ * fills the middle and right tracks. */
 .columns {
     display: grid;
-    grid-template-columns: minmax(0, 1fr) 300px;
-    gap: 28px;
+    grid-template-columns: 300px minmax(0, 1fr) minmax(300px, 400px);
+    gap: 24px;
     align-items: start;
 }
 
-.editorColumn {
-    min-width: 0;
-}
-
 .indexColumn {
     position: sticky;
     top: 0;
@@ -19,13 +18,12 @@
     min-width: 0;
 }
 
-@media (max-width: 960px) {
+@media (max-width: 1100px) {
     .columns {
         grid-template-columns: 1fr;
     }
 
     .indexColumn {
         position: static;
-        order: -1;
     }
 }
diff --git a/src/admin/pages/seo/tabs/MetaTab.tsx b/src/admin/pages/seo/tabs/MetaTab.tsx
index e80cd28b5..c92d82515 100644
--- a/src/admin/pages/seo/tabs/MetaTab.tsx
+++ b/src/admin/pages/seo/tabs/MetaTab.tsx
@@ -1,15 +1,18 @@
 /**
  * MetaTab — the SEO workspace's control center.
  *
- * Two persistent columns:
- *   - Left: the active editor. Platform previews over editable snippet
- *     fields with inherited-value placeholders, ideal-band length meters,
- *     a live per-target score, and an actionable improvements list. The
- *     pinned "Site defaults" row opens the site-level editor instead.
- *   - Right: the site-wide SEO score (liquid-progress ring) over the target
+ * One flat three-column grid:
+ *   - Left: the site-wide SEO score (liquid-progress ring) over the target
  *     index — search, kind filters, dense rows with score pills, full
  *     keyboard navigation. Score and index rows derive from the same
  *     per-target reports.
+ *   - Middle: the active editor's form — snippet fields with
+ *     inherited-value placeholders, ideal-band length meters, a live
+ *     per-target score, and an actionable improvements list. The pinned
+ *     "Site defaults" row opens the site-level editor instead.
+ *   - Right: the editor's sticky platform-preview rail (Google / Open
+ *     Graph / X / JSON-LD). The editors render form + rail as fragment
+ *     siblings so the grid stays flat.
  *
  * Save/publish lives in the workspace toolbar: the active editor registers
  * itself on the save bridge passed down from SeoPage.
@@ -83,25 +86,6 @@ export function MetaTab({ workspace, canManage, bridge }: MetaTabProps) {
 
   return (
     <div className={styles.columns}>
-      <div className={styles.editorColumn}>
-        {selectedTarget ? (
-          <SeoPreviewEditor
-            key={selectedTarget.id}
-            target={selectedTarget}
-            workspace={workspace}
-            canManage={canManage}
-            bridge={bridge}
-          />
-        ) : (
-          <SiteDefaultsEditor
-            key={SITE_DEFAULTS_ID}
-            workspace={workspace}
-            canManage={canManage}
-            bridge={bridge}
-          />
-        )}
-      </div>
-
       <div className={styles.indexColumn}>
         <SeoScoreSummary indexed={indexed} />
         <SeoTargetIndex
@@ -112,6 +96,25 @@ export function MetaTab({ workspace, canManage, bridge }: MetaTabProps) {
         />
       </div>
 
+      {/* Fragment children: the form lands in the middle column, the
+          preview rail in the right one. */}
+      {selectedTarget ? (
+        <SeoPreviewEditor
+          key={selectedTarget.id}
+          target={selectedTarget}
+          workspace={workspace}
+          canManage={canManage}
+          bridge={bridge}
+        />
+      ) : (
+        <SiteDefaultsEditor
+          key={SITE_DEFAULTS_ID}
+          workspace={workspace}
+          canManage={canManage}
+          bridge={bridge}
+        />
+      )}
+
       <Dialog
         open={pendingSelection !== null}
         onClose={() => setPendingSelection(null)}

From c7687eaf44a945137178620e0d0e6138ae461194 Mon Sep 17 00:00:00 2001
From: DavidBabinec <hello@davidbabinec.com>
Date: Fri, 12 Jun 2026 17:19:34 +0200
Subject: [PATCH 18/26] style(seo): lift subtle text to muted across the
 workspace

--editor-text-subtle is nearly invisible on the index's surface-2 rows.
Row routes/descriptors, group counts, the Site defaults chevron, and the
length meter's Inherited/Missing tag now use --editor-text-muted.

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
---
 src/admin/pages/seo/components/MetaLengthMeter.module.css | 2 +-
 src/admin/pages/seo/components/SeoTargetIndex.module.css  | 8 ++++----
 2 files changed, 5 insertions(+), 5 deletions(-)

diff --git a/src/admin/pages/seo/components/MetaLengthMeter.module.css b/src/admin/pages/seo/components/MetaLengthMeter.module.css
index 3f336dd5b..6cedd10b5 100644
--- a/src/admin/pages/seo/components/MetaLengthMeter.module.css
+++ b/src/admin/pages/seo/components/MetaLengthMeter.module.css
@@ -98,7 +98,7 @@
     font-weight: 600;
     letter-spacing: 0.07em;
     text-transform: uppercase;
-    color: var(--editor-text-subtle);
+    color: var(--editor-text-muted);
     min-width: 44px;
     text-align: right;
 }
diff --git a/src/admin/pages/seo/components/SeoTargetIndex.module.css b/src/admin/pages/seo/components/SeoTargetIndex.module.css
index 192ff16ef..363748006 100644
--- a/src/admin/pages/seo/components/SeoTargetIndex.module.css
+++ b/src/admin/pages/seo/components/SeoTargetIndex.module.css
@@ -71,7 +71,7 @@
 }
 
 .siteCardChevron {
-    color: var(--editor-text-subtle);
+    color: var(--editor-text-muted);
 }
 
 /* ── Groups ──────────────────────────────────────────────────────────────── */
@@ -96,7 +96,7 @@
 
 .groupCount {
     font-weight: 500;
-    color: var(--editor-text-subtle);
+    color: var(--editor-text-muted);
 }
 
 .groupList {
@@ -152,7 +152,7 @@
     font-size: 10.5px;
     line-height: 15px;
     font-family: var(--font-mono);
-    color: var(--editor-text-subtle);
+    color: var(--editor-text-muted);
     white-space: nowrap;
     overflow: hidden;
     text-overflow: ellipsis;
@@ -163,7 +163,7 @@
 .rowDescriptor {
     font-size: 11px;
     line-height: 15px;
-    color: var(--editor-text-subtle);
+    color: var(--editor-text-muted);
     white-space: nowrap;
     overflow: hidden;
     text-overflow: ellipsis;

From 51dbd2697d1e18e7497fc406fe89a1dec20db265 Mon Sep 17 00:00:00 2001
From: DavidBabinec <hello@davidbabinec.com>
Date: Fri, 12 Jun 2026 17:28:46 +0200
Subject: [PATCH 19/26] fix(seo): exclude layout templates from targets, name
 entry-template tables
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Two template bugs in the target index:

- `everywhere` layout templates appeared as SEO targets labelled "Entry
  template". They have no route and no content of their own — the pages
  they wrap own the metadata — so the targets endpoint now drops them;
  only entry templates (postTypes targets, token-pattern sources for
  their posts) are listed.
- Entry templates rendered a bare "Entry template" descriptor because the
  index read `tableSlug` (post rows only) instead of
  `templateTableSlugs`. The index rows and the editor header now show
  "Entry template · posts".

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
---
 docs/features/seo.md                          |  5 +++-
 server/handlers/cms/seo.ts                    | 23 +++++++++++----
 src/__tests__/server/seoHandler.test.ts       | 28 +++++++++++++++++--
 .../pages/seo/components/SeoPreviewEditor.tsx |  5 +++-
 .../pages/seo/components/SeoTargetIndex.tsx   | 10 +++++--
 5 files changed, 58 insertions(+), 13 deletions(-)

diff --git a/docs/features/seo.md b/docs/features/seo.md
index e9b951b4c..92d480bbd 100644
--- a/docs/features/seo.md
+++ b/docs/features/seo.md
@@ -32,7 +32,10 @@ One engine module owns everything: **`src/core/seo/`** (barrel-gated).
 - **Site defaults**: `site.settings.seo` (replaced the legacy
   `metaTitle`/`metaDescription` settings).
 - **Templates**: an entry template page row's `seo.title`/`seo.description`
-  act as token patterns for every matching post.
+  act as token patterns for every matching post. Only entry templates
+  (postTypes targets) are SEO targets — `everywhere` layout templates have
+  no route or content of their own, so the target index excludes them (the
+  wrapped pages own the metadata).
 
 ### Resolution — two-stage title
 
diff --git a/server/handlers/cms/seo.ts b/server/handlers/cms/seo.ts
index 87bfdca0c..b314d6a45 100644
--- a/server/handlers/cms/seo.ts
+++ b/server/handlers/cms/seo.ts
@@ -62,7 +62,8 @@ interface SeoTargetPayload {
   /**
    * Templates only: the postType table slugs this entry template applies
    * to. Lets the admin preview resolve a post's template title pattern
-   * exactly like the publisher does. Empty for `everywhere` templates.
+   * exactly like the publisher does. (`everywhere` layout templates are
+   * not SEO targets at all — the pages they wrap own the metadata.)
    */
   templateTableSlugs?: string[]
   seo: ReturnType<typeof readSeoCell> | null
@@ -71,7 +72,14 @@ interface SeoTargetPayload {
   publishedAt: string | null
 }
 
-function pageRowToTarget(row: DataRow): SeoTargetPayload {
+/**
+ * Map a pages-table row to a target — or null for `everywhere` layout
+ * templates: they have no route and no content of their own, so per-target
+ * metadata is meaningless (the wrapped pages own their SEO). Only entry
+ * templates (postTypes targets) are SEO targets, as token-pattern sources
+ * for their posts.
+ */
+function pageRowToTarget(row: DataRow): SeoTargetPayload | null {
   const template = row.cells.templateEnabled === true
     ? parsePageTemplate({
         enabled: true,
@@ -82,15 +90,15 @@ function pageRowToTarget(row: DataRow): SeoTargetPayload {
   // Mirrors isTemplatePage(page): parsePageTemplate only returns a config
   // for enabled templates, so a non-null config means "template page".
   const isTemplate = template !== null
+  const entryTarget = template !== null && template.target.kind === 'postTypes' ? template.target : null
+  if (isTemplate && entryTarget === null) return null
   const slug = row.slug.replace(/^\/+/, '')
   return {
     kind: isTemplate ? 'template' : 'page',
     id: row.id,
     title: readTitleCell(row.cells) || row.slug,
     route: isTemplate ? null : slug === 'index' || slug === '' ? '/' : `/${slug}`,
-    ...(isTemplate
-      ? { templateTableSlugs: template.target.kind === 'postTypes' ? template.target.tableSlugs : [] }
-      : {}),
+    ...(entryTarget !== null ? { templateTableSlugs: entryTarget.tableSlugs } : {}),
     seo: readSeoCell(row.cells) ?? null,
     status: row.status,
     updatedAt: row.updatedAt,
@@ -137,7 +145,10 @@ async function handleGetTargets(req: Request, db: DbClient): Promise<Response> {
     publicOrigin: canonicalPublicOrigin(),
     faviconUrl: site?.settings.faviconUrl ?? null,
     siteSeo: site?.settings.seo ?? null,
-    targets: [...pageRows.map(pageRowToTarget), ...postTargets],
+    targets: [
+      ...pageRows.map(pageRowToTarget).filter((target) => target !== null),
+      ...postTargets,
+    ],
   })
 }
 
diff --git a/src/__tests__/server/seoHandler.test.ts b/src/__tests__/server/seoHandler.test.ts
index 65a6f5df7..6950c1133 100644
--- a/src/__tests__/server/seoHandler.test.ts
+++ b/src/__tests__/server/seoHandler.test.ts
@@ -22,6 +22,7 @@ interface SeoTarget {
   title: string
   route: string | null
   tableSlug?: string
+  templateTableSlugs?: string[]
   seo: SeoMetadata | null
   status: string
 }
@@ -71,6 +72,23 @@ describe('GET /admin/api/cms/seo/targets', () => {
     })
     expect(createRes.status).toBe(201)
 
+    // An `everywhere` layout template must NOT appear in the index — it has
+    // no route or content of its own; the pages it wraps own the metadata.
+    const createLayoutRes = await h.cms('/admin/api/cms/data/tables/pages/rows', {
+      method: 'POST',
+      cookie: owner,
+      json: {
+        cells: {
+          title: 'Main layout',
+          slug: 'main-layout',
+          templateEnabled: true,
+          templateTarget: { kind: 'everywhere' },
+          templatePriority: 0,
+        },
+      },
+    })
+    expect(createLayoutRes.status).toBe(201)
+
     const body = await fetchTargets(owner)
     expect(body.siteName.length).toBeGreaterThan(0)
 
@@ -83,8 +101,14 @@ describe('GET /admin/api/cms/seo/targets', () => {
     expect(post).toBeDefined()
     expect(post!.route).toBe('/posts/hello-world')
 
-    const template = body.targets.find((t) => t.kind === 'template')
-    expect(template!.route).toBeNull()
+    // Every listed template is an entry template carrying its table slugs.
+    const templates = body.targets.filter((t) => t.kind === 'template')
+    expect(templates.length).toBeGreaterThan(0)
+    for (const template of templates) {
+      expect(template.route).toBeNull()
+      expect(template.templateTableSlugs!.length).toBeGreaterThan(0)
+    }
+    expect(body.targets.some((t) => t.title === 'Main layout')).toBe(false)
   })
 
   it('requires seo.read', async () => {
diff --git a/src/admin/pages/seo/components/SeoPreviewEditor.tsx b/src/admin/pages/seo/components/SeoPreviewEditor.tsx
index 753f872c2..520c89d95 100644
--- a/src/admin/pages/seo/components/SeoPreviewEditor.tsx
+++ b/src/admin/pages/seo/components/SeoPreviewEditor.tsx
@@ -209,7 +209,10 @@ export function SeoPreviewEditor({ target, workspace, canManage, bridge }: SeoPr
           <div className={styles.headerText}>
             <h2 className={styles.headerTitle}>{target.title}</h2>
             <span className={styles.headerRoute}>
-              {target.route ?? (target.kind === 'template' ? `Entry template${target.tableSlug ? ` · ${target.tableSlug}` : ''}` : '')}
+              {target.route ??
+                (target.kind === 'template'
+                  ? `Entry template · ${(target.templateTableSlugs ?? []).join(', ')}`
+                  : '')}
             </span>
           </div>
           <SeoScoreChip score={report.score} />
diff --git a/src/admin/pages/seo/components/SeoTargetIndex.tsx b/src/admin/pages/seo/components/SeoTargetIndex.tsx
index 3774b09fc..87a170f93 100644
--- a/src/admin/pages/seo/components/SeoTargetIndex.tsx
+++ b/src/admin/pages/seo/components/SeoTargetIndex.tsx
@@ -182,6 +182,12 @@ export function SeoTargetIndex({
   )
 }
 
+/** "Entry template · posts" — names the tables the template's patterns feed. */
+function templateDescriptor(target: SeoTarget): string {
+  const tables = target.templateTableSlugs ?? []
+  return tables.length > 0 ? `Entry template · ${tables.join(', ')}` : 'Entry template'
+}
+
 function TargetRow({
   target,
   report,
@@ -207,9 +213,7 @@ function TargetRow({
         {target.route !== null ? (
           <span className={styles.rowRoute}>{target.route}</span>
         ) : (
-          <span className={styles.rowDescriptor}>
-            Entry template{target.tableSlug ? ` · ${target.tableSlug}` : ''}
-          </span>
+          <span className={styles.rowDescriptor}>{templateDescriptor(target)}</span>
         )}
       </span>
       <ScorePill report={report} />

From 60ea8baadfa4cc339409a197cbdf3091196edaa9 Mon Sep 17 00:00:00 2001
From: DavidBabinec <hello@davidbabinec.com>
Date: Fri, 12 Jun 2026 18:46:00 +0200
Subject: [PATCH 20/26] =?UTF-8?q?feat(nav):=20Tools=20dropdown=20=E2=80=94?=
 =?UTF-8?q?=20chevron,=20hover-open,=20current-section=20style?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

The Tools nav trigger now reads as a dropdown: a chevron-down rides the
label, the menu opens on hover (with a 160ms close-intent timer bridging
the trigger→menu gap, click still toggles), and when the current section
lives inside the menu (SEO, plugin pages) the trigger carries the same
bold current-section text the sibling nav items use.

Also makes the robots-preview test deterministic: SeoCodeViewer mirrors
its value in a data-code attribute, so assertions stop racing the lazy
CM6 chunk (which paints zero measured-visible lines in test DOMs —
the source of the admin+architecture combo flake).

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
---
 src/__tests__/admin/seoWorkspace.test.tsx     | 29 ++++++++++----
 .../pages/seo/components/SeoCodeViewer.tsx    |  5 ++-
 .../pages/site/toolbar/Toolbar.module.css     | 13 +++++++
 .../AdminSectionNavigation.tsx                | 39 ++++++++++++++++++-
 4 files changed, 76 insertions(+), 10 deletions(-)

diff --git a/src/__tests__/admin/seoWorkspace.test.tsx b/src/__tests__/admin/seoWorkspace.test.tsx
index 117e21843..5e6e1e67c 100644
--- a/src/__tests__/admin/seoWorkspace.test.tsx
+++ b/src/__tests__/admin/seoWorkspace.test.tsx
@@ -360,17 +360,16 @@ describe('SEO Robots tab', () => {
     mockSeoFetch()
     renderWithSession(<RobotsHarness />)
 
-    // Newline-agnostic assertions: the preview renders through the lazy
-    // CodeMirror viewer when its chunk is already loaded (full-suite runs)
-    // and through the plain <Code> fallback otherwise — CM6's per-line DOM
-    // drops newlines from textContent.
+    // Assert on the viewer's data-code mirror, not rendered text: the lazy
+    // CM6 viewer paints only measured-visible lines (none in a test DOM),
+    // so textContent depends on whether the chunk resolved yet.
     const preview = await screen.findByTestId('seo-robots-preview')
-    expect(preview.textContent).toContain('User-agent: *')
-    expect(preview.textContent).toContain('Allow: /')
-    expect(preview.textContent).not.toContain('GPTBot')
+    expect(preview.getAttribute('data-code')).toContain('User-agent: *')
+    expect(preview.getAttribute('data-code')).toContain('Allow: /')
+    expect(preview.getAttribute('data-code')).not.toContain('GPTBot')
 
     fireEvent.click(screen.getByTestId('seo-robots-ai-training'))
-    expect(screen.getByTestId('seo-robots-preview').textContent).toContain('User-agent: GPTBot')
+    expect(screen.getByTestId('seo-robots-preview').getAttribute('data-code')).toContain('User-agent: GPTBot')
   })
 })
 
@@ -389,6 +388,20 @@ describe('Tools navigation', () => {
     expect(await screen.findByTestId('tools-nav-seo')).toBeDefined()
   })
 
+  it('opens the Tools dropdown on hover', async () => {
+    mockSeoFetch()
+    render(
+      <MemoryRouter initialEntries={['/admin/dashboard']}>
+        <AdminSessionProvider user={currentUser(['dashboard.read', 'seo.read'])}>
+          <AdminSectionNavigation section="dashboard" />
+        </AdminSessionProvider>
+      </MemoryRouter>,
+    )
+
+    fireEvent.mouseEnter(await screen.findByTestId('tools-nav-trigger'))
+    expect(await screen.findByTestId('tools-nav-seo')).toBeDefined()
+  })
+
   it('hides the Tools dropdown without seo.read or plugin pages', () => {
     mockSeoFetch()
     render(
diff --git a/src/admin/pages/seo/components/SeoCodeViewer.tsx b/src/admin/pages/seo/components/SeoCodeViewer.tsx
index acd395c1c..e0a7bff5d 100644
--- a/src/admin/pages/seo/components/SeoCodeViewer.tsx
+++ b/src/admin/pages/seo/components/SeoCodeViewer.tsx
@@ -23,7 +23,10 @@ interface SeoCodeViewerProps {
 
 export function SeoCodeViewer({ docKey, value, language, 'data-testid': testId }: SeoCodeViewerProps) {
   return (
-    <div className={styles.viewer} data-testid={testId}>
+    /* data-code mirrors the displayed text: CM6 renders only measured-
+       visible lines (none in test DOMs), so assertions read the attribute
+       instead of racing the lazy chunk. */
+    <div className={styles.viewer} data-testid={testId} data-code={value}>
       <Suspense fallback={<Code className={styles.fallback}>{value}</Code>}>
         <CodeMirrorEditor
           docKey={`${docKey}:${value.length}:${hashText(value)}`}
diff --git a/src/admin/pages/site/toolbar/Toolbar.module.css b/src/admin/pages/site/toolbar/Toolbar.module.css
index c6708fab5..8e9ca295a 100644
--- a/src/admin/pages/site/toolbar/Toolbar.module.css
+++ b/src/admin/pages/site/toolbar/Toolbar.module.css
@@ -69,6 +69,19 @@
     color: var(--editor-text);
 }
 
+/* Dropdown nav triggers (Tools) when the current section lives inside the
+   menu — same bold text the activeSection span uses, while the trigger
+   stays clickable/hoverable. */
+.adminLinkCurrent {
+    color: var(--editor-text);
+    font-weight: 700;
+}
+
+.adminLinkChevron {
+    margin-left: -2px;
+    color: var(--editor-text-muted);
+}
+
 .activeSection {
     display: inline-flex;
     align-items: center;
diff --git a/src/admin/shared/AdminSectionNavigation/AdminSectionNavigation.tsx b/src/admin/shared/AdminSectionNavigation/AdminSectionNavigation.tsx
index 5b8e07d9f..f82ed5ef3 100644
--- a/src/admin/shared/AdminSectionNavigation/AdminSectionNavigation.tsx
+++ b/src/admin/shared/AdminSectionNavigation/AdminSectionNavigation.tsx
@@ -24,7 +24,9 @@ import { PackageSolidIcon } from 'pixel-art-icons/icons/package-solid'
 import { UsersSolidIcon } from 'pixel-art-icons/icons/users-solid'
 import { ToolCaseSolidIcon } from 'pixel-art-icons/icons/tool-case-solid'
 import { SearchSolidIcon } from 'pixel-art-icons/icons/search-solid'
+import { ChevronDown2Icon } from 'pixel-art-icons/icons/chevron-down-2'
 import { Button } from '@ui/components/Button'
+import { cn } from '@ui/cn'
 import { ContextMenu, ContextMenuItem, ContextMenuSeparator } from '@ui/components/ContextMenu'
 import { listCmsPlugins } from '@core/persistence/cmsPlugins'
 import type { CmsCurrentUser } from '@core/persistence'
@@ -212,6 +214,12 @@ export function AdminSectionNavigation({
  * pages, grouped by plugin when a plugin contributes more than one page.
  * Uses the shared ContextMenu primitive anchored to the trigger button —
  * same pattern as AccountMenuButton.
+ *
+ * Opens on hover as well as click; a short close-intent timer keeps the
+ * menu up while the pointer crosses the gap between trigger and menu.
+ * When the current section lives inside the menu (SEO, plugin pages), the
+ * trigger carries the same bold "current section" text the sibling nav
+ * items use.
  */
 function ToolsNavDropdown({
   active,
@@ -226,9 +234,30 @@ function ToolsNavDropdown({
 }) {
   const [open, setOpen] = useState(false)
   const triggerRef = useRef<HTMLButtonElement>(null)
+  const closeTimer = useRef<number | null>(null)
   const navigate = useAdminNavigate()
 
+  function cancelClose(): void {
+    if (closeTimer.current !== null) {
+      window.clearTimeout(closeTimer.current)
+      closeTimer.current = null
+    }
+  }
+
+  function scheduleClose(): void {
+    cancelClose()
+    closeTimer.current = window.setTimeout(() => setOpen(false), 160)
+  }
+
+  useEffect(
+    () => () => {
+      if (closeTimer.current !== null) window.clearTimeout(closeTimer.current)
+    },
+    [],
+  )
+
   function go(to: string): void {
+    cancelClose()
     setOpen(false)
     onNavigateStart?.()
     navigate(to)
@@ -253,12 +282,18 @@ function ToolsNavDropdown({
         aria-label="Tools menu"
         aria-haspopup="menu"
         aria-expanded={open}
-        className={toolbarStyles.adminLink}
+        className={cn(toolbarStyles.adminLink, active && toolbarStyles.adminLinkCurrent)}
         data-testid="tools-nav-trigger"
         onClick={() => setOpen((current) => !current)}
+        onMouseEnter={() => {
+          cancelClose()
+          setOpen(true)
+        }}
+        onMouseLeave={scheduleClose}
       >
         <ToolCaseSolidIcon size={NAV_ICON_SIZE} aria-hidden="true" />
         <span>Tools</span>
+        <ChevronDown2Icon size={10} aria-hidden="true" className={toolbarStyles.adminLinkChevron} />
       </Button>
       {open && typeof document !== 'undefined' && createPortal(
         <ContextMenu
@@ -269,6 +304,8 @@ function ToolsNavDropdown({
           align="start"
           width={220}
           zIndex={10000}
+          onMouseEnter={cancelClose}
+          onMouseLeave={scheduleClose}
         >
           {showSeo && (
             <ContextMenuItem

From d28bdac2c7993a1844d60744e98e9326db468e14 Mon Sep 17 00:00:00 2001
From: DavidBabinec <hello@davidbabinec.com>
Date: Sat, 13 Jun 2026 11:25:33 +0200
Subject: [PATCH 21/26] chore(seo): de-export internal SITE_DEFAULTS_ID, drop
 stale spec qualifier
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

SITE_DEFAULTS_ID is only used within MetaTab — make it a private const.
The design spec now lives on main (landed via #52), so drop the "(local)"
qualifier in the feature doc.

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
---
 docs/features/seo.md                 | 2 +-
 src/admin/pages/seo/tabs/MetaTab.tsx | 2 +-
 2 files changed, 2 insertions(+), 2 deletions(-)

diff --git a/docs/features/seo.md b/docs/features/seo.md
index 92d480bbd..2dd0d1c97 100644
--- a/docs/features/seo.md
+++ b/docs/features/seo.md
@@ -6,7 +6,7 @@ Open Graph + X cards, schema.org JSON-LD, generated `robots.txt` with
 AI-crawler controls, `sitemap.xml`, and an admin workspace at
 `/admin/tools/seo` with AI-assisted copy suggestions.
 
-Spec history: `docs/superpowers/specs/2026-06-12-seo-workspace-design.md` (local).
+Spec history: `docs/superpowers/specs/2026-06-12-seo-workspace-design.md`.
 
 ---
 
diff --git a/src/admin/pages/seo/tabs/MetaTab.tsx b/src/admin/pages/seo/tabs/MetaTab.tsx
index c92d82515..94f1cf88c 100644
--- a/src/admin/pages/seo/tabs/MetaTab.tsx
+++ b/src/admin/pages/seo/tabs/MetaTab.tsx
@@ -35,7 +35,7 @@ import { SiteDefaultsEditor } from '../components/SiteDefaultsEditor'
 import styles from './MetaTab.module.css'
 
 /** Selection id for the pinned site-defaults pseudo-target. */
-export const SITE_DEFAULTS_ID = 'site:defaults'
+const SITE_DEFAULTS_ID = 'site:defaults'
 
 interface MetaTabProps {
   workspace: SeoWorkspace

From d2143f32824d7d82db9ef8d0d04f0a2f027a9b56 Mon Sep 17 00:00:00 2001
From: DavidBabinec <hello@davidbabinec.com>
Date: Sat, 13 Jun 2026 12:04:15 +0200
Subject: [PATCH 22/26] =?UTF-8?q?feat(seo):=20robots.txt=20=E2=80=94=20cus?=
 =?UTF-8?q?tom=20rules,=20escape=20hatch=20+=20URL=20tester,=20env=20prote?=
 =?UTF-8?q?ction?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Three professional-grade additions to the robots.txt feature, all driven by
the same pure generator the endpoint and the live preview share.

#1 Path-level custom rules. SeoRobotsSettings gains a `rules` array
(per-user-agent allow/disallow paths) and a `disallowSystemPaths` default
(on) that blocks `/admin` and `/_instatic/`. The generator becomes a
UA→group merge, so system paths, AI-crawler toggles, and custom rules
compose without ever repeating a `User-agent:` header.

#2 Escape hatch + validation. A raw `extraDirectives` field appends verbatim
(Clean-param, Host, a brand-new bot). New robotsAnalysis.ts adds
`lintRobotsTxt` (unknown directives, rules before any User-agent, malformed
values) and `matchRobots` (Google longest-match, Allow tie-break, `*`/`$`),
surfaced in the tab as a lint panel and a live "test a URL" checker.

#3 Environment protection. `requestHostIsCanonical` compares the trusted
request Host against PUBLIC_ORIGINS; a non-canonical host (preview/staging)
gets a blanket `Disallow: /` from robots.txt plus `X-Robots-Tag: noindex`
on pages, static assets, and uploads — so non-production deploys can't be
indexed even via a direct asset URL. Null when unconfigured, so local dev
is unaffected.

The Robots tab grows three settings cards (crawling toggles incl. the new
system-path block · custom-rule editor · Advanced raw directives) beside
the preview, lint panel, and URL tester.

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
---
 docs/features/seo.md                          |  35 ++-
 server/auth/security.ts                       |  31 ++
 server/publish/seoEndpoints.ts                |  14 +-
 server/router.ts                              |  33 ++-
 src/__tests__/admin/seoWorkspace.test.tsx     |  38 +++
 src/__tests__/server/seoEndpoints.test.ts     |  38 ++-
 src/admin/pages/seo/tabs/RobotsTab.tsx        | 278 +++++++++++++++++-
 .../pages/seo/tabs/SettingsTabs.module.css    | 111 +++++++
 src/core/seo/__tests__/robots.test.ts         |  89 ++++--
 src/core/seo/__tests__/robotsAnalysis.test.ts |  73 +++++
 src/core/seo/index.ts                         |  12 +-
 src/core/seo/robots.ts                        | 102 ++++++-
 src/core/seo/robotsAnalysis.ts                | 193 ++++++++++++
 src/core/seo/schema.ts                        |  29 ++
 14 files changed, 1007 insertions(+), 69 deletions(-)
 create mode 100644 src/core/seo/__tests__/robotsAnalysis.test.ts
 create mode 100644 src/core/seo/robotsAnalysis.ts

diff --git a/docs/features/seo.md b/docs/features/seo.md
index 2dd0d1c97..ceb003800 100644
--- a/docs/features/seo.md
+++ b/docs/features/seo.md
@@ -19,7 +19,8 @@ One engine module owns everything: **`src/core/seo/`** (barrel-gated).
 | `schema.ts` | `SeoMetadataSchema` (per-target object stored in `cells_json.seo`), `SiteSeoSettingsSchema` (`site.settings.seo`: title pattern, description, default social image, X handle/card, organization, robots, sitemap) |
 | `resolve.ts` | `resolveSeoMetadata` — the single fallback engine (see below) |
 | `jsonLd.ts` | `buildJsonLdEntities` (`WebSite`, `Organization`, `Article`, `BreadcrumbList`) + `serializeJsonLd` (escapes `</script`, `<!--`) |
-| `robots.ts` | `generateRobotsTxt` — shared by the server endpoint and the admin live preview (byte-identical) |
+| `robots.ts` | `generateRobotsTxt` — shared by the server endpoint and the admin live preview (byte-identical). Composes one group per user-agent from: the `*` group (with default system-path disallows), the AI-crawler toggles, and custom `rules`; appends raw `extraDirectives`; `SYSTEM_DISALLOW_PATHS` is the opt-out default list. `blockAll` serves a bare `Disallow: /` for preview hosts. |
+| `robotsAnalysis.ts` | `lintRobotsTxt` (flags unknown directives, rules before any `User-agent`, malformed values) + `matchRobots` (is a path crawlable for a UA — Google longest-match, `Allow` tie-break, `*`/`$` support). Powers the Robots tab's lint panel and URL tester. |
 | `aiCrawlers.ts` | The AI-crawler user-agent lists behind the Robots tab's two toggles |
 | `health.ts` | `computeSeoReport` — per-target weighted checks + 0–100 score (`aggregateSeoScore`, `seoScoreTier` for the site-wide rollup and good/fair/poor tiers) |
 | `lengthMeter.ts` | Approximate pixel-width metering with an ideal band (~580px title / ~990px description budgets; "ok" only between the too-short minimum and the budget) |
@@ -87,16 +88,29 @@ static assets and public rendering. Both generate from the **published
 snapshot** and cache keyed by `publishVersion` — SEO follows the publish
 lifecycle (edit → publish → live).
 
-- `robots.txt` (`text/plain`): default allow + optional per-bot `Disallow`
-  blocks from the two AI-crawler toggles (training bots: GPTBot,
-  Google-Extended, CCBot, Applebot-Extended, meta-externalagent; answer bots:
-  OAI-SearchBot, PerplexityBot, ChatGPT-User, Claude-SearchBot), plus a
-  `Sitemap:` line.
+- `robots.txt` (`text/plain`): default allow with system-path disallows
+  (`/admin`, `/_instatic/`), optional per-bot `Disallow` blocks from the two
+  AI-crawler toggles (training bots: GPTBot, Google-Extended, CCBot,
+  Applebot-Extended, meta-externalagent; answer bots: OAI-SearchBot,
+  PerplexityBot, ChatGPT-User, Claude-SearchBot), custom per-UA rules, raw
+  extra directives, and a `Sitemap:` line.
 - `sitemap.xml` (`application/xml`): published routable pages + post rows,
   excluding templates, `noindex` targets, and
   `site.settings.seo.sitemap.excludedTargets`; `<lastmod>` from publish
   timestamps. Disabled ⇒ 404.
 
+### Environment protection
+
+`requestHostIsCanonical(req)` (in `server/auth/security.ts`) compares the
+request `Host` (trusted; never `X-Forwarded-*`) against the configured
+`PUBLIC_ORIGINS`. On a non-canonical host — a preview/staging deploy whose
+host isn't a configured origin — `robots.txt` serves a blanket `Disallow: /`
+(uncached) and the static-asset, upload, and public-page handlers stamp
+`X-Robots-Tag: noindex, nofollow`, so a non-production deploy can't be
+indexed even via a direct asset URL. With no public origin configured the
+predicate returns `null` and behavior is unchanged (local dev / unconfigured
+installs are unaffected).
+
 ## Admin workspace — `/admin/tools/seo`
 
 `src/admin/pages/seo/`. Reached from the **Tools** nav dropdown
@@ -129,9 +143,12 @@ publish — the same machinery as the Site toolbar, not a parallel path.
   fields hide behind "Customize X preview" until set; switching targets
   while dirty asks via an in-app dialog. The Schema view pretty-prints the
   exact JSON-LD the publisher will emit.
-- **Robots.txt tab** — settings card (indexing + AI-crawler switch rows)
-  beside a sticky live preview generated by the same `generateRobotsTxt`
-  the endpoint serves.
+- **Robots.txt tab** — three settings cards (crawling toggles: indexing,
+  system-path block, AI training/answer crawlers · custom per-UA Allow/
+  Disallow rule editor · an Advanced raw-directives field) beside a sticky
+  live preview generated by the same `generateRobotsTxt` the endpoint
+  serves, a lint panel (`lintRobotsTxt`), and a "test a URL" checker
+  (`matchRobots`).
 - **Sitemap tab** — settings card (enable switch + inclusion counts) and
   per-target include/exclude list beside a sticky entry-format sample
   (noindex targets shown as auto-excluded).
diff --git a/server/auth/security.ts b/server/auth/security.ts
index 6f33ddcb8..5faf62549 100644
--- a/server/auth/security.ts
+++ b/server/auth/security.ts
@@ -111,6 +111,37 @@ export function publicOriginIsHttps(): boolean {
   return configured?.startsWith('https://') ?? false
 }
 
+/**
+ * Whether this request is arriving on the configured production host.
+ *
+ *   - `null`  — no public origin configured; the caller can't tell, so it
+ *     should leave behavior unchanged (local dev / unconfigured installs).
+ *   - `true`  — the request `Host` matches a configured public origin.
+ *   - `false` — a public origin IS configured but this host isn't one of
+ *     them (a preview/staging deploy, a platform domain not in the set).
+ *
+ * Compares by host, not full origin: a TLS-terminating edge hands the app
+ * plain HTTP with the real `Host` header, so the scheme would differ even on
+ * the canonical domain. Reads only the trusted `Host` header — never
+ * `X-Forwarded-*` — matching `expectedOrigin`'s threat model.
+ *
+ * Used by the robots.txt endpoint and the static/upload/page handlers to
+ * keep non-production deploys out of search (Disallow + `X-Robots-Tag`).
+ */
+export function requestHostIsCanonical(req: Request): boolean | null {
+  if (publicOrigins.length === 0) return null
+  const host = (req.headers.get('host') ?? new URL(req.url).host).toLowerCase()
+  if (host === '') return false
+  for (const origin of publicOrigins) {
+    try {
+      if (new URL(origin).host.toLowerCase() === host) return true
+    } catch {
+      // Skip malformed configured origins.
+    }
+  }
+  return false
+}
+
 /**
  * True when the request's `Origin` header is acceptable for a state-changing
  * action. The check is a CSRF defense-in-depth on top of `SameSite=Lax`:
diff --git a/server/publish/seoEndpoints.ts b/server/publish/seoEndpoints.ts
index 3bd89d844..fa0148e91 100644
--- a/server/publish/seoEndpoints.ts
+++ b/server/publish/seoEndpoints.ts
@@ -24,7 +24,7 @@ import {
   absoluteUrl,
   type SiteSeoSettings,
 } from '@core/seo'
-import { canonicalPublicOrigin } from '../auth/security'
+import { canonicalPublicOrigin, requestHostIsCanonical } from '../auth/security'
 import { listPublishedRowsForSitemap } from '../repositories/data/publish'
 import { getLatestSnapshotForVersion } from './publishedSnapshotCache'
 import { getPublishVersion } from './publishState'
@@ -74,7 +74,17 @@ async function publishedSeoSettings(db: DbClient): Promise<SiteSeoSettings | und
 // robots.txt
 // ---------------------------------------------------------------------------
 
-export async function serveRobotsTxt(db: DbClient, url: URL): Promise<Response> {
+export async function serveRobotsTxt(db: DbClient, url: URL, req: Request): Promise<Response> {
+  // Non-canonical host (preview/staging) → blanket Disallow, uncached: the
+  // body doesn't depend on settings and must never be confused with the
+  // production body (the cache keys on the resolved canonical origin, which
+  // is identical for every host).
+  if (requestHostIsCanonical(req) === false) {
+    return new Response(generateRobotsTxt({ sitemapEnabled: false, blockAll: true }), {
+      headers: { 'content-type': 'text/plain; charset=utf-8', 'x-robots-tag': 'noindex' },
+    })
+  }
+
   const version = getPublishVersion()
   const origin = resolveOrigin(url)
 
diff --git a/server/router.ts b/server/router.ts
index 5480156d1..9196f86c9 100644
--- a/server/router.ts
+++ b/server/router.ts
@@ -16,6 +16,7 @@ import { isRuntimePackagePath, tryServeRuntimePackage } from './publish/runtime/
 import { jsonResponse } from './http'
 import { binaryResponse, toArrayBuffer } from './binary'
 import { hardenUploadResponse, serveAdminApp, serveStaticFile } from './static'
+import { requestHostIsCanonical } from './auth/security'
 import { registry } from '@core/module-engine'
 import type { CssBundleFile, SiteCssBundleId } from '@core/publisher'
 import { buildPublishedSiteCssBundle } from './publish/siteCssBundle'
@@ -360,7 +361,8 @@ async function tryServeStaticAsset(
 ): Promise<Response | null> {
   if (!runtime.staticDir) return null
   if (pathname === '/' || pathname === '/index.html') return null
-  return await serveStaticFile(runtime.staticDir, pathname, _req)
+  const asset = await serveStaticFile(runtime.staticDir, pathname, _req)
+  return asset && withPreviewNoindex(_req, asset)
 }
 
 async function tryServeUpload(
@@ -389,13 +391,13 @@ async function tryServeUpload(
     const headers = new Headers(hardened.headers)
     headers.set('access-control-allow-origin', '*')
     headers.set('cross-origin-resource-policy', 'cross-origin')
-    return new Response(hardened.body, {
+    return withPreviewNoindex(req, new Response(hardened.body, {
       status: hardened.status,
       statusText: hardened.statusText,
       headers,
-    })
+    }))
   }
-  return hardened
+  return withPreviewNoindex(req, hardened)
 }
 
 async function tryServeAdminApp(
@@ -437,14 +439,15 @@ function tryServeSeoFiles(
   pathname: string,
 ): Promise<Response> | null {
   if (req.method !== 'GET' && req.method !== 'HEAD') return null
-  if (pathname === '/robots.txt') return serveRobotsTxt(runtime.db, url)
+  if (pathname === '/robots.txt') return serveRobotsTxt(runtime.db, url, req)
   if (pathname === '/sitemap.xml') return serveSitemapXml(runtime.db, url)
   return null
 }
 
 async function tryServePublicRoute(req: Request, runtime: ServerRuntime, url: URL, _pathname: string): Promise<Response | null> {
   if (req.method !== 'GET') return null
-  return await renderPublicResolution(runtime.db, url, runtime.uploadsDir)
+  const rendered = await renderPublicResolution(runtime.db, url, runtime.uploadsDir)
+  return rendered && withPreviewNoindex(req, rendered)
 }
 
 /**
@@ -466,6 +469,24 @@ async function trySetupRedirect(req: Request, runtime: ServerRuntime, _url: URL,
 // Helpers
 // ---------------------------------------------------------------------------
 
+/**
+ * On a non-canonical host (a preview/staging deploy whose `Host` isn't the
+ * configured production origin), stamp `X-Robots-Tag: noindex, nofollow` on
+ * served content so the preview can't be indexed even via a direct asset URL
+ * — the hard guarantee robots.txt's Disallow can't give. No-op when the host
+ * is canonical or when no public origin is configured (local dev).
+ */
+function withPreviewNoindex(req: Request, response: Response): Response {
+  if (requestHostIsCanonical(req) !== false) return response
+  const headers = new Headers(response.headers)
+  headers.set('x-robots-tag', 'noindex, nofollow')
+  return new Response(response.body, {
+    status: response.status,
+    statusText: response.statusText,
+    headers,
+  })
+}
+
 function adminUiNotBuiltResponse(pathname: string): Response {
   const targetUrl = `${VITE_DEV_URL}${pathname}`
   const html = `<!doctype html>
diff --git a/src/__tests__/admin/seoWorkspace.test.tsx b/src/__tests__/admin/seoWorkspace.test.tsx
index 5e6e1e67c..e7612949b 100644
--- a/src/__tests__/admin/seoWorkspace.test.tsx
+++ b/src/__tests__/admin/seoWorkspace.test.tsx
@@ -371,6 +371,44 @@ describe('SEO Robots tab', () => {
     fireEvent.click(screen.getByTestId('seo-robots-ai-training'))
     expect(screen.getByTestId('seo-robots-preview').getAttribute('data-code')).toContain('User-agent: GPTBot')
   })
+
+  it('disallows system paths by default and lets you opt out', async () => {
+    mockSeoFetch()
+    renderWithSession(<RobotsHarness />)
+
+    const preview = await screen.findByTestId('seo-robots-preview')
+    expect(preview.getAttribute('data-code')).toContain('Disallow: /admin')
+
+    fireEvent.click(screen.getByTestId('seo-robots-system-paths'))
+    expect(screen.getByTestId('seo-robots-preview').getAttribute('data-code')).not.toContain('Disallow: /admin')
+  })
+
+  it('adds a custom rule and reflects it in the preview', async () => {
+    mockSeoFetch()
+    renderWithSession(<RobotsHarness />)
+    await screen.findByTestId('seo-robots-preview')
+
+    fireEvent.click(screen.getByTestId('seo-robots-add-rule'))
+    fireEvent.change(screen.getByTestId('seo-robots-rule-ua-0'), { target: { value: 'Bingbot' } })
+    fireEvent.change(screen.getByLabelText('Rule 1 disallow paths'), { target: { value: '/no-bing' } })
+
+    const code = screen.getByTestId('seo-robots-preview').getAttribute('data-code') ?? ''
+    expect(code).toContain('User-agent: Bingbot')
+    expect(code).toContain('Disallow: /no-bing')
+  })
+
+  it('URL tester reports a blocked system path and an allowed content path', async () => {
+    mockSeoFetch()
+    renderWithSession(<RobotsHarness />)
+    await screen.findByTestId('seo-robots-preview')
+
+    fireEvent.change(screen.getByTestId('seo-robots-test-ua'), { target: { value: 'Googlebot' } })
+    fireEvent.change(screen.getByTestId('seo-robots-test-path'), { target: { value: '/admin/users' } })
+    expect(screen.getByTestId('seo-robots-test-result').textContent).toContain('Blocked')
+
+    fireEvent.change(screen.getByTestId('seo-robots-test-path'), { target: { value: '/about' } })
+    expect(screen.getByTestId('seo-robots-test-result').textContent).toContain('Allowed')
+  })
 })
 
 describe('Tools navigation', () => {
diff --git a/src/__tests__/server/seoEndpoints.test.ts b/src/__tests__/server/seoEndpoints.test.ts
index 2bd5e6077..051222155 100644
--- a/src/__tests__/server/seoEndpoints.test.ts
+++ b/src/__tests__/server/seoEndpoints.test.ts
@@ -14,6 +14,7 @@ import {
   resetSeoEndpointCachesForTests,
 } from '../../../server/publish/seoEndpoints'
 import { bumpPublishVersion } from '../../../server/publish/publishState'
+import { configurePublicOrigins, resetPublicOrigins } from '../../../server/auth/security'
 import type { SiteSeoSettings } from '@core/seo'
 
 function makeSiteJson(seo: SiteSeoSettings | undefined) {
@@ -102,6 +103,9 @@ function makeFakeDb(seo: SiteSeoSettings | undefined, sitemapRows: FakeRow[]): D
 }
 
 const URL_NO_ORIGIN = new URL('http://localhost:3001/robots.txt')
+// No public origin configured in these tests ⇒ requestHostIsCanonical → null
+// ⇒ env protection is inert, so this request never changes the output.
+const REQ = new Request('http://localhost:3001/robots.txt')
 
 beforeEach(() => {
   resetSeoEndpointCachesForTests()
@@ -113,7 +117,7 @@ beforeEach(() => {
 
 describe('GET /robots.txt', () => {
   it('serves text/plain with default allow + sitemap line', async () => {
-    const res = await serveRobotsTxt(makeFakeDb(undefined, []), URL_NO_ORIGIN)
+    const res = await serveRobotsTxt(makeFakeDb(undefined, []), URL_NO_ORIGIN, REQ)
     expect(res.headers.get('content-type')).toBe('text/plain; charset=utf-8')
     const body = await res.text()
     expect(body).toContain('User-agent: *\nAllow: /')
@@ -126,29 +130,51 @@ describe('GET /robots.txt', () => {
       { robots: { allowAiTrainingCrawlers: false, allowAiAnswerCrawlers: false } },
       [],
     )
-    const body = await (await serveRobotsTxt(db, URL_NO_ORIGIN)).text()
+    const body = await (await serveRobotsTxt(db, URL_NO_ORIGIN, REQ)).text()
     expect(body).toContain('User-agent: GPTBot\nDisallow: /')
     expect(body).toContain('User-agent: PerplexityBot\nDisallow: /')
   })
 
   it('disables indexing wholesale when indexingEnabled is false', async () => {
     const db = makeFakeDb({ robots: { indexingEnabled: false } }, [])
-    const body = await (await serveRobotsTxt(db, URL_NO_ORIGIN)).text()
+    const body = await (await serveRobotsTxt(db, URL_NO_ORIGIN, REQ)).text()
     expect(body).toContain('User-agent: *\nDisallow: /')
   })
 
   it('caches per publish version', async () => {
     const db = makeFakeDb(undefined, [])
-    const first = await (await serveRobotsTxt(db, URL_NO_ORIGIN)).text()
+    const first = await (await serveRobotsTxt(db, URL_NO_ORIGIN, REQ)).text()
     // Same version: served from cache even if settings change underneath.
     const dbChanged = makeFakeDb({ robots: { indexingEnabled: false } }, [])
-    const second = await (await serveRobotsTxt(dbChanged, URL_NO_ORIGIN)).text()
+    const second = await (await serveRobotsTxt(dbChanged, URL_NO_ORIGIN, REQ)).text()
     expect(second).toBe(first)
     // New publish version: regenerated.
     bumpPublishVersion()
-    const third = await (await serveRobotsTxt(dbChanged, URL_NO_ORIGIN)).text()
+    const third = await (await serveRobotsTxt(dbChanged, URL_NO_ORIGIN, REQ)).text()
     expect(third).toContain('Disallow: /')
   })
+
+  it('serves a blanket Disallow on a non-canonical host (preview protection)', async () => {
+    configurePublicOrigins(['https://acme.com'])
+    try {
+      const db = makeFakeDb(undefined, [])
+      // Request arriving on a preview host that is NOT the configured origin.
+      const previewReq = new Request('https://preview-abc.vercel.app/robots.txt', {
+        headers: { host: 'preview-abc.vercel.app' },
+      })
+      const res = await serveRobotsTxt(db, new URL('https://preview-abc.vercel.app/robots.txt'), previewReq)
+      const body = await res.text()
+      expect(body).toBe('User-agent: *\nDisallow: /\n')
+      expect(res.headers.get('x-robots-tag')).toBe('noindex')
+
+      // The canonical host still serves the normal allow body.
+      const canonReq = new Request('https://acme.com/robots.txt', { headers: { host: 'acme.com' } })
+      const canon = await (await serveRobotsTxt(db, new URL('https://acme.com/robots.txt'), canonReq)).text()
+      expect(canon).toContain('User-agent: *\nAllow: /')
+    } finally {
+      resetPublicOrigins()
+    }
+  })
 })
 
 describe('GET /sitemap.xml', () => {
diff --git a/src/admin/pages/seo/tabs/RobotsTab.tsx b/src/admin/pages/seo/tabs/RobotsTab.tsx
index 3235bd09b..319de92ce 100644
--- a/src/admin/pages/seo/tabs/RobotsTab.tsx
+++ b/src/admin/pages/seo/tabs/RobotsTab.tsx
@@ -1,14 +1,19 @@
 /**
  * RobotsTab — generated robots.txt controls + live preview.
  *
- * Two-column workbench: the settings card (shared SeoSwitchRow rows —
- * indexing, AI training crawlers, AI answer crawlers) on the left, a sticky
- * byte-identical CodeMirror preview of the served file on the right — the
- * preview calls the same `generateRobotsTxt` the server endpoint uses.
- * Saving writes `site.settings.seo.robots`; output goes live with the
- * publish lifecycle.
+ * Two-column workbench. Left settings column:
+ *   - Crawling card: indexing + AI-crawler toggles + a system-paths default.
+ *   - Custom rules card: per-user-agent Allow/Disallow groups.
+ *   - Advanced card: raw `extraDirectives` appended verbatim (escape hatch).
+ * Right column: the byte-identical CodeMirror preview (same `generateRobotsTxt`
+ * the endpoint serves), a lint panel, and a "test a URL" checker.
+ *
+ * Saving writes `site.settings.seo.robots`; output goes live on publish.
  */
 import { useState } from 'react'
+import { Input, Textarea } from '@ui/components/Input'
+import { Button } from '@ui/components/Button'
+import { cn } from '@ui/cn'
 import { getErrorMessage } from '@core/utils/errorMessage'
 import { publishCmsDraft } from '@core/persistence'
 import { hasCapability } from '@admin/access'
@@ -16,9 +21,12 @@ import { useCurrentAdminUser } from '@admin/sessionContext'
 import { StepUpCancelledMessage, useStepUp } from '@admin/shared/StepUp'
 import {
   generateRobotsTxt,
+  lintRobotsTxt,
+  matchRobots,
   AI_TRAINING_CRAWLERS,
   AI_ANSWER_CRAWLERS,
   type SeoRobotsSettings,
+  type SeoRobotsRule,
 } from '@core/seo'
 import { SeoCodeViewer } from '../components/SeoCodeViewer'
 import { SeoSwitchRow } from '../components/SeoFormRow'
@@ -33,33 +41,120 @@ interface RobotsTabProps {
   bridge: SeoSaveBridge
 }
 
+/**
+ * Rules are edited as raw multi-line text (one path per line) so typing a
+ * newline never gets stripped mid-edit; they compile to `string[]` only when
+ * building the settings object.
+ */
+interface RuleDraft {
+  userAgent: string
+  allowText: string
+  disallowText: string
+}
+
+type SaveState = 'idle' | 'saving' | 'saved' | 'publishing' | 'published' | 'error'
+
+function parseLines(text: string): string[] {
+  return text.split('\n').map((line) => line.trim()).filter((line) => line !== '')
+}
+
+function rulesToDrafts(rules: SeoRobotsRule[] | undefined): RuleDraft[] {
+  return (rules ?? []).map((rule) => ({
+    userAgent: rule.userAgent,
+    allowText: (rule.allow ?? []).join('\n'),
+    disallowText: (rule.disallow ?? []).join('\n'),
+  }))
+}
+
+/** Toggles draft + rule drafts → the persisted/previewed settings object. */
+function compileRobots(toggles: SeoRobotsSettings, rules: RuleDraft[]): SeoRobotsSettings {
+  const compiled: SeoRobotsRule[] = rules
+    .map((rule) => {
+      const out: SeoRobotsRule = { userAgent: rule.userAgent.trim() }
+      const allow = parseLines(rule.allowText)
+      const disallow = parseLines(rule.disallowText)
+      if (allow.length > 0) out.allow = allow
+      if (disallow.length > 0) out.disallow = disallow
+      return out
+    })
+    .filter((rule) => rule.userAgent !== '')
+
+  const next: SeoRobotsSettings = { ...toggles }
+  const extra = (toggles.extraDirectives ?? '').trim()
+  if (extra === '') delete next.extraDirectives
+  else next.extraDirectives = extra
+  if (compiled.length > 0) next.rules = compiled
+  else delete next.rules
+  return next
+}
+
+/** Canonical signature for dirty comparison — fills defaults, fixes key order. */
+function robotsSignature(settings: SeoRobotsSettings): string {
+  return JSON.stringify({
+    indexingEnabled: settings.indexingEnabled ?? true,
+    allowAiTrainingCrawlers: settings.allowAiTrainingCrawlers ?? true,
+    allowAiAnswerCrawlers: settings.allowAiAnswerCrawlers ?? true,
+    disallowSystemPaths: settings.disallowSystemPaths ?? true,
+    extraDirectives: (settings.extraDirectives ?? '').trim(),
+    rules: (settings.rules ?? []).map((rule) => ({
+      userAgent: rule.userAgent,
+      allow: rule.allow ?? [],
+      disallow: rule.disallow ?? [],
+    })),
+  })
+}
+
 export function RobotsTab({ workspace, canManage, bridge }: RobotsTabProps) {
   const stored = workspace.siteSeo?.robots ?? {}
-  const [draft, setDraft] = useState<SeoRobotsSettings>(stored)
-  const [saveState, setSaveState] = useState<'idle' | 'saving' | 'saved' | 'publishing' | 'published' | 'error'>('idle')
+  // Toggles + extra directives live in `draft`; rule path-lists live in
+  // `rules` as raw text (see RuleDraft).
+  const [draft, setDraft] = useState<SeoRobotsSettings>(() => {
+    const { rules: _rules, ...rest } = stored
+    return rest
+  })
+  const [rules, setRules] = useState<RuleDraft[]>(() => rulesToDrafts(stored.rules))
+  const [saveState, setSaveState] = useState<SaveState>('idle')
   const [saveError, setSaveError] = useState<string | null>(null)
   const currentUser = useCurrentAdminUser()
   const { runStepUp } = useStepUp()
   const canPublish = !currentUser || hasCapability(currentUser, 'pages.publish')
 
-  const isDirty = JSON.stringify(draft) !== JSON.stringify(stored)
+  const effective = compileRobots(draft, rules)
+  const indexingOff = draft.indexingEnabled === false
+  const isDirty = robotsSignature(effective) !== robotsSignature(stored)
 
   const preview = generateRobotsTxt({
-    robots: draft,
+    robots: effective,
     sitemapEnabled: workspace.siteSeo?.sitemap?.enabled !== false,
     origin: workspace.publicOrigin ?? undefined,
   })
+  const lint = lintRobotsTxt(preview)
 
+  function touch(): void {
+    if (saveState !== 'idle') setSaveState('idle')
+  }
   function setFlag(flag: keyof SeoRobotsSettings, value: boolean): void {
     setDraft((current) => ({ ...current, [flag]: value }))
-    if (saveState !== 'idle') setSaveState('idle')
+    touch()
+  }
+  function addRule(): void {
+    setRules((current) => [...current, { userAgent: '', allowText: '', disallowText: '' }])
+    touch()
+  }
+  function updateRule(index: number, patch: Partial<RuleDraft>): void {
+    setRules((current) => current.map((rule, i) => (i === index ? { ...rule, ...patch } : rule)))
+    touch()
+  }
+  function removeRule(index: number): void {
+    setRules((current) => current.filter((_, i) => i !== index))
+    touch()
   }
 
   async function handleSave(): Promise<boolean> {
     setSaveState('saving')
     setSaveError(null)
     try {
-      await workspace.saveSite({ ...(workspace.siteSeo ?? {}), robots: draft })
+      await workspace.saveSite({ ...(workspace.siteSeo ?? {}), robots: effective })
       setSaveState('saved')
       return true
     } catch (err) {
@@ -125,17 +220,26 @@ export function RobotsTab({ workspace, canManage, bridge }: RobotsTabProps) {
               id="seo-robots-indexing-switch"
               label="Search indexing"
               hint="Turning this off serves a global Disallow — the whole site disappears from search."
-              checked={draft.indexingEnabled !== false}
+              checked={!indexingOff}
               disabled={!canManage}
               onCheckedChange={(value) => setFlag('indexingEnabled', value)}
               data-testid="seo-robots-indexing"
             />
+            <SeoSwitchRow
+              id="seo-robots-system-paths-switch"
+              label="Block system paths"
+              hint="Adds default Disallow rules for /admin and internal /_instatic/ routes."
+              checked={draft.disallowSystemPaths !== false}
+              disabled={!canManage || indexingOff}
+              onCheckedChange={(value) => setFlag('disallowSystemPaths', value)}
+              data-testid="seo-robots-system-paths"
+            />
             <SeoSwitchRow
               id="seo-robots-ai-training-switch"
               label="AI training crawlers"
               hint={`Bots that ingest content for model training: ${AI_TRAINING_CRAWLERS.join(', ')}.`}
               checked={draft.allowAiTrainingCrawlers !== false}
-              disabled={!canManage || draft.indexingEnabled === false}
+              disabled={!canManage || indexingOff}
               onCheckedChange={(value) => setFlag('allowAiTrainingCrawlers', value)}
               data-testid="seo-robots-ai-training"
             />
@@ -144,18 +248,162 @@ export function RobotsTab({ workspace, canManage, bridge }: RobotsTabProps) {
               label="AI answer crawlers"
               hint={`Bots that fetch content to ground live AI answers: ${AI_ANSWER_CRAWLERS.join(', ')}. Blocking these removes the site from AI search results.`}
               checked={draft.allowAiAnswerCrawlers !== false}
-              disabled={!canManage || draft.indexingEnabled === false}
+              disabled={!canManage || indexingOff}
               onCheckedChange={(value) => setFlag('allowAiAnswerCrawlers', value)}
               data-testid="seo-robots-ai-answer"
             />
           </div>
+
+          <div className={styles.card}>
+            <header className={styles.cardHeader}>
+              <h2 className={styles.heading}>Custom rules</h2>
+              <p className={styles.subheading}>
+                Per-crawler Allow / Disallow paths — one path per line. Groups for the same
+                user-agent merge with the built-in ones above.
+              </p>
+            </header>
+
+            {rules.map((rule, index) => (
+              <div key={index} className={styles.ruleCard}>
+                <div className={styles.ruleHead}>
+                  <Input
+                    type="text"
+                    value={rule.userAgent}
+                    placeholder="User-agent — e.g. Googlebot or *"
+                    disabled={!canManage}
+                    aria-label={`Rule ${index + 1} user-agent`}
+                    onChange={(e) => updateRule(index, { userAgent: e.target.value })}
+                    data-testid={`seo-robots-rule-ua-${index}`}
+                  />
+                  <Button
+                    variant="ghost"
+                    size="sm"
+                    disabled={!canManage}
+                    onClick={() => removeRule(index)}
+                    aria-label={`Remove rule ${index + 1}`}
+                    data-testid={`seo-robots-rule-remove-${index}`}
+                  >
+                    Remove
+                  </Button>
+                </div>
+                <div className={styles.ruleGrid}>
+                  <label className={styles.ruleField}>
+                    <span className={styles.ruleLabel}>Disallow</span>
+                    <Textarea
+                      rows={2}
+                      value={rule.disallowText}
+                      placeholder={'/private\n/search'}
+                      disabled={!canManage}
+                      aria-label={`Rule ${index + 1} disallow paths`}
+                      onChange={(e) => updateRule(index, { disallowText: e.target.value })}
+                    />
+                  </label>
+                  <label className={styles.ruleField}>
+                    <span className={styles.ruleLabel}>Allow</span>
+                    <Textarea
+                      rows={2}
+                      value={rule.allowText}
+                      placeholder={'/public'}
+                      disabled={!canManage}
+                      aria-label={`Rule ${index + 1} allow paths`}
+                      onChange={(e) => updateRule(index, { allowText: e.target.value })}
+                    />
+                  </label>
+                </div>
+              </div>
+            ))}
+
+            <Button
+              variant="secondary"
+              size="sm"
+              disabled={!canManage}
+              onClick={addRule}
+              data-testid="seo-robots-add-rule"
+            >
+              Add rule
+            </Button>
+          </div>
+
+          <div className={styles.card}>
+            <header className={styles.cardHeader}>
+              <h2 className={styles.heading}>Advanced</h2>
+              <p className={styles.subheading}>
+                Extra directives appended verbatim — for one-offs like <code>Clean-param</code> or
+                <code> Host</code>. Linted, never dropped.
+              </p>
+            </header>
+            <Textarea
+              rows={4}
+              value={draft.extraDirectives ?? ''}
+              placeholder={'Clean-param: ref /\nHost: example.com'}
+              disabled={!canManage}
+              aria-label="Extra robots.txt directives"
+              onChange={(e) => {
+                setDraft((current) => ({ ...current, extraDirectives: e.target.value }))
+                touch()
+              }}
+              data-testid="seo-robots-extra"
+            />
+          </div>
         </div>
 
         <aside className={styles.previewColumn} aria-label="robots.txt preview">
           <h3 className={styles.previewHeading}>Preview</h3>
           <SeoCodeViewer docKey="robots-preview" value={preview} language="text" data-testid="seo-robots-preview" />
+
+          {lint.length > 0 && (
+            <ul className={styles.lintList} aria-label="robots.txt warnings">
+              {lint.map((finding, i) => (
+                <li key={i} className={cn(styles.lintItem, styles[`lint_${finding.level}`])}>
+                  <span className={styles.lintLine}>Line {finding.line}</span>
+                  {finding.message}
+                </li>
+              ))}
+            </ul>
+          )}
+
+          <RobotsUrlTester robotsText={preview} />
         </aside>
       </div>
     </section>
   )
 }
+
+/** Live "is this URL crawlable?" checker against the previewed file. */
+function RobotsUrlTester({ robotsText }: { robotsText: string }) {
+  const [userAgent, setUserAgent] = useState('Googlebot')
+  const [path, setPath] = useState('/')
+  const result = matchRobots(robotsText, userAgent.trim() || '*', path.trim() || '/')
+
+  return (
+    <div className={styles.tester}>
+      <h3 className={styles.previewHeading}>Test a URL</h3>
+      <div className={styles.testerRow}>
+        <Input
+          type="text"
+          value={userAgent}
+          placeholder="User-agent"
+          aria-label="Test user-agent"
+          onChange={(e) => setUserAgent(e.target.value)}
+          data-testid="seo-robots-test-ua"
+        />
+        <Input
+          type="text"
+          value={path}
+          placeholder="/path/to/page"
+          aria-label="Test path"
+          onChange={(e) => setPath(e.target.value)}
+          data-testid="seo-robots-test-path"
+        />
+      </div>
+      <p
+        className={cn(styles.testerResult, result.allowed ? styles.testerAllowed : styles.testerBlocked)}
+        role="status"
+        data-testid="seo-robots-test-result"
+      >
+        <strong>{result.allowed ? 'Allowed' : 'Blocked'}</strong>
+        {result.rule ? ` · matched ${result.rule}` : ' · no matching rule'}
+      </p>
+    </div>
+  )
+}
diff --git a/src/admin/pages/seo/tabs/SettingsTabs.module.css b/src/admin/pages/seo/tabs/SettingsTabs.module.css
index 0182fe915..64bda5878 100644
--- a/src/admin/pages/seo/tabs/SettingsTabs.module.css
+++ b/src/admin/pages/seo/tabs/SettingsTabs.module.css
@@ -132,3 +132,114 @@
     font-size: 10px;
     color: var(--editor-warning-text);
 }
+
+/* ── Custom rules editor ─────────────────────────────────────────────────── */
+.ruleCard {
+    display: flex;
+    flex-direction: column;
+    gap: 10px;
+    padding: 14px;
+    border-radius: var(--panel-radius);
+    background: var(--editor-surface-3);
+}
+
+.ruleHead {
+    display: flex;
+    align-items: center;
+    gap: 8px;
+}
+
+.ruleHead > :first-child {
+    flex: 1;
+    min-width: 0;
+}
+
+.ruleGrid {
+    display: grid;
+    grid-template-columns: 1fr 1fr;
+    gap: 10px;
+}
+
+.ruleField {
+    display: flex;
+    flex-direction: column;
+    gap: 4px;
+    min-width: 0;
+}
+
+.ruleLabel {
+    font-size: 11px;
+    font-weight: 600;
+    color: var(--editor-text-muted);
+}
+
+@media (max-width: 560px) {
+    .ruleGrid {
+        grid-template-columns: 1fr;
+    }
+}
+
+/* ── Lint panel ──────────────────────────────────────────────────────────── */
+.lintList {
+    display: flex;
+    flex-direction: column;
+    gap: 1px;
+    margin: 0;
+    padding: 0;
+    list-style: none;
+    border-radius: var(--editor-radius);
+    overflow: hidden;
+}
+
+.lintItem {
+    display: flex;
+    align-items: baseline;
+    gap: 8px;
+    padding: 8px 12px;
+    font-size: 12px;
+    background: var(--editor-surface-2);
+}
+
+.lintLine {
+    flex-shrink: 0;
+    font-family: var(--font-mono);
+    font-size: 10.5px;
+    color: var(--editor-text-muted);
+}
+
+.lint_warning {
+    color: var(--editor-warning-text);
+}
+
+.lint_error {
+    color: var(--editor-danger-text);
+}
+
+/* ── URL tester ──────────────────────────────────────────────────────────── */
+.tester {
+    display: flex;
+    flex-direction: column;
+    gap: 8px;
+}
+
+.testerRow {
+    display: grid;
+    grid-template-columns: minmax(0, 0.9fr) minmax(0, 1.1fr);
+    gap: 8px;
+}
+
+.testerResult {
+    margin: 0;
+    padding: 8px 12px;
+    border-radius: var(--editor-radius);
+    font-size: 12px;
+    background: var(--editor-surface-2);
+}
+
+.testerAllowed {
+    color: var(--editor-success-text-soft);
+}
+
+.testerBlocked {
+    color: var(--editor-danger-text);
+}
diff --git a/src/core/seo/__tests__/robots.test.ts b/src/core/seo/__tests__/robots.test.ts
index 1370ff5f9..e12f0e7ff 100644
--- a/src/core/seo/__tests__/robots.test.ts
+++ b/src/core/seo/__tests__/robots.test.ts
@@ -1,18 +1,25 @@
 import { describe, expect, test } from 'bun:test'
-import { generateRobotsTxt } from '../robots'
+import { generateRobotsTxt, SYSTEM_DISALLOW_PATHS } from '../robots'
 import { AI_ANSWER_CRAWLERS, AI_TRAINING_CRAWLERS } from '../aiCrawlers'
 
 describe('generateRobotsTxt', () => {
-  test('default output allows everything and links the sitemap', () => {
+  test('default output allows everything, disallows system paths, links the sitemap', () => {
     const out = generateRobotsTxt({ sitemapEnabled: true, origin: 'https://acme.com' })
-    expect(out).toBe('User-agent: *\nAllow: /\n\nSitemap: https://acme.com/sitemap.xml\n')
+    expect(out).toBe(
+      'User-agent: *\nAllow: /\nDisallow: /admin\nDisallow: /_instatic/\n\n' +
+        'Sitemap: https://acme.com/sitemap.xml\n',
+    )
+  })
+
+  test('system-path defaults can be opted out', () => {
+    const out = generateRobotsTxt({ robots: { disallowSystemPaths: false }, sitemapEnabled: false })
+    expect(out).toBe('User-agent: *\nAllow: /\n')
+    for (const path of SYSTEM_DISALLOW_PATHS) expect(out).not.toContain(`Disallow: ${path}`)
   })
 
   test('omits the sitemap line without an origin or when disabled', () => {
     expect(generateRobotsTxt({ sitemapEnabled: true })).not.toContain('Sitemap:')
-    expect(generateRobotsTxt({ sitemapEnabled: false, origin: 'https://a.com' })).not.toContain(
-      'Sitemap:',
-    )
+    expect(generateRobotsTxt({ sitemapEnabled: false, origin: 'https://a.com' })).not.toContain('Sitemap:')
   })
 
   test('indexing disabled produces a global Disallow', () => {
@@ -23,29 +30,73 @@ describe('generateRobotsTxt', () => {
     })
     expect(out).toContain('User-agent: *\nDisallow: /')
     expect(out).not.toContain('Allow: /')
+    expect(out).not.toContain('Disallow: /admin') // blanket block, not the system list
+  })
+
+  test('blockAll serves a bare Disallow with no sitemap or extras', () => {
+    const out = generateRobotsTxt({
+      robots: { extraDirectives: 'Host: example.com', rules: [{ userAgent: 'Googlebot', disallow: ['/x'] }] },
+      sitemapEnabled: true,
+      origin: 'https://acme.com',
+      blockAll: true,
+    })
+    expect(out).toBe('User-agent: *\nDisallow: /\n')
   })
 
   test('blocking AI training crawlers emits one block per bot', () => {
+    const out = generateRobotsTxt({ robots: { allowAiTrainingCrawlers: false }, sitemapEnabled: false })
+    for (const bot of AI_TRAINING_CRAWLERS) expect(out).toContain(`User-agent: ${bot}\nDisallow: /`)
+    for (const bot of AI_ANSWER_CRAWLERS) expect(out).not.toContain(`User-agent: ${bot}`)
+  })
+
+  test('blocking AI answer crawlers emits one block per bot', () => {
+    const out = generateRobotsTxt({ robots: { allowAiAnswerCrawlers: false }, sitemapEnabled: false })
+    for (const bot of AI_ANSWER_CRAWLERS) expect(out).toContain(`User-agent: ${bot}\nDisallow: /`)
+    expect(out).toContain('User-agent: *\nAllow: /')
+  })
+
+  test('custom rules render as their own user-agent groups', () => {
     const out = generateRobotsTxt({
-      robots: { allowAiTrainingCrawlers: false },
+      robots: {
+        disallowSystemPaths: false,
+        rules: [{ userAgent: 'Googlebot', allow: ['/public'], disallow: ['/private', '/tmp'] }],
+      },
       sitemapEnabled: false,
     })
-    for (const bot of AI_TRAINING_CRAWLERS) {
-      expect(out).toContain(`User-agent: ${bot}\nDisallow: /`)
-    }
-    for (const bot of AI_ANSWER_CRAWLERS) {
-      expect(out).not.toContain(`User-agent: ${bot}`)
-    }
+    expect(out).toContain('User-agent: Googlebot\nAllow: /public\nDisallow: /private\nDisallow: /tmp')
   })
 
-  test('blocking AI answer crawlers emits one block per bot', () => {
+  test('a custom `*` rule merges into the wildcard group (no duplicate header)', () => {
     const out = generateRobotsTxt({
-      robots: { allowAiAnswerCrawlers: false },
+      robots: { disallowSystemPaths: false, rules: [{ userAgent: '*', disallow: ['/search'] }] },
       sitemapEnabled: false,
     })
-    for (const bot of AI_ANSWER_CRAWLERS) {
-      expect(out).toContain(`User-agent: ${bot}\nDisallow: /`)
-    }
-    expect(out).toContain('User-agent: *\nAllow: /')
+    expect(out).toBe('User-agent: *\nAllow: /\nDisallow: /search\n')
+    expect(out.match(/User-agent: \*/g)?.length).toBe(1)
+  })
+
+  test('a custom rule for a toggled-off AI bot merges into one block', () => {
+    const out = generateRobotsTxt({
+      robots: {
+        disallowSystemPaths: false,
+        allowAiTrainingCrawlers: false,
+        rules: [{ userAgent: 'GPTBot', disallow: ['/secret'] }],
+      },
+      sitemapEnabled: false,
+    })
+    expect(out.match(/User-agent: GPTBot/g)?.length).toBe(1)
+    expect(out).toContain('User-agent: GPTBot\nDisallow: /\nDisallow: /secret')
+  })
+
+  test('extra directives append verbatim before the sitemap line', () => {
+    const out = generateRobotsTxt({
+      robots: { disallowSystemPaths: false, extraDirectives: 'Clean-param: ref /\nHost: acme.com' },
+      sitemapEnabled: true,
+      origin: 'https://acme.com',
+    })
+    expect(out).toBe(
+      'User-agent: *\nAllow: /\n\nClean-param: ref /\nHost: acme.com\n\n' +
+        'Sitemap: https://acme.com/sitemap.xml\n',
+    )
   })
 })
diff --git a/src/core/seo/__tests__/robotsAnalysis.test.ts b/src/core/seo/__tests__/robotsAnalysis.test.ts
new file mode 100644
index 000000000..9cca65cd3
--- /dev/null
+++ b/src/core/seo/__tests__/robotsAnalysis.test.ts
@@ -0,0 +1,73 @@
+import { describe, expect, test } from 'bun:test'
+import { lintRobotsTxt, matchRobots } from '../robotsAnalysis'
+import { generateRobotsTxt } from '../robots'
+
+describe('lintRobotsTxt', () => {
+  test('clean generated output has no findings', () => {
+    const out = generateRobotsTxt({ sitemapEnabled: true, origin: 'https://acme.com' })
+    expect(lintRobotsTxt(out)).toEqual([])
+  })
+
+  test('flags a rule before any User-agent', () => {
+    const findings = lintRobotsTxt('Disallow: /private')
+    expect(findings).toHaveLength(1)
+    expect(findings[0]).toMatchObject({ line: 1, level: 'error' })
+  })
+
+  test('flags unknown directives and bad values', () => {
+    const text = 'User-agent: *\nDisalow: /typo\nSitemap: not-a-url\nCrawl-delay: soon'
+    const findings = lintRobotsTxt(text)
+    const messages = findings.map((f) => f.message).join(' | ')
+    expect(messages).toContain('Unknown directive')
+    expect(messages).toContain('absolute http(s) URL')
+    expect(messages).toContain('not a number')
+  })
+
+  test('flags an empty User-agent and a non-directive line; ignores comments', () => {
+    const findings = lintRobotsTxt('# a comment\nUser-agent:\njust some words')
+    expect(findings.some((f) => f.message.includes('User-agent has no value'))).toBe(true)
+    expect(findings.some((f) => f.message.includes('Not a "key: value"'))).toBe(true)
+    expect(findings.every((f) => f.line !== 1)).toBe(true) // comment line ignored
+  })
+})
+
+describe('matchRobots', () => {
+  const robots = generateRobotsTxt({
+    robots: {
+      rules: [{ userAgent: 'Googlebot', allow: ['/admin/public'], disallow: ['/private'] }],
+    },
+    sitemapEnabled: true,
+    origin: 'https://acme.com',
+  })
+
+  test('default content path is allowed for everyone', () => {
+    expect(matchRobots(robots, 'SomeBot', '/about').allowed).toBe(true)
+  })
+
+  test('system path is disallowed via the * group', () => {
+    const m = matchRobots(robots, 'SomeBot', '/admin/settings')
+    expect(m.allowed).toBe(false)
+    expect(m.rule).toBe('Disallow: /admin')
+  })
+
+  test('a more specific user-agent group overrides the * group', () => {
+    // Googlebot has its own group → the * group's /admin disallow does not apply.
+    expect(matchRobots(robots, 'Googlebot', '/admin/settings').allowed).toBe(true)
+    expect(matchRobots(robots, 'Googlebot', '/private/x').allowed).toBe(false)
+  })
+
+  test('longest match wins, Allow breaks ties', () => {
+    // Googlebot: Allow /admin/public (its group has no /admin disallow, so
+    // /admin/public is allowed by the explicit Allow).
+    const m = matchRobots(robots, 'Googlebot', '/admin/public/doc')
+    expect(m.allowed).toBe(true)
+    expect(m.rule).toBe('Allow: /admin/public')
+  })
+
+  test('$ end-anchor and * wildcard are honored', () => {
+    const text = 'User-agent: *\nDisallow: /*.pdf$\nDisallow: /search'
+    expect(matchRobots(text, 'X', '/files/report.pdf').allowed).toBe(false)
+    expect(matchRobots(text, 'X', '/files/report.pdf?v=1').allowed).toBe(true) // $ anchors the end
+    expect(matchRobots(text, 'X', '/search/results').allowed).toBe(false)
+  })
+})
diff --git a/src/core/seo/index.ts b/src/core/seo/index.ts
index 18be177bc..4ba549c77 100644
--- a/src/core/seo/index.ts
+++ b/src/core/seo/index.ts
@@ -13,6 +13,7 @@ export {
   SiteSeoSettingsSchema,
   SeoOrganizationSchema,
   SeoRobotsSettingsSchema,
+  SeoRobotsRuleSchema,
   SeoSitemapSettingsSchema,
   OgTypeSchema,
   XCardTypeSchema,
@@ -22,6 +23,7 @@ export {
   type SiteSeoSettings,
   type SeoOrganization,
   type SeoRobotsSettings,
+  type SeoRobotsRule,
   type SeoSitemapSettings,
   type OgType,
   type XCardType,
@@ -44,7 +46,15 @@ export {
 
 export { AI_TRAINING_CRAWLERS, AI_ANSWER_CRAWLERS } from './aiCrawlers'
 
-export { generateRobotsTxt, type GenerateRobotsTxtInput } from './robots'
+export { generateRobotsTxt, SYSTEM_DISALLOW_PATHS, type GenerateRobotsTxtInput } from './robots'
+
+export {
+  lintRobotsTxt,
+  matchRobots,
+  type RobotsLintFinding,
+  type RobotsLintLevel,
+  type RobotsMatch,
+} from './robotsAnalysis'
 
 export {
   computeSeoReport,
diff --git a/src/core/seo/robots.ts b/src/core/seo/robots.ts
index 85d77250e..87e2bdb04 100644
--- a/src/core/seo/robots.ts
+++ b/src/core/seo/robots.ts
@@ -3,6 +3,13 @@
  * the served `text/plain` body. Used by the server endpoint
  * (`server/publish/seoEndpoints.ts`) and the admin Robots.txt tab's live
  * preview, so what the tab shows is byte-identical to what crawlers get.
+ *
+ * Composition model: every directive resolves into one user-agent group
+ * (`User-agent: <ua>` + its Allow/Disallow lines). System-path defaults, the
+ * AI-crawler toggles, and custom rules all merge into the same group when
+ * they target the same agent, so the output never repeats a `User-agent:`
+ * header. Order: the `*` group first, then the rest in first-seen order.
+ * Raw `extraDirectives` append verbatim; the `Sitemap:` line is always last.
  */
 
 import { AI_ANSWER_CRAWLERS, AI_TRAINING_CRAWLERS } from './aiCrawlers'
@@ -14,28 +21,101 @@ export interface GenerateRobotsTxtInput {
   sitemapEnabled: boolean
   /** Absolute public origin for the Sitemap line; absent ⇒ line omitted. */
   origin?: string
+  /**
+   * When true, serve a blanket `Disallow: /` regardless of settings —
+   * used by the endpoint on a non-canonical host (preview/staging) so a
+   * non-production deploy never gets indexed. Skips custom rules, AI
+   * toggles, and extra directives, and omits the Sitemap line.
+   */
+  blockAll?: boolean
+}
+
+/**
+ * Non-content routes disallowed by default under `User-agent: *`. `/admin`
+ * also covers `/admin/api`; `/_instatic/` covers the lazy fragment + runtime
+ * endpoints. Opt out with `disallowSystemPaths: false`.
+ */
+export const SYSTEM_DISALLOW_PATHS = ['/admin', '/_instatic/'] as const
+
+interface Group {
+  allow: string[]
+  disallow: string[]
+}
+
+/** Append a path once (deduped) to a group's allow/disallow list. */
+function addPath(list: string[], path: string): void {
+  const trimmed = path.trim()
+  if (trimmed !== '' && !list.includes(trimmed)) list.push(trimmed)
 }
 
 export function generateRobotsTxt(input: GenerateRobotsTxtInput): string {
   const robots = input.robots ?? {}
-  const lines: string[] = []
 
-  if (robots.indexingEnabled === false) {
-    lines.push('User-agent: *', 'Disallow: /')
-  } else {
-    lines.push('User-agent: *', 'Allow: /')
+  if (input.blockAll || robots.indexingEnabled === false) {
+    const lines = ['User-agent: *', 'Disallow: /']
+    if (input.blockAll) return `${lines.join('\n')}\n`
+    // A user-chosen global block still lists the sitemap + extras.
+    return finalize(lines, input, /* allowExtras */ true)
+  }
 
-    const blockedBots: string[] = []
-    if (robots.allowAiTrainingCrawlers === false) blockedBots.push(...AI_TRAINING_CRAWLERS)
-    if (robots.allowAiAnswerCrawlers === false) blockedBots.push(...AI_ANSWER_CRAWLERS)
-    for (const bot of blockedBots) {
-      lines.push('', `User-agent: ${bot}`, 'Disallow: /')
+  // Ordered map of user-agent → group. The `*` group always exists and
+  // renders first; everything else keeps first-seen order.
+  const groups = new Map<string, Group>()
+  const groupFor = (ua: string): Group => {
+    const key = ua.trim()
+    let group = groups.get(key)
+    if (!group) {
+      group = { allow: [], disallow: [] }
+      groups.set(key, group)
     }
+    return group
+  }
+
+  const star = groupFor('*')
+  if (robots.disallowSystemPaths !== false) {
+    for (const path of SYSTEM_DISALLOW_PATHS) addPath(star.disallow, path)
+  }
+
+  // AI-crawler toggles → blanket Disallow groups per bot.
+  const blockedBots: string[] = []
+  if (robots.allowAiTrainingCrawlers === false) blockedBots.push(...AI_TRAINING_CRAWLERS)
+  if (robots.allowAiAnswerCrawlers === false) blockedBots.push(...AI_ANSWER_CRAWLERS)
+  for (const bot of blockedBots) addPath(groupFor(bot).disallow, '/')
+
+  // Custom rules merge into their target group.
+  for (const rule of robots.rules ?? []) {
+    if (rule.userAgent.trim() === '') continue
+    const group = groupFor(rule.userAgent)
+    for (const path of rule.allow ?? []) addPath(group.allow, path)
+    for (const path of rule.disallow ?? []) addPath(group.disallow, path)
+  }
+
+  // Render: `*` first, then the rest in insertion order.
+  const orderedKeys = ['*', ...[...groups.keys()].filter((key) => key !== '*')]
+  const lines: string[] = []
+  let first = true
+  for (const ua of orderedKeys) {
+    const group = groups.get(ua)!
+    if (!first) lines.push('')
+    first = false
+    lines.push(`User-agent: ${ua}`)
+    // The `*` group with no explicit allow means "index everything" — emit
+    // an explicit `Allow: /` so the intent reads clearly. A bare disallow
+    // group (a blocked bot) needs no Allow line.
+    if (ua === '*' && group.allow.length === 0) lines.push('Allow: /')
+    for (const path of group.allow) lines.push(`Allow: ${path}`)
+    for (const path of group.disallow) lines.push(`Disallow: ${path}`)
   }
 
+  return finalize(lines, input, /* allowExtras */ true)
+}
+
+/** Append the optional extra-directives block, then the Sitemap line. */
+function finalize(lines: string[], input: GenerateRobotsTxtInput, allowExtras: boolean): string {
+  const extra = allowExtras ? (input.robots?.extraDirectives ?? '').trim() : ''
+  if (extra !== '') lines.push('', extra)
   if (input.sitemapEnabled && input.origin) {
     lines.push('', `Sitemap: ${input.origin.replace(/\/+$/, '')}/sitemap.xml`)
   }
-
   return `${lines.join('\n')}\n`
 }
diff --git a/src/core/seo/robotsAnalysis.ts b/src/core/seo/robotsAnalysis.ts
new file mode 100644
index 000000000..fa7dfd0fe
--- /dev/null
+++ b/src/core/seo/robotsAnalysis.ts
@@ -0,0 +1,193 @@
+/**
+ * robots.txt analysis — pure helpers the admin Robots.txt tab uses to lint
+ * the generated file and test a URL against it. Both operate on the SAME
+ * text the endpoint serves (via `generateRobotsTxt`), so the tab's feedback
+ * always reflects reality, including raw `extraDirectives`.
+ *
+ *   - `lintRobotsTxt` flags syntax problems crawlers would ignore silently
+ *     (unknown directives, rules before any `User-agent`, malformed values).
+ *   - `matchRobots` answers "is this path allowed for this crawler?" using
+ *     Google's longest-match semantics (most-specific rule wins, `Allow`
+ *     breaks ties) with `*` wildcard and `$` end-anchor support.
+ */
+
+// ---------------------------------------------------------------------------
+// Lint
+// ---------------------------------------------------------------------------
+
+export type RobotsLintLevel = 'warning' | 'error'
+
+export interface RobotsLintFinding {
+  /** 1-based line number in the linted text. */
+  line: number
+  level: RobotsLintLevel
+  message: string
+}
+
+const KNOWN_DIRECTIVES = new Set([
+  'user-agent',
+  'allow',
+  'disallow',
+  'sitemap',
+  'crawl-delay',
+  'host',
+  'clean-param',
+])
+
+/** Directives that belong to a `User-agent` group (vs file-global ones). */
+const GROUP_DIRECTIVES = new Set(['allow', 'disallow', 'crawl-delay'])
+
+export function lintRobotsTxt(text: string): RobotsLintFinding[] {
+  const findings: RobotsLintFinding[] = []
+  let sawUserAgent = false
+
+  text.split('\n').forEach((raw, index) => {
+    const line = index + 1
+    const stripped = raw.replace(/#.*$/, '').trim()
+    if (stripped === '') return
+
+    const colon = stripped.indexOf(':')
+    if (colon === -1) {
+      findings.push({ line, level: 'error', message: `Not a "key: value" directive: "${stripped}"` })
+      return
+    }
+
+    const key = stripped.slice(0, colon).trim().toLowerCase()
+    const value = stripped.slice(colon + 1).trim()
+
+    if (!KNOWN_DIRECTIVES.has(key)) {
+      findings.push({ line, level: 'warning', message: `Unknown directive "${stripped.slice(0, colon).trim()}" — crawlers will ignore it` })
+      return
+    }
+
+    if (key === 'user-agent') {
+      sawUserAgent = true
+      if (value === '') findings.push({ line, level: 'error', message: 'User-agent has no value' })
+      return
+    }
+
+    if (GROUP_DIRECTIVES.has(key) && !sawUserAgent) {
+      findings.push({ line, level: 'error', message: `"${key}" appears before any "User-agent" group` })
+    }
+
+    if (key === 'crawl-delay' && value !== '' && Number.isNaN(Number(value))) {
+      findings.push({ line, level: 'warning', message: `Crawl-delay "${value}" is not a number` })
+    }
+
+    if (key === 'sitemap' && !/^https?:\/\//i.test(value)) {
+      findings.push({ line, level: 'warning', message: 'Sitemap should be an absolute http(s) URL' })
+    }
+  })
+
+  return findings
+}
+
+// ---------------------------------------------------------------------------
+// URL matcher
+// ---------------------------------------------------------------------------
+
+interface ParsedRule {
+  type: 'allow' | 'disallow'
+  path: string
+}
+
+interface ParsedGroup {
+  agents: string[]
+  rules: ParsedRule[]
+}
+
+/** Parse robots text into user-agent groups, collapsing consecutive headers. */
+function parseGroups(text: string): ParsedGroup[] {
+  const groups: ParsedGroup[] = []
+  let current: ParsedGroup | null = null
+  let expectingAgents = false
+
+  for (const raw of text.split('\n')) {
+    const stripped = raw.replace(/#.*$/, '').trim()
+    if (stripped === '') continue
+    const colon = stripped.indexOf(':')
+    if (colon === -1) continue
+    const key = stripped.slice(0, colon).trim().toLowerCase()
+    const value = stripped.slice(colon + 1).trim()
+
+    if (key === 'user-agent') {
+      // Consecutive User-agent lines share the following rule block.
+      if (!current || !expectingAgents) {
+        current = { agents: [], rules: [] }
+        groups.push(current)
+        expectingAgents = true
+      }
+      current.agents.push(value.toLowerCase())
+    } else if (key === 'allow' || key === 'disallow') {
+      if (!current) continue
+      expectingAgents = false
+      current.rules.push({ type: key, path: value })
+    }
+  }
+
+  return groups
+}
+
+/** Translate a robots path pattern (`*` wildcard, `$` end-anchor) to RegExp. */
+function patternToRegExp(pattern: string): RegExp {
+  let source = ''
+  for (const char of pattern) {
+    if (char === '*') source += '.*'
+    else if (char === '$') source += '$'
+    else source += char.replace(/[.+?^${}()|[\]\\]/g, '\\$&')
+  }
+  return new RegExp(`^${source}`)
+}
+
+/** Effective path length a pattern matches against, for longest-match wins. */
+function matchLength(pattern: string, path: string): number | null {
+  if (pattern === '') return null
+  if (patternToRegExp(pattern).test(path)) {
+    // Specificity ≈ pattern length excluding wildcards (Google's rule).
+    return pattern.replace(/\*/g, '').length
+  }
+  return null
+}
+
+export interface RobotsMatch {
+  allowed: boolean
+  /** The winning rule, e.g. `Disallow: /admin`; absent ⇒ no rule applied. */
+  rule: string | null
+}
+
+/**
+ * Decide whether `path` is crawlable by `userAgent` per `robotsText`. Picks
+ * the most specific matching user-agent group (exact token, else `*`), then
+ * the longest matching Allow/Disallow within it (Allow wins ties). No
+ * matching rule ⇒ allowed.
+ */
+export function matchRobots(robotsText: string, userAgent: string, path: string): RobotsMatch {
+  const groups = parseGroups(robotsText)
+  const ua = userAgent.trim().toLowerCase()
+
+  // Prefer a group naming this agent; fall back to the `*` group.
+  const specific = groups.find((group) => group.agents.includes(ua))
+  const wildcard = groups.find((group) => group.agents.includes('*'))
+  const group = specific ?? wildcard
+  if (!group) return { allowed: true, rule: null }
+
+  let best: { type: 'allow' | 'disallow'; path: string; length: number } | null = null
+  for (const rule of group.rules) {
+    const length = matchLength(rule.path, path)
+    if (length === null) continue
+    // Longer match wins; on a tie, Allow beats Disallow.
+    if (
+      best === null ||
+      length > best.length ||
+      (length === best.length && rule.type === 'allow' && best.type === 'disallow')
+    ) {
+      best = { type: rule.type, path: rule.path, length }
+    }
+  }
+
+  if (!best) return { allowed: true, rule: null }
+  return {
+    allowed: best.type === 'allow',
+    rule: `${best.type === 'allow' ? 'Allow' : 'Disallow'}: ${best.path}`,
+  }
+}
diff --git a/src/core/seo/schema.ts b/src/core/seo/schema.ts
index 2c8051a38..fe31f2cd6 100644
--- a/src/core/seo/schema.ts
+++ b/src/core/seo/schema.ts
@@ -78,6 +78,22 @@ export const SeoOrganizationSchema = Type.Object({
 
 export type SeoOrganization = Static<typeof SeoOrganizationSchema>
 
+/**
+ * One custom robots.txt group: a user-agent plus its allow/disallow paths.
+ * Rendered as a `User-agent:` block; groups targeting the same agent as a
+ * built-in block (the `*` group, or an AI-crawler toggle) merge into it.
+ */
+export const SeoRobotsRuleSchema = Type.Object({
+  /** Target user-agent token, e.g. `*` or `Googlebot`. */
+  userAgent: Type.String(),
+  /** Path prefixes to Allow (each rendered as `Allow: <path>`). */
+  allow: Type.Optional(Type.Array(Type.String())),
+  /** Path prefixes to Disallow (each rendered as `Disallow: <path>`). */
+  disallow: Type.Optional(Type.Array(Type.String())),
+})
+
+export type SeoRobotsRule = Static<typeof SeoRobotsRuleSchema>
+
 export const SeoRobotsSettingsSchema = Type.Object({
   /** false ⇒ `Disallow: /` for every user agent. Defaults to true. */
   indexingEnabled: Type.Optional(Type.Boolean()),
@@ -85,6 +101,19 @@ export const SeoRobotsSettingsSchema = Type.Object({
   allowAiTrainingCrawlers: Type.Optional(Type.Boolean()),
   /** false ⇒ Disallow blocks for AI_ANSWER_CRAWLERS. Defaults to true. */
   allowAiAnswerCrawlers: Type.Optional(Type.Boolean()),
+  /**
+   * false ⇒ skip the default `Disallow:` lines for non-content system routes
+   * (`/admin`, `/_instatic/`) under `User-agent: *`. Defaults to true.
+   */
+  disallowSystemPaths: Type.Optional(Type.Boolean()),
+  /** Custom per-user-agent allow/disallow groups. */
+  rules: Type.Optional(Type.Array(SeoRobotsRuleSchema)),
+  /**
+   * Raw directives appended verbatim to the generated file — the escape
+   * hatch for one-offs (Clean-param, Host, a brand-new crawler). Linted in
+   * the admin tab but never silently dropped.
+   */
+  extraDirectives: Type.Optional(Type.String()),
 })
 
 export type SeoRobotsSettings = Static<typeof SeoRobotsSettingsSchema>

From 28755352d9e6a01ed825a69119ee813746ab9e0f Mon Sep 17 00:00:00 2001
From: DavidBabinec <hello@davidbabinec.com>
Date: Sat, 13 Jun 2026 12:28:50 +0200
Subject: [PATCH 23/26] refactor(seo): robots.txt as a directly-edited document
 with an assistant rail
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

The structured form (toggles + rule editor + extra-directives field) was
more complicated to use than the file it generated. Flip it: the robots.txt
body IS the artifact now — `seo.robots.content`, edited in a CodeMirror
surface that is the main column. The left rail becomes an assistant rather
than a parallel form:

- contextual recommendations (block AI crawlers / block system paths /
  "all crawlers blocked" warning) that are themselves the one-click edits,
- quick-insert shortcuts (recommended defaults, block all AI, block all),
- a lint issue list (lintRobotsTxt) and a live URL tester (matchRobots).

generateRobotsTxt now serves the stored body (or DEFAULT_ROBOTS_TEMPLATE)
and appends the Sitemap line unless one is present; the structured
SeoRobotsSettings collapses to `{ content }`. Shortcuts compose bodies from
the maintained AI-crawler lists + SYSTEM_DISALLOW_PATHS, so nothing the old
toggles did is lost — it just edits the canonical text.

Also drops the "no public origin configured" notices from the Robots and
Sitemap tabs: production always sets PUBLIC_ORIGINS, so the warning was dev-
only noise. Env protection (#3) is unchanged server-side.

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
---
 docs/features/seo.md                          |  29 +-
 src/__tests__/admin/seoWorkspace.test.tsx     |  47 +-
 src/__tests__/server/seoEndpoints.test.ts     |  17 +-
 .../seo/components/SeoCodeEditor.module.css   |  33 ++
 .../pages/seo/components/SeoCodeEditor.tsx    |  66 +++
 src/admin/pages/seo/tabs/RobotsTab.tsx        | 436 ++++++++----------
 .../pages/seo/tabs/SettingsTabs.module.css    | 105 +++--
 src/admin/pages/seo/tabs/SitemapTab.tsx       |   6 -
 src/core/seo/__tests__/robots.test.ts         |  94 +---
 src/core/seo/__tests__/robotsAnalysis.test.ts |  20 +-
 src/core/seo/index.ts                         |   9 +-
 src/core/seo/robots.ts                        | 130 ++----
 src/core/seo/robotsAnalysis.ts                |   2 +-
 src/core/seo/schema.ts                        |  39 +-
 14 files changed, 469 insertions(+), 564 deletions(-)
 create mode 100644 src/admin/pages/seo/components/SeoCodeEditor.module.css
 create mode 100644 src/admin/pages/seo/components/SeoCodeEditor.tsx

diff --git a/docs/features/seo.md b/docs/features/seo.md
index ceb003800..2996171b2 100644
--- a/docs/features/seo.md
+++ b/docs/features/seo.md
@@ -19,8 +19,8 @@ One engine module owns everything: **`src/core/seo/`** (barrel-gated).
 | `schema.ts` | `SeoMetadataSchema` (per-target object stored in `cells_json.seo`), `SiteSeoSettingsSchema` (`site.settings.seo`: title pattern, description, default social image, X handle/card, organization, robots, sitemap) |
 | `resolve.ts` | `resolveSeoMetadata` — the single fallback engine (see below) |
 | `jsonLd.ts` | `buildJsonLdEntities` (`WebSite`, `Organization`, `Article`, `BreadcrumbList`) + `serializeJsonLd` (escapes `</script`, `<!--`) |
-| `robots.ts` | `generateRobotsTxt` — shared by the server endpoint and the admin live preview (byte-identical). Composes one group per user-agent from: the `*` group (with default system-path disallows), the AI-crawler toggles, and custom `rules`; appends raw `extraDirectives`; `SYSTEM_DISALLOW_PATHS` is the opt-out default list. `blockAll` serves a bare `Disallow: /` for preview hosts. |
-| `robotsAnalysis.ts` | `lintRobotsTxt` (flags unknown directives, rules before any `User-agent`, malformed values) + `matchRobots` (is a path crawlable for a UA — Google longest-match, `Allow` tie-break, `*`/`$` support). Powers the Robots tab's lint panel and URL tester. |
+| `robots.ts` | `generateRobotsTxt` — serves the stored body verbatim (`SeoRobotsSettings.content`), falling back to `DEFAULT_ROBOTS_TEMPLATE` when empty and appending the origin-resolved `Sitemap:` line unless the body already has one. `SYSTEM_DISALLOW_PATHS` seeds the default template + the tab's "block system paths" shortcut. `blockAll` serves a bare `Disallow: /` for preview hosts. |
+| `robotsAnalysis.ts` | `lintRobotsTxt` (flags unknown directives, rules before any `User-agent`, malformed values) + `matchRobots` (is a path crawlable for a UA — Google longest-match, `Allow` tie-break, `*`/`$` support). Powers the Robots tab's issue list and URL tester, plus the contextual recommendations. |
 | `aiCrawlers.ts` | The AI-crawler user-agent lists behind the Robots tab's two toggles |
 | `health.ts` | `computeSeoReport` — per-target weighted checks + 0–100 score (`aggregateSeoScore`, `seoScoreTier` for the site-wide rollup and good/fair/poor tiers) |
 | `lengthMeter.ts` | Approximate pixel-width metering with an ideal band (~580px title / ~990px description budgets; "ok" only between the too-short minimum and the budget) |
@@ -88,12 +88,12 @@ static assets and public rendering. Both generate from the **published
 snapshot** and cache keyed by `publishVersion` — SEO follows the publish
 lifecycle (edit → publish → live).
 
-- `robots.txt` (`text/plain`): default allow with system-path disallows
-  (`/admin`, `/_instatic/`), optional per-bot `Disallow` blocks from the two
-  AI-crawler toggles (training bots: GPTBot, Google-Extended, CCBot,
-  Applebot-Extended, meta-externalagent; answer bots: OAI-SearchBot,
-  PerplexityBot, ChatGPT-User, Claude-SearchBot), custom per-UA rules, raw
-  extra directives, and a `Sitemap:` line.
+- `robots.txt` (`text/plain`): the admin-authored body (or the default
+  template — allow all + system-path disallows for `/admin` + `/_instatic/`),
+  with a `Sitemap:` line appended unless the body already declares one. The
+  Robots tab's shortcuts compose common bodies (block AI crawlers from
+  `AI_TRAINING_CRAWLERS` / `AI_ANSWER_CRAWLERS`, block system paths, block
+  everything).
 - `sitemap.xml` (`application/xml`): published routable pages + post rows,
   excluding templates, `noindex` targets, and
   `site.settings.seo.sitemap.excludedTargets`; `<lastmod>` from publish
@@ -143,12 +143,13 @@ publish — the same machinery as the Site toolbar, not a parallel path.
   fields hide behind "Customize X preview" until set; switching targets
   while dirty asks via an in-app dialog. The Schema view pretty-prints the
   exact JSON-LD the publisher will emit.
-- **Robots.txt tab** — three settings cards (crawling toggles: indexing,
-  system-path block, AI training/answer crawlers · custom per-UA Allow/
-  Disallow rule editor · an Advanced raw-directives field) beside a sticky
-  live preview generated by the same `generateRobotsTxt` the endpoint
-  serves, a lint panel (`lintRobotsTxt`), and a "test a URL" checker
-  (`matchRobots`).
+- **Robots.txt tab** — the file is edited directly: an editable CodeMirror
+  surface (`SeoCodeEditor`, saving `seo.robots.content`) is the main column,
+  with an assistant rail on the left — contextual recommendations (block AI
+  crawlers / system paths, "all crawlers blocked" warning) that double as
+  one-click document edits, quick-insert shortcuts, a lint issue list
+  (`lintRobotsTxt`), and a "test a URL" checker (`matchRobots`). No public-
+  origin notices (production always sets `PUBLIC_ORIGINS`).
 - **Sitemap tab** — settings card (enable switch + inclusion counts) and
   per-target include/exclude list beside a sticky entry-format sample
   (noindex targets shown as auto-excluded).
diff --git a/src/__tests__/admin/seoWorkspace.test.tsx b/src/__tests__/admin/seoWorkspace.test.tsx
index e7612949b..d042ec7e0 100644
--- a/src/__tests__/admin/seoWorkspace.test.tsx
+++ b/src/__tests__/admin/seoWorkspace.test.tsx
@@ -356,51 +356,46 @@ describe('SEO Meta tab', () => {
 })
 
 describe('SEO Robots tab', () => {
-  it('updates the generated preview as AI-crawler toggles flip', async () => {
+  it('renders the editable robots.txt seeded with the default template', async () => {
     mockSeoFetch()
     renderWithSession(<RobotsHarness />)
 
-    // Assert on the viewer's data-code mirror, not rendered text: the lazy
-    // CM6 viewer paints only measured-visible lines (none in a test DOM),
-    // so textContent depends on whether the chunk resolved yet.
-    const preview = await screen.findByTestId('seo-robots-preview')
-    expect(preview.getAttribute('data-code')).toContain('User-agent: *')
-    expect(preview.getAttribute('data-code')).toContain('Allow: /')
-    expect(preview.getAttribute('data-code')).not.toContain('GPTBot')
-
-    fireEvent.click(screen.getByTestId('seo-robots-ai-training'))
-    expect(screen.getByTestId('seo-robots-preview').getAttribute('data-code')).toContain('User-agent: GPTBot')
+    // The container mirrors the live content in data-content (the lazy CM6
+    // editor paints only measured-visible lines in a test DOM).
+    const editor = await screen.findByTestId('seo-robots-editor')
+    expect(editor.getAttribute('data-content')).toContain('User-agent: *')
+    expect(editor.getAttribute('data-content')).toContain('Disallow: /admin')
   })
 
-  it('disallows system paths by default and lets you opt out', async () => {
+  it('a quick-insert shortcut edits the document', async () => {
     mockSeoFetch()
     renderWithSession(<RobotsHarness />)
+    await screen.findByTestId('seo-robots-editor')
 
-    const preview = await screen.findByTestId('seo-robots-preview')
-    expect(preview.getAttribute('data-code')).toContain('Disallow: /admin')
-
-    fireEvent.click(screen.getByTestId('seo-robots-system-paths'))
-    expect(screen.getByTestId('seo-robots-preview').getAttribute('data-code')).not.toContain('Disallow: /admin')
+    fireEvent.click(screen.getByTestId('seo-robots-block-ai'))
+    const content = screen.getByTestId('seo-robots-editor').getAttribute('data-content') ?? ''
+    expect(content).toContain('User-agent: GPTBot')
+    expect(content).toContain('User-agent: PerplexityBot')
   })
 
-  it('adds a custom rule and reflects it in the preview', async () => {
+  it('surfaces an AI-crawler recommendation and applies it on click', async () => {
     mockSeoFetch()
     renderWithSession(<RobotsHarness />)
-    await screen.findByTestId('seo-robots-preview')
+    await screen.findByTestId('seo-robots-editor')
 
-    fireEvent.click(screen.getByTestId('seo-robots-add-rule'))
-    fireEvent.change(screen.getByTestId('seo-robots-rule-ua-0'), { target: { value: 'Bingbot' } })
-    fireEvent.change(screen.getByLabelText('Rule 1 disallow paths'), { target: { value: '/no-bing' } })
+    // Default template leaves AI crawlers allowed → the recommendation shows.
+    const rec = await screen.findByTestId('seo-robots-rec-ai-training')
+    fireEvent.click(rec)
 
-    const code = screen.getByTestId('seo-robots-preview').getAttribute('data-code') ?? ''
-    expect(code).toContain('User-agent: Bingbot')
-    expect(code).toContain('Disallow: /no-bing')
+    expect(screen.getByTestId('seo-robots-editor').getAttribute('data-content')).toContain('User-agent: GPTBot')
+    // Applied → recommendation gone.
+    expect(screen.queryByTestId('seo-robots-rec-ai-training')).toBeNull()
   })
 
   it('URL tester reports a blocked system path and an allowed content path', async () => {
     mockSeoFetch()
     renderWithSession(<RobotsHarness />)
-    await screen.findByTestId('seo-robots-preview')
+    await screen.findByTestId('seo-robots-editor')
 
     fireEvent.change(screen.getByTestId('seo-robots-test-ua'), { target: { value: 'Googlebot' } })
     fireEvent.change(screen.getByTestId('seo-robots-test-path'), { target: { value: '/admin/users' } })
diff --git a/src/__tests__/server/seoEndpoints.test.ts b/src/__tests__/server/seoEndpoints.test.ts
index 051222155..73632d955 100644
--- a/src/__tests__/server/seoEndpoints.test.ts
+++ b/src/__tests__/server/seoEndpoints.test.ts
@@ -125,27 +125,18 @@ describe('GET /robots.txt', () => {
     expect(body).not.toContain('<')
   })
 
-  it('emits AI-crawler blocks when groups are disabled', async () => {
-    const db = makeFakeDb(
-      { robots: { allowAiTrainingCrawlers: false, allowAiAnswerCrawlers: false } },
-      [],
-    )
+  it('serves the stored body verbatim and appends the sitemap', async () => {
+    const db = makeFakeDb({ robots: { content: 'User-agent: GPTBot\nDisallow: /' } }, [])
     const body = await (await serveRobotsTxt(db, URL_NO_ORIGIN, REQ)).text()
     expect(body).toContain('User-agent: GPTBot\nDisallow: /')
-    expect(body).toContain('User-agent: PerplexityBot\nDisallow: /')
-  })
-
-  it('disables indexing wholesale when indexingEnabled is false', async () => {
-    const db = makeFakeDb({ robots: { indexingEnabled: false } }, [])
-    const body = await (await serveRobotsTxt(db, URL_NO_ORIGIN, REQ)).text()
-    expect(body).toContain('User-agent: *\nDisallow: /')
+    expect(body).toContain('Sitemap: http://localhost:3001/sitemap.xml')
   })
 
   it('caches per publish version', async () => {
     const db = makeFakeDb(undefined, [])
     const first = await (await serveRobotsTxt(db, URL_NO_ORIGIN, REQ)).text()
     // Same version: served from cache even if settings change underneath.
-    const dbChanged = makeFakeDb({ robots: { indexingEnabled: false } }, [])
+    const dbChanged = makeFakeDb({ robots: { content: 'User-agent: *\nDisallow: /' } }, [])
     const second = await (await serveRobotsTxt(dbChanged, URL_NO_ORIGIN, REQ)).text()
     expect(second).toBe(first)
     // New publish version: regenerated.
diff --git a/src/admin/pages/seo/components/SeoCodeEditor.module.css b/src/admin/pages/seo/components/SeoCodeEditor.module.css
new file mode 100644
index 000000000..a182dde5b
--- /dev/null
+++ b/src/admin/pages/seo/components/SeoCodeEditor.module.css
@@ -0,0 +1,33 @@
+/* Editable card surface, matching SeoCodeViewer. CM6's own editor/gutter
+ * backgrounds are flattened to the card so it reads as one quiet surface. */
+.editor {
+    border-radius: 16px;
+    background: var(--editor-surface-2);
+    padding: 8px 4px;
+    min-height: 360px;
+    max-height: 70vh;
+    overflow-y: auto;
+}
+
+.editor :global(.cm-editor) {
+    background: transparent;
+}
+
+.editor :global(.cm-gutters) {
+    background: transparent;
+    border-right: 1px solid var(--panel-border);
+}
+
+.editor :global(.cm-activeLineGutter) {
+    background: transparent;
+}
+
+/* Pre-CM fallback: a monospace textarea so the surface is usable immediately. */
+.fallback {
+    width: 100%;
+    min-height: 340px;
+    font-family: var(--font-mono);
+    font-size: 12px;
+    line-height: 1.6;
+    resize: vertical;
+}
diff --git a/src/admin/pages/seo/components/SeoCodeEditor.tsx b/src/admin/pages/seo/components/SeoCodeEditor.tsx
new file mode 100644
index 000000000..9c3253eab
--- /dev/null
+++ b/src/admin/pages/seo/components/SeoCodeEditor.tsx
@@ -0,0 +1,66 @@
+/**
+ * SeoCodeEditor — editable sibling of `SeoCodeViewer`. Mounts the shared
+ * CodeMirror 6 editor (lazy, ~150 kB) with a plain `<Textarea>` as the
+ * Suspense fallback so the surface is editable before the chunk resolves and
+ * in test DOMs. The container mirrors the live value in `data-content` so
+ * callers/tests can read it without depending on CM6's measured-line render.
+ *
+ * CM6 reads `value` only on mount / `docKey` change, so programmatic edits
+ * (the Robots tab's insert shortcuts) bump `docKey` to remount with the new
+ * text; plain typing flows back through `onChange` without a remount.
+ */
+import { lazy, Suspense } from 'react'
+import { Textarea } from '@ui/components/Input'
+import type { CodeLanguage } from '@site/code-editor/CodeMirrorEditor'
+import styles from './SeoCodeEditor.module.css'
+
+const CodeMirrorEditor = lazy(() => import('@site/code-editor/CodeMirrorEditor'))
+
+interface SeoCodeEditorProps {
+  /** Remount key — bump to push a programmatic value change into CM6. */
+  docKey: string
+  value: string
+  language: CodeLanguage
+  onChange: (next: string) => void
+  disabled?: boolean
+  ariaLabel: string
+  'data-testid'?: string
+}
+
+export function SeoCodeEditor({
+  docKey,
+  value,
+  language,
+  onChange,
+  disabled = false,
+  ariaLabel,
+  'data-testid': testId,
+}: SeoCodeEditorProps) {
+  return (
+    <div className={styles.editor} data-testid={testId} data-content={value}>
+      {disabled ? (
+        <Textarea className={styles.fallback} value={value} aria-label={ariaLabel} readOnly spellCheck={false} />
+      ) : (
+        <Suspense
+          fallback={
+            <Textarea
+              className={styles.fallback}
+              value={value}
+              aria-label={ariaLabel}
+              spellCheck={false}
+              onChange={(e) => onChange(e.target.value)}
+            />
+          }
+        >
+          <CodeMirrorEditor
+            docKey={docKey}
+            value={value}
+            language={language}
+            changeDelayMs={0}
+            onChange={onChange}
+          />
+        </Suspense>
+      )}
+    </div>
+  )
+}
diff --git a/src/admin/pages/seo/tabs/RobotsTab.tsx b/src/admin/pages/seo/tabs/RobotsTab.tsx
index 319de92ce..8a85a3603 100644
--- a/src/admin/pages/seo/tabs/RobotsTab.tsx
+++ b/src/admin/pages/seo/tabs/RobotsTab.tsx
@@ -1,18 +1,17 @@
 /**
- * RobotsTab — generated robots.txt controls + live preview.
+ * RobotsTab — robots.txt as a directly-edited document.
  *
- * Two-column workbench. Left settings column:
- *   - Crawling card: indexing + AI-crawler toggles + a system-paths default.
- *   - Custom rules card: per-user-agent Allow/Disallow groups.
- *   - Advanced card: raw `extraDirectives` appended verbatim (escape hatch).
- * Right column: the byte-identical CodeMirror preview (same `generateRobotsTxt`
- * the endpoint serves), a lint panel, and a "test a URL" checker.
- *
- * Saving writes `site.settings.seo.robots`; output goes live on publish.
+ * The body IS the artifact: it lives in an editable CodeMirror surface (the
+ * main column) and saves to `site.settings.seo.robots.content`. The left
+ * rail is an assistant, not a parallel form — it explains the file, surfaces
+ * contextual recommendations + lint, and offers one-click inserts that edit
+ * the document (block AI crawlers, block system paths, reset, …). The server
+ * appends the `Sitemap:` line and enforces preview-host protection; the
+ * author never hand-manages the production origin.
  */
 import { useState } from 'react'
-import { Input, Textarea } from '@ui/components/Input'
 import { Button } from '@ui/components/Button'
+import { Input } from '@ui/components/Input'
 import { cn } from '@ui/cn'
 import { getErrorMessage } from '@core/utils/errorMessage'
 import { publishCmsDraft } from '@core/persistence'
@@ -20,16 +19,16 @@ import { hasCapability } from '@admin/access'
 import { useCurrentAdminUser } from '@admin/sessionContext'
 import { StepUpCancelledMessage, useStepUp } from '@admin/shared/StepUp'
 import {
-  generateRobotsTxt,
   lintRobotsTxt,
   matchRobots,
+  generateRobotsTxt,
   AI_TRAINING_CRAWLERS,
   AI_ANSWER_CRAWLERS,
+  SYSTEM_DISALLOW_PATHS,
+  DEFAULT_ROBOTS_TEMPLATE,
   type SeoRobotsSettings,
-  type SeoRobotsRule,
 } from '@core/seo'
-import { SeoCodeViewer } from '../components/SeoCodeViewer'
-import { SeoSwitchRow } from '../components/SeoFormRow'
+import { SeoCodeEditor } from '../components/SeoCodeEditor'
 import type { SeoWorkspace } from '../hooks/useSeoWorkspace'
 import type { SeoSaveBridge } from '../hooks/useSeoSaveBridge'
 import { useSeoSaveSurface } from '../hooks/useSeoSaveBridge'
@@ -41,112 +40,76 @@ interface RobotsTabProps {
   bridge: SeoSaveBridge
 }
 
-/**
- * Rules are edited as raw multi-line text (one path per line) so typing a
- * newline never gets stripped mid-edit; they compile to `string[]` only when
- * building the settings object.
- */
-interface RuleDraft {
-  userAgent: string
-  allowText: string
-  disallowText: string
-}
-
 type SaveState = 'idle' | 'saving' | 'saved' | 'publishing' | 'published' | 'error'
 
-function parseLines(text: string): string[] {
-  return text.split('\n').map((line) => line.trim()).filter((line) => line !== '')
+function escapeRegExp(value: string): string {
+  return value.replace(/[.+?^${}()|[\]\\*]/g, '\\$&')
 }
 
-function rulesToDrafts(rules: SeoRobotsRule[] | undefined): RuleDraft[] {
-  return (rules ?? []).map((rule) => ({
-    userAgent: rule.userAgent,
-    allowText: (rule.allow ?? []).join('\n'),
-    disallowText: (rule.disallow ?? []).join('\n'),
-  }))
-}
-
-/** Toggles draft + rule drafts → the persisted/previewed settings object. */
-function compileRobots(toggles: SeoRobotsSettings, rules: RuleDraft[]): SeoRobotsSettings {
-  const compiled: SeoRobotsRule[] = rules
-    .map((rule) => {
-      const out: SeoRobotsRule = { userAgent: rule.userAgent.trim() }
-      const allow = parseLines(rule.allowText)
-      const disallow = parseLines(rule.disallowText)
-      if (allow.length > 0) out.allow = allow
-      if (disallow.length > 0) out.disallow = disallow
-      return out
-    })
-    .filter((rule) => rule.userAgent !== '')
-
-  const next: SeoRobotsSettings = { ...toggles }
-  const extra = (toggles.extraDirectives ?? '').trim()
-  if (extra === '') delete next.extraDirectives
-  else next.extraDirectives = extra
-  if (compiled.length > 0) next.rules = compiled
-  else delete next.rules
-  return next
+/** Append `User-agent: <bot>\nDisallow: /` blocks for bots not already present. */
+function appendBotBlocks(text: string, bots: readonly string[]): string {
+  const missing = bots.filter(
+    (bot) => !new RegExp(`^user-agent:\\s*${escapeRegExp(bot)}\\s*$`, 'im').test(text),
+  )
+  if (missing.length === 0) return text
+  const block = missing.map((bot) => `User-agent: ${bot}\nDisallow: /`).join('\n\n')
+  return text.trim() === '' ? block : `${text.trimEnd()}\n\n${block}`
 }
 
-/** Canonical signature for dirty comparison — fills defaults, fixes key order. */
-function robotsSignature(settings: SeoRobotsSettings): string {
-  return JSON.stringify({
-    indexingEnabled: settings.indexingEnabled ?? true,
-    allowAiTrainingCrawlers: settings.allowAiTrainingCrawlers ?? true,
-    allowAiAnswerCrawlers: settings.allowAiAnswerCrawlers ?? true,
-    disallowSystemPaths: settings.disallowSystemPaths ?? true,
-    extraDirectives: (settings.extraDirectives ?? '').trim(),
-    rules: (settings.rules ?? []).map((rule) => ({
-      userAgent: rule.userAgent,
-      allow: rule.allow ?? [],
-      disallow: rule.disallow ?? [],
-    })),
-  })
+/** Add `Disallow:` lines into the `User-agent: *` group (creating it if absent). */
+function addStarDisallows(text: string, paths: readonly string[]): string {
+  const additions = paths.map((path) => `Disallow: ${path}`)
+  const lines = text.split('\n')
+  const missing = additions.filter(
+    (line) => !lines.some((existing) => existing.trim().toLowerCase() === line.toLowerCase()),
+  )
+  if (missing.length === 0) return text
+  const starIndex = lines.findIndex((line) => /^user-agent:\s*\*\s*$/i.test(line.trim()))
+  if (starIndex === -1) {
+    const block = ['User-agent: *', ...missing].join('\n')
+    return text.trim() === '' ? block : `${text.trimEnd()}\n\n${block}`
+  }
+  lines.splice(starIndex + 1, 0, ...missing)
+  return lines.join('\n')
 }
 
 export function RobotsTab({ workspace, canManage, bridge }: RobotsTabProps) {
   const stored = workspace.siteSeo?.robots ?? {}
-  // Toggles + extra directives live in `draft`; rule path-lists live in
-  // `rules` as raw text (see RuleDraft).
-  const [draft, setDraft] = useState<SeoRobotsSettings>(() => {
-    const { rules: _rules, ...rest } = stored
-    return rest
-  })
-  const [rules, setRules] = useState<RuleDraft[]>(() => rulesToDrafts(stored.rules))
+  const baseline = stored.content ?? DEFAULT_ROBOTS_TEMPLATE
+
+  const [content, setContent] = useState<string>(baseline)
+  // Bumped only on programmatic edits (shortcuts) to remount CM6 with the new
+  // text; plain typing flows through onChange without a remount.
+  const [editorRev, setEditorRev] = useState(0)
   const [saveState, setSaveState] = useState<SaveState>('idle')
   const [saveError, setSaveError] = useState<string | null>(null)
   const currentUser = useCurrentAdminUser()
   const { runStepUp } = useStepUp()
   const canPublish = !currentUser || hasCapability(currentUser, 'pages.publish')
 
-  const effective = compileRobots(draft, rules)
-  const indexingOff = draft.indexingEnabled === false
-  const isDirty = robotsSignature(effective) !== robotsSignature(stored)
+  const isDirty = content !== baseline
+  const lint = lintRobotsTxt(content)
 
-  const preview = generateRobotsTxt({
-    robots: effective,
-    sitemapEnabled: workspace.siteSeo?.sitemap?.enabled !== false,
-    origin: workspace.publicOrigin ?? undefined,
-  })
-  const lint = lintRobotsTxt(preview)
+  // Contextual recommendations — each is also the shortcut that resolves it.
+  const allBlocked = !matchRobots(content, 'Googlebot', '/').allowed
+  const adminExposed = matchRobots(content, 'Googlebot', '/admin').allowed
+  const trainingOpen = AI_TRAINING_CRAWLERS.some((bot) => matchRobots(content, bot, '/').allowed)
+  const answerOpen = AI_ANSWER_CRAWLERS.some((bot) => matchRobots(content, bot, '/').allowed)
 
   function touch(): void {
     if (saveState !== 'idle') setSaveState('idle')
   }
-  function setFlag(flag: keyof SeoRobotsSettings, value: boolean): void {
-    setDraft((current) => ({ ...current, [flag]: value }))
-    touch()
-  }
-  function addRule(): void {
-    setRules((current) => [...current, { userAgent: '', allowText: '', disallowText: '' }])
-    touch()
-  }
-  function updateRule(index: number, patch: Partial<RuleDraft>): void {
-    setRules((current) => current.map((rule, i) => (i === index ? { ...rule, ...patch } : rule)))
+
+  /** Plain typing from the editor — no remount. */
+  function handleEdit(next: string): void {
+    setContent(next)
     touch()
   }
-  function removeRule(index: number): void {
-    setRules((current) => current.filter((_, i) => i !== index))
+
+  /** Programmatic edit from a shortcut — remount CM6 to show the new text. */
+  function applyEdit(transform: (prev: string) => string): void {
+    setContent((prev) => transform(prev))
+    setEditorRev((rev) => rev + 1)
     touch()
   }
 
@@ -154,7 +117,8 @@ export function RobotsTab({ workspace, canManage, bridge }: RobotsTabProps) {
     setSaveState('saving')
     setSaveError(null)
     try {
-      await workspace.saveSite({ ...(workspace.siteSeo ?? {}), robots: effective })
+      const robots: SeoRobotsSettings = content.trim() === '' ? {} : { content }
+      await workspace.saveSite({ ...(workspace.siteSeo ?? {}), robots })
       setSaveState('saved')
       return true
     } catch (err) {
@@ -196,180 +160,149 @@ export function RobotsTab({ workspace, canManage, bridge }: RobotsTabProps) {
     { save: () => void handleSave(), publish: () => void handlePublish() },
   )
 
+  const recommendations: { id: string; tone: 'warning' | 'info'; text: string; action: string; onApply: () => void }[] = []
+  if (allBlocked) {
+    recommendations.push({
+      id: 'all-blocked',
+      tone: 'warning',
+      text: 'Every crawler is blocked — your site will not appear in search results.',
+      action: 'Allow crawlers',
+      onApply: () => applyEdit(() => 'User-agent: *\nAllow: /'),
+    })
+  } else {
+    if (adminExposed) {
+      recommendations.push({
+        id: 'admin',
+        tone: 'info',
+        text: 'Admin and internal routes are crawlable. Block them so they stay out of search.',
+        action: 'Block system paths',
+        onApply: () => applyEdit((prev) => addStarDisallows(prev, SYSTEM_DISALLOW_PATHS)),
+      })
+    }
+    if (trainingOpen) {
+      recommendations.push({
+        id: 'ai-training',
+        tone: 'info',
+        text: 'AI training crawlers can ingest your content for model training.',
+        action: 'Block AI training crawlers',
+        onApply: () => applyEdit((prev) => appendBotBlocks(prev, AI_TRAINING_CRAWLERS)),
+      })
+    }
+    if (answerOpen) {
+      recommendations.push({
+        id: 'ai-answer',
+        tone: 'info',
+        text: 'AI answer engines fetch your pages to ground live answers.',
+        action: 'Block AI answer crawlers',
+        onApply: () => applyEdit((prev) => appendBotBlocks(prev, AI_ANSWER_CRAWLERS)),
+      })
+    }
+  }
+
   return (
     <section className={styles.tab} aria-label="Robots.txt settings">
-      <div className={styles.workbench}>
-        <div className={styles.settingsColumn}>
-          {saveError && <p className={styles.error} role="alert">{saveError}</p>}
-          {!workspace.publicOrigin && (
-            <p className={styles.notice} role="status">
-              No public origin configured — set the <code>PUBLIC_ORIGINS</code> environment
-              variable so the sitemap link (and canonical URLs) use your real domain.
-            </p>
-          )}
-
+      <div className={styles.editorWorkbench}>
+        <aside className={styles.assistColumn} aria-label="robots.txt help">
           <div className={styles.card}>
             <header className={styles.cardHeader}>
               <h2 className={styles.heading}>Robots.txt</h2>
               <p className={styles.subheading}>
-                Generated automatically and served at <code>/robots.txt</code>. Changes go live on the next publish.
-              </p>
-            </header>
-
-            <SeoSwitchRow
-              id="seo-robots-indexing-switch"
-              label="Search indexing"
-              hint="Turning this off serves a global Disallow — the whole site disappears from search."
-              checked={!indexingOff}
-              disabled={!canManage}
-              onCheckedChange={(value) => setFlag('indexingEnabled', value)}
-              data-testid="seo-robots-indexing"
-            />
-            <SeoSwitchRow
-              id="seo-robots-system-paths-switch"
-              label="Block system paths"
-              hint="Adds default Disallow rules for /admin and internal /_instatic/ routes."
-              checked={draft.disallowSystemPaths !== false}
-              disabled={!canManage || indexingOff}
-              onCheckedChange={(value) => setFlag('disallowSystemPaths', value)}
-              data-testid="seo-robots-system-paths"
-            />
-            <SeoSwitchRow
-              id="seo-robots-ai-training-switch"
-              label="AI training crawlers"
-              hint={`Bots that ingest content for model training: ${AI_TRAINING_CRAWLERS.join(', ')}.`}
-              checked={draft.allowAiTrainingCrawlers !== false}
-              disabled={!canManage || indexingOff}
-              onCheckedChange={(value) => setFlag('allowAiTrainingCrawlers', value)}
-              data-testid="seo-robots-ai-training"
-            />
-            <SeoSwitchRow
-              id="seo-robots-ai-answer-switch"
-              label="AI answer crawlers"
-              hint={`Bots that fetch content to ground live AI answers: ${AI_ANSWER_CRAWLERS.join(', ')}. Blocking these removes the site from AI search results.`}
-              checked={draft.allowAiAnswerCrawlers !== false}
-              disabled={!canManage || indexingOff}
-              onCheckedChange={(value) => setFlag('allowAiAnswerCrawlers', value)}
-              data-testid="seo-robots-ai-answer"
-            />
-          </div>
-
-          <div className={styles.card}>
-            <header className={styles.cardHeader}>
-              <h2 className={styles.heading}>Custom rules</h2>
-              <p className={styles.subheading}>
-                Per-crawler Allow / Disallow paths — one path per line. Groups for the same
-                user-agent merge with the built-in ones above.
+                Edit the file directly — it is served at <code>/robots.txt</code> and goes live on
+                publish. The <code>Sitemap:</code> line is added automatically.
               </p>
             </header>
 
-            {rules.map((rule, index) => (
-              <div key={index} className={styles.ruleCard}>
-                <div className={styles.ruleHead}>
-                  <Input
-                    type="text"
-                    value={rule.userAgent}
-                    placeholder="User-agent — e.g. Googlebot or *"
-                    disabled={!canManage}
-                    aria-label={`Rule ${index + 1} user-agent`}
-                    onChange={(e) => updateRule(index, { userAgent: e.target.value })}
-                    data-testid={`seo-robots-rule-ua-${index}`}
-                  />
-                  <Button
-                    variant="ghost"
-                    size="sm"
-                    disabled={!canManage}
-                    onClick={() => removeRule(index)}
-                    aria-label={`Remove rule ${index + 1}`}
-                    data-testid={`seo-robots-rule-remove-${index}`}
-                  >
-                    Remove
-                  </Button>
-                </div>
-                <div className={styles.ruleGrid}>
-                  <label className={styles.ruleField}>
-                    <span className={styles.ruleLabel}>Disallow</span>
-                    <Textarea
-                      rows={2}
-                      value={rule.disallowText}
-                      placeholder={'/private\n/search'}
+            <div className={styles.assistGroup}>
+              <h3 className={styles.assistLabel}>Recommendations</h3>
+              {recommendations.length === 0 ? (
+                <p className={styles.assistOk} role="status">No recommendations — this looks healthy.</p>
+              ) : (
+                recommendations.map((rec) => (
+                  <div key={rec.id} className={cn(styles.recCard, styles[`rec_${rec.tone}`])}>
+                    <p className={styles.recText}>{rec.text}</p>
+                    <Button
+                      variant="secondary"
+                      size="xs"
                       disabled={!canManage}
-                      aria-label={`Rule ${index + 1} disallow paths`}
-                      onChange={(e) => updateRule(index, { disallowText: e.target.value })}
-                    />
-                  </label>
-                  <label className={styles.ruleField}>
-                    <span className={styles.ruleLabel}>Allow</span>
-                    <Textarea
-                      rows={2}
-                      value={rule.allowText}
-                      placeholder={'/public'}
-                      disabled={!canManage}
-                      aria-label={`Rule ${index + 1} allow paths`}
-                      onChange={(e) => updateRule(index, { allowText: e.target.value })}
-                    />
-                  </label>
-                </div>
+                      onClick={rec.onApply}
+                      data-testid={`seo-robots-rec-${rec.id}`}
+                    >
+                      {rec.action}
+                    </Button>
+                  </div>
+                ))
+              )}
+            </div>
+
+            <div className={styles.assistGroup}>
+              <h3 className={styles.assistLabel}>Quick inserts</h3>
+              <div className={styles.shortcutRow}>
+                <Button variant="ghost" size="xs" disabled={!canManage}
+                  onClick={() => applyEdit(() => DEFAULT_ROBOTS_TEMPLATE)} data-testid="seo-robots-reset">
+                  Recommended defaults
+                </Button>
+                <Button variant="ghost" size="xs" disabled={!canManage}
+                  onClick={() => applyEdit((prev) => appendBotBlocks(prev, [...AI_TRAINING_CRAWLERS, ...AI_ANSWER_CRAWLERS]))}
+                  data-testid="seo-robots-block-ai">
+                  Block all AI crawlers
+                </Button>
+                <Button variant="ghost" size="xs" disabled={!canManage}
+                  onClick={() => applyEdit(() => 'User-agent: *\nDisallow: /')} data-testid="seo-robots-block-all">
+                  Block everything
+                </Button>
               </div>
-            ))}
+            </div>
 
-            <Button
-              variant="secondary"
-              size="sm"
-              disabled={!canManage}
-              onClick={addRule}
-              data-testid="seo-robots-add-rule"
-            >
-              Add rule
-            </Button>
-          </div>
+            {lint.length > 0 && (
+              <div className={styles.assistGroup}>
+                <h3 className={styles.assistLabel}>Issues</h3>
+                <ul className={styles.lintList} aria-label="robots.txt warnings">
+                  {lint.map((finding, i) => (
+                    <li key={i} className={cn(styles.lintItem, styles[`lint_${finding.level}`])}>
+                      <span className={styles.lintLine}>Line {finding.line}</span>
+                      {finding.message}
+                    </li>
+                  ))}
+                </ul>
+              </div>
+            )}
 
-          <div className={styles.card}>
-            <header className={styles.cardHeader}>
-              <h2 className={styles.heading}>Advanced</h2>
-              <p className={styles.subheading}>
-                Extra directives appended verbatim — for one-offs like <code>Clean-param</code> or
-                <code> Host</code>. Linted, never dropped.
-              </p>
-            </header>
-            <Textarea
-              rows={4}
-              value={draft.extraDirectives ?? ''}
-              placeholder={'Clean-param: ref /\nHost: example.com'}
-              disabled={!canManage}
-              aria-label="Extra robots.txt directives"
-              onChange={(e) => {
-                setDraft((current) => ({ ...current, extraDirectives: e.target.value }))
-                touch()
-              }}
-              data-testid="seo-robots-extra"
-            />
+            <div className={styles.assistGroup}>
+              <h3 className={styles.assistLabel}>Test a URL</h3>
+              <RobotsUrlTester
+                robotsText={generateRobotsTxt({
+                  robots: { content },
+                  sitemapEnabled: workspace.siteSeo?.sitemap?.enabled !== false,
+                  origin: workspace.publicOrigin ?? undefined,
+                })}
+              />
+            </div>
           </div>
-        </div>
-
-        <aside className={styles.previewColumn} aria-label="robots.txt preview">
-          <h3 className={styles.previewHeading}>Preview</h3>
-          <SeoCodeViewer docKey="robots-preview" value={preview} language="text" data-testid="seo-robots-preview" />
+        </aside>
 
-          {lint.length > 0 && (
-            <ul className={styles.lintList} aria-label="robots.txt warnings">
-              {lint.map((finding, i) => (
-                <li key={i} className={cn(styles.lintItem, styles[`lint_${finding.level}`])}>
-                  <span className={styles.lintLine}>Line {finding.line}</span>
-                  {finding.message}
-                </li>
-              ))}
-            </ul>
+        <div className={styles.editorMain}>
+          {saveError && <p className={styles.error} role="alert">{saveError}</p>}
+          <SeoCodeEditor
+            docKey={`robots:${editorRev}`}
+            value={content}
+            language="text"
+            disabled={!canManage}
+            ariaLabel="robots.txt content"
+            onChange={handleEdit}
+            data-testid="seo-robots-editor"
+          />
+          {workspace.publicOrigin && (
+            <p className={styles.servedNote} role="status">
+              Served at <code>{workspace.publicOrigin}/robots.txt</code> · sitemap linked automatically.
+            </p>
           )}
-
-          <RobotsUrlTester robotsText={preview} />
-        </aside>
+        </div>
       </div>
     </section>
   )
 }
 
-/** Live "is this URL crawlable?" checker against the previewed file. */
+/** Live "is this URL crawlable?" checker against the served file. */
 function RobotsUrlTester({ robotsText }: { robotsText: string }) {
   const [userAgent, setUserAgent] = useState('Googlebot')
   const [path, setPath] = useState('/')
@@ -377,7 +310,6 @@ function RobotsUrlTester({ robotsText }: { robotsText: string }) {
 
   return (
     <div className={styles.tester}>
-      <h3 className={styles.previewHeading}>Test a URL</h3>
       <div className={styles.testerRow}>
         <Input
           type="text"
diff --git a/src/admin/pages/seo/tabs/SettingsTabs.module.css b/src/admin/pages/seo/tabs/SettingsTabs.module.css
index 64bda5878..cf50ced54 100644
--- a/src/admin/pages/seo/tabs/SettingsTabs.module.css
+++ b/src/admin/pages/seo/tabs/SettingsTabs.module.css
@@ -73,15 +73,6 @@
     color: var(--editor-danger-text);
 }
 
-.notice {
-    margin: 0;
-    padding: 10px 12px;
-    border-radius: var(--editor-radius);
-    background: var(--editor-surface-3);
-    font-size: 12px;
-    color: var(--editor-warning-text);
-}
-
 .previewHeading {
     margin: 0;
     font-size: 13px;
@@ -133,50 +124,90 @@
     color: var(--editor-warning-text);
 }
 
-/* ── Custom rules editor ─────────────────────────────────────────────────── */
-.ruleCard {
+/* ── Robots editor workbench: assistant rail (left) + editor (main) ──────── */
+.editorWorkbench {
+    display: grid;
+    grid-template-columns: minmax(300px, 360px) minmax(0, 1fr);
+    gap: 24px;
+    align-items: start;
+}
+
+@media (max-width: 1000px) {
+    .editorWorkbench {
+        grid-template-columns: 1fr;
+    }
+}
+
+.assistColumn {
+    position: sticky;
+    top: 0;
+    align-self: start;
+    min-width: 0;
+}
+
+.editorMain {
     display: flex;
     flex-direction: column;
-    gap: 10px;
-    padding: 14px;
-    border-radius: var(--panel-radius);
-    background: var(--editor-surface-3);
+    gap: 8px;
+    min-width: 0;
 }
 
-.ruleHead {
+.assistGroup {
     display: flex;
-    align-items: center;
+    flex-direction: column;
     gap: 8px;
 }
 
-.ruleHead > :first-child {
-    flex: 1;
-    min-width: 0;
+.assistLabel {
+    margin: 0;
+    font-size: 10px;
+    font-weight: 620;
+    letter-spacing: 0.08em;
+    text-transform: uppercase;
+    color: var(--editor-text-secondary);
 }
 
-.ruleGrid {
-    display: grid;
-    grid-template-columns: 1fr 1fr;
-    gap: 10px;
+.assistOk {
+    margin: 0;
+    font-size: 12px;
+    color: var(--editor-text-muted);
 }
 
-.ruleField {
+.recCard {
     display: flex;
     flex-direction: column;
-    gap: 4px;
-    min-width: 0;
+    align-items: flex-start;
+    gap: 8px;
+    padding: 12px;
+    border-radius: var(--panel-radius);
+    background: var(--editor-surface-3);
 }
 
-.ruleLabel {
-    font-size: 11px;
-    font-weight: 600;
-    color: var(--editor-text-muted);
+.recText {
+    margin: 0;
+    font-size: 12px;
+    line-height: 1.45;
+    color: var(--editor-text);
 }
 
-@media (max-width: 560px) {
-    .ruleGrid {
-        grid-template-columns: 1fr;
-    }
+.rec_warning {
+    box-shadow: inset 2px 0 0 var(--editor-warning);
+}
+
+.rec_info {
+    box-shadow: inset 2px 0 0 var(--editor-info-text);
+}
+
+.shortcutRow {
+    display: flex;
+    flex-wrap: wrap;
+    gap: 6px;
+}
+
+.servedNote {
+    margin: 0;
+    font-size: 11px;
+    color: var(--editor-text-muted);
 }
 
 /* ── Lint panel ──────────────────────────────────────────────────────────── */
@@ -197,7 +228,7 @@
     gap: 8px;
     padding: 8px 12px;
     font-size: 12px;
-    background: var(--editor-surface-2);
+    background: var(--editor-surface-3);
 }
 
 .lintLine {
@@ -233,7 +264,7 @@
     padding: 8px 12px;
     border-radius: var(--editor-radius);
     font-size: 12px;
-    background: var(--editor-surface-2);
+    background: var(--editor-surface-3);
 }
 
 .testerAllowed {
diff --git a/src/admin/pages/seo/tabs/SitemapTab.tsx b/src/admin/pages/seo/tabs/SitemapTab.tsx
index 6519c6d65..a067e6fd7 100644
--- a/src/admin/pages/seo/tabs/SitemapTab.tsx
+++ b/src/admin/pages/seo/tabs/SitemapTab.tsx
@@ -114,12 +114,6 @@ export function SitemapTab({ workspace, canManage, bridge }: SitemapTabProps) {
       <div className={styles.workbench}>
         <div className={styles.settingsColumn}>
           {saveError && <p className={styles.error} role="alert">{saveError}</p>}
-          {!workspace.publicOrigin && (
-            <p className={styles.notice} role="status">
-              No public origin configured — set the <code>PUBLIC_ORIGINS</code> environment
-              variable so sitemap URLs use your real domain.
-            </p>
-          )}
 
           <div className={styles.card}>
             <header className={styles.cardHeader}>
diff --git a/src/core/seo/__tests__/robots.test.ts b/src/core/seo/__tests__/robots.test.ts
index e12f0e7ff..ee7f816cd 100644
--- a/src/core/seo/__tests__/robots.test.ts
+++ b/src/core/seo/__tests__/robots.test.ts
@@ -1,20 +1,17 @@
 import { describe, expect, test } from 'bun:test'
-import { generateRobotsTxt, SYSTEM_DISALLOW_PATHS } from '../robots'
-import { AI_ANSWER_CRAWLERS, AI_TRAINING_CRAWLERS } from '../aiCrawlers'
+import { generateRobotsTxt, DEFAULT_ROBOTS_TEMPLATE, SYSTEM_DISALLOW_PATHS } from '../robots'
 
 describe('generateRobotsTxt', () => {
-  test('default output allows everything, disallows system paths, links the sitemap', () => {
+  test('falls back to the default template and links the sitemap', () => {
     const out = generateRobotsTxt({ sitemapEnabled: true, origin: 'https://acme.com' })
-    expect(out).toBe(
-      'User-agent: *\nAllow: /\nDisallow: /admin\nDisallow: /_instatic/\n\n' +
-        'Sitemap: https://acme.com/sitemap.xml\n',
-    )
+    expect(out).toBe(`${DEFAULT_ROBOTS_TEMPLATE}\n\nSitemap: https://acme.com/sitemap.xml\n`)
+    for (const path of SYSTEM_DISALLOW_PATHS) expect(out).toContain(`Disallow: ${path}`)
   })
 
-  test('system-path defaults can be opted out', () => {
-    const out = generateRobotsTxt({ robots: { disallowSystemPaths: false }, sitemapEnabled: false })
-    expect(out).toBe('User-agent: *\nAllow: /\n')
-    for (const path of SYSTEM_DISALLOW_PATHS) expect(out).not.toContain(`Disallow: ${path}`)
+  test('serves the stored content verbatim', () => {
+    const content = 'User-agent: Googlebot\nDisallow: /private'
+    const out = generateRobotsTxt({ robots: { content }, sitemapEnabled: false })
+    expect(out).toBe(`${content}\n`)
   })
 
   test('omits the sitemap line without an origin or when disabled', () => {
@@ -22,20 +19,16 @@ describe('generateRobotsTxt', () => {
     expect(generateRobotsTxt({ sitemapEnabled: false, origin: 'https://a.com' })).not.toContain('Sitemap:')
   })
 
-  test('indexing disabled produces a global Disallow', () => {
-    const out = generateRobotsTxt({
-      robots: { indexingEnabled: false },
-      sitemapEnabled: true,
-      origin: 'https://acme.com',
-    })
-    expect(out).toContain('User-agent: *\nDisallow: /')
-    expect(out).not.toContain('Allow: /')
-    expect(out).not.toContain('Disallow: /admin') // blanket block, not the system list
+  test('does not append a sitemap line when the body already has one', () => {
+    const content = 'User-agent: *\nAllow: /\nSitemap: https://acme.com/custom-sitemap.xml'
+    const out = generateRobotsTxt({ robots: { content }, sitemapEnabled: true, origin: 'https://acme.com' })
+    expect(out.match(/Sitemap:/g)).toHaveLength(1)
+    expect(out).toContain('custom-sitemap.xml')
   })
 
-  test('blockAll serves a bare Disallow with no sitemap or extras', () => {
+  test('blockAll serves a bare Disallow with no sitemap', () => {
     const out = generateRobotsTxt({
-      robots: { extraDirectives: 'Host: example.com', rules: [{ userAgent: 'Googlebot', disallow: ['/x'] }] },
+      robots: { content: 'User-agent: *\nAllow: /' },
       sitemapEnabled: true,
       origin: 'https://acme.com',
       blockAll: true,
@@ -43,60 +36,9 @@ describe('generateRobotsTxt', () => {
     expect(out).toBe('User-agent: *\nDisallow: /\n')
   })
 
-  test('blocking AI training crawlers emits one block per bot', () => {
-    const out = generateRobotsTxt({ robots: { allowAiTrainingCrawlers: false }, sitemapEnabled: false })
-    for (const bot of AI_TRAINING_CRAWLERS) expect(out).toContain(`User-agent: ${bot}\nDisallow: /`)
-    for (const bot of AI_ANSWER_CRAWLERS) expect(out).not.toContain(`User-agent: ${bot}`)
-  })
-
-  test('blocking AI answer crawlers emits one block per bot', () => {
-    const out = generateRobotsTxt({ robots: { allowAiAnswerCrawlers: false }, sitemapEnabled: false })
-    for (const bot of AI_ANSWER_CRAWLERS) expect(out).toContain(`User-agent: ${bot}\nDisallow: /`)
-    expect(out).toContain('User-agent: *\nAllow: /')
-  })
-
-  test('custom rules render as their own user-agent groups', () => {
-    const out = generateRobotsTxt({
-      robots: {
-        disallowSystemPaths: false,
-        rules: [{ userAgent: 'Googlebot', allow: ['/public'], disallow: ['/private', '/tmp'] }],
-      },
-      sitemapEnabled: false,
-    })
-    expect(out).toContain('User-agent: Googlebot\nAllow: /public\nDisallow: /private\nDisallow: /tmp')
-  })
-
-  test('a custom `*` rule merges into the wildcard group (no duplicate header)', () => {
-    const out = generateRobotsTxt({
-      robots: { disallowSystemPaths: false, rules: [{ userAgent: '*', disallow: ['/search'] }] },
-      sitemapEnabled: false,
-    })
-    expect(out).toBe('User-agent: *\nAllow: /\nDisallow: /search\n')
-    expect(out.match(/User-agent: \*/g)?.length).toBe(1)
-  })
-
-  test('a custom rule for a toggled-off AI bot merges into one block', () => {
-    const out = generateRobotsTxt({
-      robots: {
-        disallowSystemPaths: false,
-        allowAiTrainingCrawlers: false,
-        rules: [{ userAgent: 'GPTBot', disallow: ['/secret'] }],
-      },
-      sitemapEnabled: false,
-    })
-    expect(out.match(/User-agent: GPTBot/g)?.length).toBe(1)
-    expect(out).toContain('User-agent: GPTBot\nDisallow: /\nDisallow: /secret')
-  })
-
-  test('extra directives append verbatim before the sitemap line', () => {
-    const out = generateRobotsTxt({
-      robots: { disallowSystemPaths: false, extraDirectives: 'Clean-param: ref /\nHost: acme.com' },
-      sitemapEnabled: true,
-      origin: 'https://acme.com',
-    })
-    expect(out).toBe(
-      'User-agent: *\nAllow: /\n\nClean-param: ref /\nHost: acme.com\n\n' +
-        'Sitemap: https://acme.com/sitemap.xml\n',
+  test('empty/whitespace content falls back to the default template', () => {
+    expect(generateRobotsTxt({ robots: { content: '   \n  ' }, sitemapEnabled: false })).toBe(
+      `${DEFAULT_ROBOTS_TEMPLATE}\n`,
     )
   })
 })
diff --git a/src/core/seo/__tests__/robotsAnalysis.test.ts b/src/core/seo/__tests__/robotsAnalysis.test.ts
index 9cca65cd3..379392494 100644
--- a/src/core/seo/__tests__/robotsAnalysis.test.ts
+++ b/src/core/seo/__tests__/robotsAnalysis.test.ts
@@ -32,13 +32,19 @@ describe('lintRobotsTxt', () => {
 })
 
 describe('matchRobots', () => {
-  const robots = generateRobotsTxt({
-    robots: {
-      rules: [{ userAgent: 'Googlebot', allow: ['/admin/public'], disallow: ['/private'] }],
-    },
-    sitemapEnabled: true,
-    origin: 'https://acme.com',
-  })
+  // The * group blocks /admin; Googlebot has its own group that allows
+  // /admin/public and disallows /private.
+  const robots = [
+    'User-agent: *',
+    'Allow: /',
+    'Disallow: /admin',
+    '',
+    'User-agent: Googlebot',
+    'Allow: /admin/public',
+    'Disallow: /private',
+    '',
+    'Sitemap: https://acme.com/sitemap.xml',
+  ].join('\n')
 
   test('default content path is allowed for everyone', () => {
     expect(matchRobots(robots, 'SomeBot', '/about').allowed).toBe(true)
diff --git a/src/core/seo/index.ts b/src/core/seo/index.ts
index 4ba549c77..5e98088d3 100644
--- a/src/core/seo/index.ts
+++ b/src/core/seo/index.ts
@@ -13,7 +13,6 @@ export {
   SiteSeoSettingsSchema,
   SeoOrganizationSchema,
   SeoRobotsSettingsSchema,
-  SeoRobotsRuleSchema,
   SeoSitemapSettingsSchema,
   OgTypeSchema,
   XCardTypeSchema,
@@ -23,7 +22,6 @@ export {
   type SiteSeoSettings,
   type SeoOrganization,
   type SeoRobotsSettings,
-  type SeoRobotsRule,
   type SeoSitemapSettings,
   type OgType,
   type XCardType,
@@ -46,7 +44,12 @@ export {
 
 export { AI_TRAINING_CRAWLERS, AI_ANSWER_CRAWLERS } from './aiCrawlers'
 
-export { generateRobotsTxt, SYSTEM_DISALLOW_PATHS, type GenerateRobotsTxtInput } from './robots'
+export {
+  generateRobotsTxt,
+  SYSTEM_DISALLOW_PATHS,
+  DEFAULT_ROBOTS_TEMPLATE,
+  type GenerateRobotsTxtInput,
+} from './robots'
 
 export {
   lintRobotsTxt,
diff --git a/src/core/seo/robots.ts b/src/core/seo/robots.ts
index 87e2bdb04..a3d19335b 100644
--- a/src/core/seo/robots.ts
+++ b/src/core/seo/robots.ts
@@ -1,20 +1,33 @@
 /**
- * robots.txt generation — pure function from robots settings + context to
- * the served `text/plain` body. Used by the server endpoint
- * (`server/publish/seoEndpoints.ts`) and the admin Robots.txt tab's live
- * preview, so what the tab shows is byte-identical to what crawlers get.
+ * robots.txt generation — pure function from the stored body + context to the
+ * served `text/plain` file. The body is authored directly in the admin
+ * Robots tab's editor (`SeoRobotsSettings.content`); this module only adds
+ * the bits the author shouldn't have to manage by hand:
  *
- * Composition model: every directive resolves into one user-agent group
- * (`User-agent: <ua>` + its Allow/Disallow lines). System-path defaults, the
- * AI-crawler toggles, and custom rules all merge into the same group when
- * they target the same agent, so the output never repeats a `User-agent:`
- * header. Order: the `*` group first, then the rest in first-seen order.
- * Raw `extraDirectives` append verbatim; the `Sitemap:` line is always last.
+ *   - a sensible default body when nothing is stored yet,
+ *   - the origin-resolved `Sitemap:` line (unless the body already has one),
+ *   - the `blockAll` short-circuit the endpoint uses on non-canonical hosts.
+ *
+ * Shared by the server endpoint (`server/publish/seoEndpoints.ts`) and the
+ * admin editor's "served file" hint so both agree byte-for-byte.
  */
 
-import { AI_ANSWER_CRAWLERS, AI_TRAINING_CRAWLERS } from './aiCrawlers'
 import type { SeoRobotsSettings } from './schema'
 
+/**
+ * Non-content routes worth disallowing by default. `/admin` covers
+ * `/admin/api`; `/_instatic/` covers the lazy fragment + runtime endpoints.
+ * Part of the default template and the Robots tab's "recommended" shortcut.
+ */
+export const SYSTEM_DISALLOW_PATHS = ['/admin', '/_instatic/'] as const
+
+/** The body served (and shown in the editor) when nothing is stored yet. */
+export const DEFAULT_ROBOTS_TEMPLATE = [
+  'User-agent: *',
+  'Allow: /',
+  ...SYSTEM_DISALLOW_PATHS.map((path) => `Disallow: ${path}`),
+].join('\n')
+
 export interface GenerateRobotsTxtInput {
   robots?: SeoRobotsSettings
   /** Whether sitemap generation is enabled (adds the `Sitemap:` line). */
@@ -22,100 +35,25 @@ export interface GenerateRobotsTxtInput {
   /** Absolute public origin for the Sitemap line; absent ⇒ line omitted. */
   origin?: string
   /**
-   * When true, serve a blanket `Disallow: /` regardless of settings —
-   * used by the endpoint on a non-canonical host (preview/staging) so a
-   * non-production deploy never gets indexed. Skips custom rules, AI
-   * toggles, and extra directives, and omits the Sitemap line.
+   * When true, serve a blanket `Disallow: /` regardless of the stored body —
+   * the endpoint uses this on a non-canonical host (preview/staging) so a
+   * non-production deploy never gets indexed. No sitemap line.
    */
   blockAll?: boolean
 }
 
-/**
- * Non-content routes disallowed by default under `User-agent: *`. `/admin`
- * also covers `/admin/api`; `/_instatic/` covers the lazy fragment + runtime
- * endpoints. Opt out with `disallowSystemPaths: false`.
- */
-export const SYSTEM_DISALLOW_PATHS = ['/admin', '/_instatic/'] as const
-
-interface Group {
-  allow: string[]
-  disallow: string[]
-}
-
-/** Append a path once (deduped) to a group's allow/disallow list. */
-function addPath(list: string[], path: string): void {
-  const trimmed = path.trim()
-  if (trimmed !== '' && !list.includes(trimmed)) list.push(trimmed)
-}
+const SITEMAP_DIRECTIVE = /^\s*sitemap\s*:/im
 
 export function generateRobotsTxt(input: GenerateRobotsTxtInput): string {
-  const robots = input.robots ?? {}
+  if (input.blockAll) return 'User-agent: *\nDisallow: /\n'
 
-  if (input.blockAll || robots.indexingEnabled === false) {
-    const lines = ['User-agent: *', 'Disallow: /']
-    if (input.blockAll) return `${lines.join('\n')}\n`
-    // A user-chosen global block still lists the sitemap + extras.
-    return finalize(lines, input, /* allowExtras */ true)
-  }
-
-  // Ordered map of user-agent → group. The `*` group always exists and
-  // renders first; everything else keeps first-seen order.
-  const groups = new Map<string, Group>()
-  const groupFor = (ua: string): Group => {
-    const key = ua.trim()
-    let group = groups.get(key)
-    if (!group) {
-      group = { allow: [], disallow: [] }
-      groups.set(key, group)
-    }
-    return group
-  }
+  const body = (input.robots?.content ?? '').trim() || DEFAULT_ROBOTS_TEMPLATE
+  const lines = [body]
 
-  const star = groupFor('*')
-  if (robots.disallowSystemPaths !== false) {
-    for (const path of SYSTEM_DISALLOW_PATHS) addPath(star.disallow, path)
-  }
-
-  // AI-crawler toggles → blanket Disallow groups per bot.
-  const blockedBots: string[] = []
-  if (robots.allowAiTrainingCrawlers === false) blockedBots.push(...AI_TRAINING_CRAWLERS)
-  if (robots.allowAiAnswerCrawlers === false) blockedBots.push(...AI_ANSWER_CRAWLERS)
-  for (const bot of blockedBots) addPath(groupFor(bot).disallow, '/')
-
-  // Custom rules merge into their target group.
-  for (const rule of robots.rules ?? []) {
-    if (rule.userAgent.trim() === '') continue
-    const group = groupFor(rule.userAgent)
-    for (const path of rule.allow ?? []) addPath(group.allow, path)
-    for (const path of rule.disallow ?? []) addPath(group.disallow, path)
-  }
-
-  // Render: `*` first, then the rest in insertion order.
-  const orderedKeys = ['*', ...[...groups.keys()].filter((key) => key !== '*')]
-  const lines: string[] = []
-  let first = true
-  for (const ua of orderedKeys) {
-    const group = groups.get(ua)!
-    if (!first) lines.push('')
-    first = false
-    lines.push(`User-agent: ${ua}`)
-    // The `*` group with no explicit allow means "index everything" — emit
-    // an explicit `Allow: /` so the intent reads clearly. A bare disallow
-    // group (a blocked bot) needs no Allow line.
-    if (ua === '*' && group.allow.length === 0) lines.push('Allow: /')
-    for (const path of group.allow) lines.push(`Allow: ${path}`)
-    for (const path of group.disallow) lines.push(`Disallow: ${path}`)
-  }
-
-  return finalize(lines, input, /* allowExtras */ true)
-}
-
-/** Append the optional extra-directives block, then the Sitemap line. */
-function finalize(lines: string[], input: GenerateRobotsTxtInput, allowExtras: boolean): string {
-  const extra = allowExtras ? (input.robots?.extraDirectives ?? '').trim() : ''
-  if (extra !== '') lines.push('', extra)
-  if (input.sitemapEnabled && input.origin) {
+  // Append the sitemap line unless the author already declared one.
+  if (input.sitemapEnabled && input.origin && !SITEMAP_DIRECTIVE.test(body)) {
     lines.push('', `Sitemap: ${input.origin.replace(/\/+$/, '')}/sitemap.xml`)
   }
+
   return `${lines.join('\n')}\n`
 }
diff --git a/src/core/seo/robotsAnalysis.ts b/src/core/seo/robotsAnalysis.ts
index fa7dfd0fe..d1611cf2f 100644
--- a/src/core/seo/robotsAnalysis.ts
+++ b/src/core/seo/robotsAnalysis.ts
@@ -2,7 +2,7 @@
  * robots.txt analysis — pure helpers the admin Robots.txt tab uses to lint
  * the generated file and test a URL against it. Both operate on the SAME
  * text the endpoint serves (via `generateRobotsTxt`), so the tab's feedback
- * always reflects reality, including raw `extraDirectives`.
+ * always reflects exactly what crawlers receive.
  *
  *   - `lintRobotsTxt` flags syntax problems crawlers would ignore silently
  *     (unknown directives, rules before any `User-agent`, malformed values).
diff --git a/src/core/seo/schema.ts b/src/core/seo/schema.ts
index fe31f2cd6..72d3f2ff7 100644
--- a/src/core/seo/schema.ts
+++ b/src/core/seo/schema.ts
@@ -79,41 +79,14 @@ export const SeoOrganizationSchema = Type.Object({
 export type SeoOrganization = Static<typeof SeoOrganizationSchema>
 
 /**
- * One custom robots.txt group: a user-agent plus its allow/disallow paths.
- * Rendered as a `User-agent:` block; groups targeting the same agent as a
- * built-in block (the `*` group, or an AI-crawler toggle) merge into it.
+ * robots.txt is edited as a single document: `content` is the raw body the
+ * admin types in the Robots tab's code editor. Empty/absent ⇒ the served
+ * file falls back to `DEFAULT_ROBOTS_TEMPLATE`. The server appends the
+ * `Sitemap:` line (origin-resolved) at serve time unless the body already
+ * has one — so the author never has to hardcode the production origin.
  */
-export const SeoRobotsRuleSchema = Type.Object({
-  /** Target user-agent token, e.g. `*` or `Googlebot`. */
-  userAgent: Type.String(),
-  /** Path prefixes to Allow (each rendered as `Allow: <path>`). */
-  allow: Type.Optional(Type.Array(Type.String())),
-  /** Path prefixes to Disallow (each rendered as `Disallow: <path>`). */
-  disallow: Type.Optional(Type.Array(Type.String())),
-})
-
-export type SeoRobotsRule = Static<typeof SeoRobotsRuleSchema>
-
 export const SeoRobotsSettingsSchema = Type.Object({
-  /** false ⇒ `Disallow: /` for every user agent. Defaults to true. */
-  indexingEnabled: Type.Optional(Type.Boolean()),
-  /** false ⇒ Disallow blocks for AI_TRAINING_CRAWLERS. Defaults to true. */
-  allowAiTrainingCrawlers: Type.Optional(Type.Boolean()),
-  /** false ⇒ Disallow blocks for AI_ANSWER_CRAWLERS. Defaults to true. */
-  allowAiAnswerCrawlers: Type.Optional(Type.Boolean()),
-  /**
-   * false ⇒ skip the default `Disallow:` lines for non-content system routes
-   * (`/admin`, `/_instatic/`) under `User-agent: *`. Defaults to true.
-   */
-  disallowSystemPaths: Type.Optional(Type.Boolean()),
-  /** Custom per-user-agent allow/disallow groups. */
-  rules: Type.Optional(Type.Array(SeoRobotsRuleSchema)),
-  /**
-   * Raw directives appended verbatim to the generated file — the escape
-   * hatch for one-offs (Clean-param, Host, a brand-new crawler). Linted in
-   * the admin tab but never silently dropped.
-   */
-  extraDirectives: Type.Optional(Type.String()),
+  content: Type.Optional(Type.String()),
 })
 
 export type SeoRobotsSettings = Static<typeof SeoRobotsSettingsSchema>

From d19931bd664b5600404823173a88fac4bf47ba00 Mon Sep 17 00:00:00 2001
From: DavidBabinec <hello@davidbabinec.com>
Date: Sun, 14 Jun 2026 15:29:33 +0200
Subject: [PATCH 24/26] =?UTF-8?q?style(seo):=20deslop=20the=20Robots=20tab?=
 =?UTF-8?q?=20=E2=80=94=20quiet=20rows,=20color=20only=20as=20state?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

The recommendation cards used tinted fills + colored left-border accent
bars under four stacked ALL-CAPS sections — the noisy pattern the rest of
the app avoids (and the same left-accent bar already removed from index
rows). Rebuild the assistant rail on the app's grouped-row pattern:
recommendations and lint render as quiet surface-3 rows on a 1px-gap
parent, the only color a single leading state dot; the URL tester result
drops its colored fill for a dot + muted text. Two-layer color model
restored — nothing decorative carries color.

RobotsTab joins the §8.11 advice-row allowlist (full-width wrapping
dot+text rows Button's fixed-height layout can't host).

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
---
 .../button-primitive-usage.test.ts            |  12 +-
 src/admin/pages/seo/tabs/RobotsTab.tsx        | 105 ++++++++--------
 .../pages/seo/tabs/SettingsTabs.module.css    | 115 +++++++++---------
 3 files changed, 117 insertions(+), 115 deletions(-)

diff --git a/src/__tests__/architecture/button-primitive-usage.test.ts b/src/__tests__/architecture/button-primitive-usage.test.ts
index 769e55606..d1d54fc49 100644
--- a/src/__tests__/architecture/button-primitive-usage.test.ts
+++ b/src/__tests__/architecture/button-primitive-usage.test.ts
@@ -108,12 +108,14 @@ const ALLOWLIST = new Set([
   // §8.1 nav rows and §8.7 listbox options.
   'admin/pages/seo/components/SeoTargetIndex.tsx',
 
-  // ── §8.11 SEO improvements advice rows ──────────────────────────────────
-  // The Meta editor's improvements list renders full-width rows (status dot
-  // + wrapping two-line advice text) that focus the field they describe.
-  // Button's fixed heights and white-space: nowrap cannot host wrapping
-  // multi-line row content — same pattern class as the §8.8 index rows.
+  // ── §8.11 SEO advice rows (recommendations + improvements) ──────────────
+  // The Meta editor's improvements list and the Robots tab's recommendation
+  // list render full-width rows (status dot + wrapping two-line advice text)
+  // that apply a fix / focus a field on click. Button's fixed heights and
+  // white-space: nowrap cannot host wrapping multi-line row content — same
+  // pattern class as the §8.8 index rows.
   'admin/pages/seo/components/SeoPreviewEditor.tsx',
+  'admin/pages/seo/tabs/RobotsTab.tsx',
 
   // ── §8.7 Full-width row disclosure / listbox option custom layouts ──────
   // ColorTokenCard row toggle is a full-width structured row (title + meta,
diff --git a/src/admin/pages/seo/tabs/RobotsTab.tsx b/src/admin/pages/seo/tabs/RobotsTab.tsx
index 8a85a3603..9241b9bd8 100644
--- a/src/admin/pages/seo/tabs/RobotsTab.tsx
+++ b/src/admin/pages/seo/tabs/RobotsTab.tsx
@@ -160,40 +160,37 @@ export function RobotsTab({ workspace, canManage, bridge }: RobotsTabProps) {
     { save: () => void handleSave(), publish: () => void handlePublish() },
   )
 
-  const recommendations: { id: string; tone: 'warning' | 'info'; text: string; action: string; onApply: () => void }[] = []
+  const recommendations: { id: string; warn?: boolean; label: string; text: string; onApply: () => void }[] = []
   if (allBlocked) {
     recommendations.push({
       id: 'all-blocked',
-      tone: 'warning',
-      text: 'Every crawler is blocked — your site will not appear in search results.',
-      action: 'Allow crawlers',
+      warn: true,
+      label: 'Allow crawlers',
+      text: 'every crawler is blocked, so the site won’t appear in search.',
       onApply: () => applyEdit(() => 'User-agent: *\nAllow: /'),
     })
   } else {
     if (adminExposed) {
       recommendations.push({
         id: 'admin',
-        tone: 'info',
-        text: 'Admin and internal routes are crawlable. Block them so they stay out of search.',
-        action: 'Block system paths',
+        label: 'Block system paths',
+        text: 'admin and internal routes are crawlable.',
         onApply: () => applyEdit((prev) => addStarDisallows(prev, SYSTEM_DISALLOW_PATHS)),
       })
     }
     if (trainingOpen) {
       recommendations.push({
         id: 'ai-training',
-        tone: 'info',
-        text: 'AI training crawlers can ingest your content for model training.',
-        action: 'Block AI training crawlers',
+        label: 'Block AI training crawlers',
+        text: 'they can ingest your content for model training.',
         onApply: () => applyEdit((prev) => appendBotBlocks(prev, AI_TRAINING_CRAWLERS)),
       })
     }
     if (answerOpen) {
       recommendations.push({
         id: 'ai-answer',
-        tone: 'info',
-        text: 'AI answer engines fetch your pages to ground live answers.',
-        action: 'Block AI answer crawlers',
+        label: 'Block AI answer crawlers',
+        text: 'they fetch your pages to ground live AI answers.',
         onApply: () => applyEdit((prev) => appendBotBlocks(prev, AI_ANSWER_CRAWLERS)),
       })
     }
@@ -207,46 +204,45 @@ export function RobotsTab({ workspace, canManage, bridge }: RobotsTabProps) {
             <header className={styles.cardHeader}>
               <h2 className={styles.heading}>Robots.txt</h2>
               <p className={styles.subheading}>
-                Edit the file directly — it is served at <code>/robots.txt</code> and goes live on
-                publish. The <code>Sitemap:</code> line is added automatically.
+                Served at <code>/robots.txt</code>, live on publish. The <code>Sitemap:</code> line
+                is added automatically.
               </p>
             </header>
 
-            <div className={styles.assistGroup}>
-              <h3 className={styles.assistLabel}>Recommendations</h3>
-              {recommendations.length === 0 ? (
-                <p className={styles.assistOk} role="status">No recommendations — this looks healthy.</p>
-              ) : (
-                recommendations.map((rec) => (
-                  <div key={rec.id} className={cn(styles.recCard, styles[`rec_${rec.tone}`])}>
-                    <p className={styles.recText}>{rec.text}</p>
-                    <Button
-                      variant="secondary"
-                      size="xs"
+            {recommendations.length > 0 && (
+              <div className={styles.assistGroup}>
+                <h3 className={styles.assistLabel}>Recommendations</h3>
+                <div className={styles.adviceList}>
+                  {recommendations.map((rec) => (
+                    <button
+                      key={rec.id}
+                      type="button"
+                      className={styles.adviceRow}
                       disabled={!canManage}
                       onClick={rec.onApply}
                       data-testid={`seo-robots-rec-${rec.id}`}
                     >
-                      {rec.action}
-                    </Button>
-                  </div>
-                ))
-              )}
-            </div>
+                      <span className={cn(styles.adviceDot, rec.warn && styles.adviceDotWarn)} aria-hidden="true" />
+                      <span className={styles.adviceText}><strong>{rec.label}</strong> — {rec.text}</span>
+                    </button>
+                  ))}
+                </div>
+              </div>
+            )}
 
             <div className={styles.assistGroup}>
-              <h3 className={styles.assistLabel}>Quick inserts</h3>
+              <h3 className={styles.assistLabel}>Insert</h3>
               <div className={styles.shortcutRow}>
-                <Button variant="ghost" size="xs" disabled={!canManage}
+                <Button variant="secondary" size="xs" disabled={!canManage}
                   onClick={() => applyEdit(() => DEFAULT_ROBOTS_TEMPLATE)} data-testid="seo-robots-reset">
-                  Recommended defaults
+                  Defaults
                 </Button>
-                <Button variant="ghost" size="xs" disabled={!canManage}
+                <Button variant="secondary" size="xs" disabled={!canManage}
                   onClick={() => applyEdit((prev) => appendBotBlocks(prev, [...AI_TRAINING_CRAWLERS, ...AI_ANSWER_CRAWLERS]))}
                   data-testid="seo-robots-block-ai">
-                  Block all AI crawlers
+                  Block AI crawlers
                 </Button>
-                <Button variant="ghost" size="xs" disabled={!canManage}
+                <Button variant="secondary" size="xs" disabled={!canManage}
                   onClick={() => applyEdit(() => 'User-agent: *\nDisallow: /')} data-testid="seo-robots-block-all">
                   Block everything
                 </Button>
@@ -256,14 +252,17 @@ export function RobotsTab({ workspace, canManage, bridge }: RobotsTabProps) {
             {lint.length > 0 && (
               <div className={styles.assistGroup}>
                 <h3 className={styles.assistLabel}>Issues</h3>
-                <ul className={styles.lintList} aria-label="robots.txt warnings">
+                <div className={styles.adviceList} aria-label="robots.txt issues">
                   {lint.map((finding, i) => (
-                    <li key={i} className={cn(styles.lintItem, styles[`lint_${finding.level}`])}>
-                      <span className={styles.lintLine}>Line {finding.line}</span>
-                      {finding.message}
-                    </li>
+                    <div key={i} className={styles.adviceRow}>
+                      <span
+                        className={cn(styles.adviceDot, finding.level === 'error' ? styles.adviceDotDanger : styles.adviceDotWarn)}
+                        aria-hidden="true"
+                      />
+                      <span className={styles.adviceText}><strong>Line {finding.line}</strong> — {finding.message}</span>
+                    </div>
                   ))}
-                </ul>
+                </div>
               </div>
             )}
 
@@ -293,7 +292,7 @@ export function RobotsTab({ workspace, canManage, bridge }: RobotsTabProps) {
           />
           {workspace.publicOrigin && (
             <p className={styles.servedNote} role="status">
-              Served at <code>{workspace.publicOrigin}/robots.txt</code> · sitemap linked automatically.
+              Served at <code>{workspace.publicOrigin}/robots.txt</code>
             </p>
           )}
         </div>
@@ -328,13 +327,15 @@ function RobotsUrlTester({ robotsText }: { robotsText: string }) {
           data-testid="seo-robots-test-path"
         />
       </div>
-      <p
-        className={cn(styles.testerResult, result.allowed ? styles.testerAllowed : styles.testerBlocked)}
-        role="status"
-        data-testid="seo-robots-test-result"
-      >
-        <strong>{result.allowed ? 'Allowed' : 'Blocked'}</strong>
-        {result.rule ? ` · matched ${result.rule}` : ' · no matching rule'}
+      <p className={styles.testerResult} role="status" data-testid="seo-robots-test-result">
+        <span
+          className={cn(styles.adviceDot, result.allowed ? styles.adviceDotOk : styles.adviceDotDanger)}
+          aria-hidden="true"
+        />
+        <span className={styles.adviceText}>
+          <strong>{result.allowed ? 'Allowed' : 'Blocked'}</strong>
+          {result.rule ? ` · matched ${result.rule}` : ' · no matching rule'}
+        </span>
       </p>
     </div>
   )
diff --git a/src/admin/pages/seo/tabs/SettingsTabs.module.css b/src/admin/pages/seo/tabs/SettingsTabs.module.css
index cf50ced54..8bfb2d4c1 100644
--- a/src/admin/pages/seo/tabs/SettingsTabs.module.css
+++ b/src/admin/pages/seo/tabs/SettingsTabs.module.css
@@ -167,37 +167,6 @@
     color: var(--editor-text-secondary);
 }
 
-.assistOk {
-    margin: 0;
-    font-size: 12px;
-    color: var(--editor-text-muted);
-}
-
-.recCard {
-    display: flex;
-    flex-direction: column;
-    align-items: flex-start;
-    gap: 8px;
-    padding: 12px;
-    border-radius: var(--panel-radius);
-    background: var(--editor-surface-3);
-}
-
-.recText {
-    margin: 0;
-    font-size: 12px;
-    line-height: 1.45;
-    color: var(--editor-text);
-}
-
-.rec_warning {
-    box-shadow: inset 2px 0 0 var(--editor-warning);
-}
-
-.rec_info {
-    box-shadow: inset 2px 0 0 var(--editor-info-text);
-}
-
 .shortcutRow {
     display: flex;
     flex-wrap: wrap;
@@ -210,40 +179,76 @@
     color: var(--editor-text-muted);
 }
 
-/* ── Lint panel ──────────────────────────────────────────────────────────── */
-.lintList {
+/* ── Advice rows (recommendations + lint) — the app's grouped-row pattern:
+ *    quiet surface-3 rows divided by a 1px gap on the surface parent; the
+ *    only color is the leading state dot. ──────────────────────────────── */
+.adviceList {
     display: flex;
     flex-direction: column;
     gap: 1px;
-    margin: 0;
-    padding: 0;
-    list-style: none;
-    border-radius: var(--editor-radius);
+    border-radius: var(--panel-radius);
     overflow: hidden;
 }
 
-.lintItem {
+.adviceRow {
+    appearance: none;
+    border: 0;
+    margin: 0;
+    font: inherit;
+    width: 100%;
+    text-align: left;
     display: flex;
     align-items: baseline;
     gap: 8px;
-    padding: 8px 12px;
-    font-size: 12px;
+    padding: 9px 12px;
     background: var(--editor-surface-3);
+    color: var(--editor-text);
+}
+
+button.adviceRow {
+    cursor: pointer;
+    transition: background 120ms ease;
+}
+
+button.adviceRow:hover:not(:disabled) {
+    background: var(--editor-surface-4);
+}
+
+button.adviceRow:disabled {
+    cursor: not-allowed;
+    opacity: 0.55;
 }
 
-.lintLine {
+.adviceDot {
     flex-shrink: 0;
-    font-family: var(--font-mono);
-    font-size: 10.5px;
-    color: var(--editor-text-muted);
+    width: 6px;
+    height: 6px;
+    margin-top: 5px;
+    border-radius: 50%;
+    background: var(--editor-text-muted);
 }
 
-.lint_warning {
-    color: var(--editor-warning-text);
+.adviceDotOk {
+    background: var(--editor-success-green);
 }
 
-.lint_error {
-    color: var(--editor-danger-text);
+.adviceDotWarn {
+    background: var(--editor-warning);
+}
+
+.adviceDotDanger {
+    background: var(--editor-danger);
+}
+
+.adviceText {
+    font-size: 12px;
+    line-height: 1.45;
+    color: var(--editor-text-muted);
+}
+
+.adviceText strong {
+    font-weight: 600;
+    color: var(--editor-text);
 }
 
 /* ── URL tester ──────────────────────────────────────────────────────────── */
@@ -261,16 +266,10 @@
 
 .testerResult {
     margin: 0;
-    padding: 8px 12px;
+    display: flex;
+    align-items: baseline;
+    gap: 8px;
+    padding: 9px 12px;
     border-radius: var(--editor-radius);
-    font-size: 12px;
     background: var(--editor-surface-3);
 }
-
-.testerAllowed {
-    color: var(--editor-success-text-soft);
-}
-
-.testerBlocked {
-    color: var(--editor-danger-text);
-}

From e27378c8a487551b1c539ee70384dcbab336d01e Mon Sep 17 00:00:00 2001
From: DavidBabinec <hello@davidbabinec.com>
Date: Sun, 14 Jun 2026 20:00:00 +0200
Subject: [PATCH 25/26] style(seo): redesign the Sitemap tab to match the
 Robots tab
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Same assistant-rail + main-column shape: the left rail holds the heading,
a compact Generate-sitemap toggle (label + switch on one line, hint
full-width below — the wide SeoFormRow grid wrapped badly in the narrow
rail), and the inclusion count; the per-target include/exclude list is the
main column, rendered as the app's quiet grouped rows (title + route left,
include switch right; noindex targets disabled with the reason). Off shows
a quiet disabled state.

Drops the XML entry-format code sample (reference fluff — the list already
shows exactly which URLs ship) and the dead two-column workbench /
preview-column CSS. Adds Sitemap-tab test coverage.

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
---
 docs/features/seo.md                          |   7 +-
 src/__tests__/admin/seoWorkspace.test.tsx     |  31 +++++
 .../pages/seo/tabs/SettingsTabs.module.css    |  98 ++++++++------
 src/admin/pages/seo/tabs/SitemapTab.tsx       | 124 +++++++++---------
 4 files changed, 155 insertions(+), 105 deletions(-)

diff --git a/docs/features/seo.md b/docs/features/seo.md
index 2996171b2..5f204c130 100644
--- a/docs/features/seo.md
+++ b/docs/features/seo.md
@@ -150,9 +150,10 @@ publish — the same machinery as the Site toolbar, not a parallel path.
   one-click document edits, quick-insert shortcuts, a lint issue list
   (`lintRobotsTxt`), and a "test a URL" checker (`matchRobots`). No public-
   origin notices (production always sets `PUBLIC_ORIGINS`).
-- **Sitemap tab** — settings card (enable switch + inclusion counts) and
-  per-target include/exclude list beside a sticky entry-format sample
-  (noindex targets shown as auto-excluded).
+- **Sitemap tab** — same shape as Robots: an assistant rail (heading,
+  the Generate toggle + inclusion count) beside the per-target
+  include/exclude list as the main column (noindex targets shown disabled
+  with the reason). Off ⇒ a quiet disabled state.
 
 All workspace forms render rows through the shared
 `components/SeoFormRow.tsx` (`SeoFormRow` / `SeoSwitchRow`): a two-column
diff --git a/src/__tests__/admin/seoWorkspace.test.tsx b/src/__tests__/admin/seoWorkspace.test.tsx
index d042ec7e0..cf87a49b2 100644
--- a/src/__tests__/admin/seoWorkspace.test.tsx
+++ b/src/__tests__/admin/seoWorkspace.test.tsx
@@ -18,6 +18,7 @@ import { StepUpProvider } from '@admin/shared/StepUp'
 import { AdminSectionNavigation } from '@admin/shared/AdminSectionNavigation'
 import { MetaTab } from '@admin/pages/seo/tabs/MetaTab'
 import { RobotsTab } from '@admin/pages/seo/tabs/RobotsTab'
+import { SitemapTab } from '@admin/pages/seo/tabs/SitemapTab'
 import { SeoToolbar } from '@admin/pages/seo/components/SeoToolbar'
 import { useSeoWorkspace } from '@admin/pages/seo/hooks/useSeoWorkspace'
 import { useSeoSaveBridge } from '@admin/pages/seo/hooks/useSeoSaveBridge'
@@ -201,6 +202,13 @@ function RobotsHarness() {
   return <RobotsTab workspace={workspace} canManage bridge={bridge} />
 }
 
+function SitemapHarness() {
+  const workspace = useSeoWorkspace()
+  const bridge = useSeoSaveBridge()
+  if (workspace.loading) return <p>Loading…</p>
+  return <SitemapTab workspace={workspace} canManage bridge={bridge} />
+}
+
 function renderWithSession(node: React.ReactElement, capabilities: string[] = ['seo.read', 'seo.manage', 'ai.chat', 'pages.publish', 'content.publish.any']) {
   return render(
     <MemoryRouter initialEntries={['/admin/tools/seo']}>
@@ -406,6 +414,29 @@ describe('SEO Robots tab', () => {
   })
 })
 
+describe('SEO Sitemap tab', () => {
+  it('lists routable targets with include switches and a count', async () => {
+    mockSeoFetch()
+    renderWithSession(<SitemapHarness />)
+
+    // Routable targets: Home (/), About (/about), Hello world (/posts/…).
+    // The template has no route and is excluded.
+    expect(await screen.findByText('Hello world')).toBeDefined()
+    expect(screen.getByTestId('seo-sitemap-counts').textContent).toContain('3 of 3')
+    expect(screen.queryByText('Post template')).toBeNull()
+  })
+
+  it('turning generation off replaces the list with the disabled state', async () => {
+    mockSeoFetch()
+    renderWithSession(<SitemapHarness />)
+    await screen.findByText('Hello world')
+
+    fireEvent.click(screen.getByTestId('seo-sitemap-enabled'))
+    expect(screen.queryByText('Hello world')).toBeNull()
+    expect(screen.getByTestId('seo-sitemap-counts').textContent).toContain('off')
+  })
+})
+
 describe('Tools navigation', () => {
   it('exposes the SEO link inside the Tools dropdown', async () => {
     mockSeoFetch()
diff --git a/src/admin/pages/seo/tabs/SettingsTabs.module.css b/src/admin/pages/seo/tabs/SettingsTabs.module.css
index 8bfb2d4c1..2b54e042e 100644
--- a/src/admin/pages/seo/tabs/SettingsTabs.module.css
+++ b/src/admin/pages/seo/tabs/SettingsTabs.module.css
@@ -1,41 +1,11 @@
-/* Shared layout for the Robots.txt and Sitemap settings tabs: a two-column
- * workbench — settings card (left) and a sticky code preview (right) —
- * mirroring the Meta tab's editor/preview split. */
+/* Shared layout for the Robots.txt and Sitemap tabs: an assistant rail
+ * (left, sticky) beside the main content column — see `.editorWorkbench`
+ * below. Mirrors the Meta tab's column language. */
 
 .tab {
     min-width: 0;
 }
 
-.workbench {
-    display: grid;
-    grid-template-columns: minmax(0, 1fr) minmax(320px, 440px);
-    gap: 24px;
-    align-items: start;
-}
-
-@media (max-width: 1100px) {
-    .workbench {
-        grid-template-columns: 1fr;
-    }
-}
-
-.settingsColumn {
-    display: flex;
-    flex-direction: column;
-    gap: 18px;
-    min-width: 0;
-}
-
-.previewColumn {
-    position: sticky;
-    top: 0;
-    align-self: start;
-    display: flex;
-    flex-direction: column;
-    gap: 8px;
-    min-width: 0;
-}
-
 /* Same card shell as the Meta editor's form, with roomier spacing. */
 .card {
     display: flex;
@@ -73,19 +43,38 @@
     color: var(--editor-danger-text);
 }
 
-.previewHeading {
-    margin: 0;
+/* Compact rail toggle: label + switch on one line, hint full-width below
+ * (the wide SeoFormRow grid is too cramped in the narrow assistant rail). */
+.toggleRow {
+    display: flex;
+    align-items: center;
+    justify-content: space-between;
+    gap: 12px;
+}
+
+.toggleLabel {
     font-size: 13px;
-    font-weight: 700;
-    color: var(--editor-text-bright);
+    font-weight: 600;
+    color: var(--editor-text);
+}
+
+.toggleHint {
+    margin: 0;
+    font-size: 12px;
+    font-weight: 500;
+    line-height: 1.5;
+    color: var(--editor-text-secondary);
 }
 
 .counts {
     margin: 0;
     font-size: 12px;
-    color: var(--editor-text);
+    font-weight: 500;
+    color: var(--editor-text-muted);
 }
 
+/* ── Sitemap inclusion list (the main column) — grouped rows on a surface
+ *    parent, each: title + route (left), include switch (right). ─────────── */
 .targetList {
     display: flex;
     flex-direction: column;
@@ -99,29 +88,54 @@
     display: flex;
     align-items: center;
     gap: 12px;
-    padding: 10px 14px;
+    padding: 11px 16px;
     background: var(--editor-surface-2);
 }
 
+.targetText {
+    flex: 1;
+    min-width: 0;
+    display: flex;
+    align-items: baseline;
+    gap: 8px;
+}
+
 .targetTitle {
-    font-size: 12px;
+    font-size: 13px;
     font-weight: 600;
     color: var(--editor-text-bright);
+    white-space: nowrap;
+    overflow: hidden;
+    text-overflow: ellipsis;
 }
 
 .targetRoute {
     font-size: 11px;
     font-family: var(--font-mono);
     color: var(--editor-text-muted);
-    flex: 1;
+    min-width: 0;
+    flex-shrink: 4;
     white-space: nowrap;
     overflow: hidden;
     text-overflow: ellipsis;
 }
 
 .targetNote {
+    flex-shrink: 0;
     font-size: 10px;
-    color: var(--editor-warning-text);
+    font-weight: 600;
+    letter-spacing: 0.04em;
+    text-transform: uppercase;
+    color: var(--editor-text-muted);
+}
+
+.disabledState {
+    margin: 0;
+    padding: 24px;
+    border-radius: 16px;
+    background: var(--editor-surface-2);
+    font-size: 13px;
+    color: var(--editor-text-muted);
 }
 
 /* ── Robots editor workbench: assistant rail (left) + editor (main) ──────── */
diff --git a/src/admin/pages/seo/tabs/SitemapTab.tsx b/src/admin/pages/seo/tabs/SitemapTab.tsx
index a067e6fd7..af6ddec28 100644
--- a/src/admin/pages/seo/tabs/SitemapTab.tsx
+++ b/src/admin/pages/seo/tabs/SitemapTab.tsx
@@ -1,11 +1,9 @@
 /**
- * SitemapTab — sitemap.xml generation settings.
- *
- * Two-column workbench: the settings card (enable switch + inclusion
- * counts) and the per-target include/exclude list on the left, a sticky
- * entry-format sample on the right. Noindex targets are excluded
- * automatically and shown as such — the control is disabled with the
- * reason inline.
+ * SitemapTab — sitemap.xml inclusion, in the same shape as the Robots tab:
+ * an assistant rail (left) explaining the file + the master enable toggle +
+ * counts, and the actual content (the list of routable targets with
+ * include/exclude switches) as the main column. Noindex targets are excluded
+ * automatically and shown disabled with the reason inline.
  */
 import { useState } from 'react'
 import { Switch } from '@ui/components/Switch'
@@ -15,8 +13,6 @@ import { hasCapability } from '@admin/access'
 import { useCurrentAdminUser } from '@admin/sessionContext'
 import { StepUpCancelledMessage, useStepUp } from '@admin/shared/StepUp'
 import type { SeoSitemapSettings } from '@core/seo'
-import { SeoCodeViewer } from '../components/SeoCodeViewer'
-import { SeoSwitchRow } from '../components/SeoFormRow'
 import type { SeoWorkspace } from '../hooks/useSeoWorkspace'
 import type { SeoSaveBridge } from '../hooks/useSeoSaveBridge'
 import { useSeoSaveSurface } from '../hooks/useSeoSaveBridge'
@@ -28,10 +24,12 @@ interface SitemapTabProps {
   bridge: SeoSaveBridge
 }
 
+type SaveState = 'idle' | 'saving' | 'saved' | 'publishing' | 'published' | 'error'
+
 export function SitemapTab({ workspace, canManage, bridge }: SitemapTabProps) {
   const stored = workspace.siteSeo?.sitemap ?? {}
   const [draft, setDraft] = useState<SeoSitemapSettings>(stored)
-  const [saveState, setSaveState] = useState<'idle' | 'saving' | 'saved' | 'publishing' | 'published' | 'error'>('idle')
+  const [saveState, setSaveState] = useState<SaveState>('idle')
   const [saveError, setSaveError] = useState<string | null>(null)
   const currentUser = useCurrentAdminUser()
   const { runStepUp } = useStepUp()
@@ -49,6 +47,20 @@ export function SitemapTab({ workspace, canManage, bridge }: SitemapTabProps) {
     return !excluded.has(key)
   })
 
+  function touch(): void {
+    if (saveState !== 'idle') setSaveState('idle')
+  }
+
+  function setEnabled(value: boolean): void {
+    setDraft((current) => {
+      const next = { ...current }
+      if (value) delete next.enabled
+      else next.enabled = false
+      return next
+    })
+    touch()
+  }
+
   function toggleTarget(kind: 'page' | 'row', id: string, include: boolean): void {
     const key = `${kind}:${id}`
     setDraft((current) => {
@@ -60,7 +72,7 @@ export function SitemapTab({ workspace, canManage, bridge }: SitemapTabProps) {
       else next.excludedTargets = [...set].sort()
       return next
     })
-    if (saveState !== 'idle') setSaveState('idle')
+    touch()
   }
 
   async function handleSave(): Promise<boolean> {
@@ -111,51 +123,59 @@ export function SitemapTab({ workspace, canManage, bridge }: SitemapTabProps) {
 
   return (
     <section className={styles.tab} aria-label="Sitemap settings">
-      <div className={styles.workbench}>
-        <div className={styles.settingsColumn}>
-          {saveError && <p className={styles.error} role="alert">{saveError}</p>}
-
+      <div className={styles.editorWorkbench}>
+        <aside className={styles.assistColumn} aria-label="Sitemap help">
           <div className={styles.card}>
             <header className={styles.cardHeader}>
               <h2 className={styles.heading}>Sitemap</h2>
               <p className={styles.subheading}>
-                Generated from published content and served at <code>/sitemap.xml</code>. Changes go live on the next publish.
+                Generated from published content, served at <code>/sitemap.xml</code>, live on
+                publish. Each URL carries its last-modified date.
               </p>
             </header>
 
-            <SeoSwitchRow
-              id="seo-sitemap-enabled-switch"
-              label="Generate sitemap.xml"
-              hint="Search and answer engines use the sitemap to discover published pages and posts."
-              checked={enabled}
-              disabled={!canManage}
-              onCheckedChange={(value) => {
-                setDraft((current) => {
-                  const next = { ...current }
-                  if (value) delete next.enabled
-                  else next.enabled = false
-                  return next
-                })
-                if (saveState !== 'idle') setSaveState('idle')
-              }}
-              data-testid="seo-sitemap-enabled"
-            />
+            <div className={styles.assistGroup}>
+              <div className={styles.toggleRow}>
+                <label htmlFor="seo-sitemap-enabled-switch" className={styles.toggleLabel}>
+                  Generate sitemap.xml
+                </label>
+                <Switch
+                  id="seo-sitemap-enabled-switch"
+                  checked={enabled}
+                  disabled={!canManage}
+                  onCheckedChange={setEnabled}
+                  aria-label="Generate sitemap.xml"
+                  data-testid="seo-sitemap-enabled"
+                />
+              </div>
+              <p className={styles.toggleHint}>
+                Search and answer engines use it to discover published pages and posts.
+              </p>
+              <p className={styles.counts} role="status" data-testid="seo-sitemap-counts">
+                {enabled
+                  ? `${included.length} of ${routable.length} routable targets included.`
+                  : 'Sitemap generation is off — /sitemap.xml returns 404.'}
+              </p>
+            </div>
 
-            <p className={styles.counts} role="status" data-testid="seo-sitemap-counts">
-              {enabled
-                ? `${included.length} of ${routable.length} routable targets included.`
-                : 'Sitemap generation is disabled — /sitemap.xml returns 404.'}
-            </p>
+            {saveError && <p className={styles.error} role="alert">{saveError}</p>}
           </div>
+        </aside>
 
-          {enabled && (
+        <div className={styles.editorMain}>
+          {enabled ? (
             <div className={styles.targetList} aria-label="Sitemap inclusion">
               {routable.map((target) => {
-                const kindKey = target.kind === 'post' ? 'row' as const : 'page' as const
+                const kindKey = target.kind === 'post' ? ('row' as const) : ('page' as const)
                 const noindexed = target.seo?.noindex === true
                 const isIncluded = !noindexed && !excluded.has(`${kindKey}:${target.id}`)
                 return (
                   <div key={target.id} className={styles.targetRow}>
+                    <span className={styles.targetText}>
+                      <span className={styles.targetTitle}>{target.title}</span>
+                      <span className={styles.targetRoute}>{target.route}</span>
+                    </span>
+                    {noindexed && <span className={styles.targetNote}>noindex</span>}
                     <Switch
                       checked={isIncluded}
                       disabled={!canManage || noindexed}
@@ -163,33 +183,17 @@ export function SitemapTab({ workspace, canManage, bridge }: SitemapTabProps) {
                       aria-label={`Include ${target.title} in the sitemap`}
                       switchSize="sm"
                     />
-                    <span className={styles.targetTitle}>{target.title}</span>
-                    <span className={styles.targetRoute}>{target.route}</span>
-                    {noindexed && (
-                      <span className={styles.targetNote}>noindex — excluded automatically</span>
-                    )}
                   </div>
                 )
               })}
             </div>
+          ) : (
+            <p className={styles.disabledState} role="status">
+              Sitemap generation is off. Turn it on to choose which pages and posts are listed.
+            </p>
           )}
         </div>
-
-        <aside className={styles.previewColumn} aria-label="Sitemap entry format">
-          <h3 className={styles.previewHeading}>Entry format</h3>
-          <SeoCodeViewer docKey="sitemap-sample" value={sampleEntry(workspace)} language="html" />
-        </aside>
       </div>
     </section>
   )
 }
-
-function sampleEntry(workspace: SeoWorkspace): string {
-  const origin = workspace.publicOrigin ?? 'https://example.com'
-  return [
-    '<url>',
-    `  <loc>${origin}/posts/hello-world</loc>`,
-    '  <lastmod>2026-06-12T00:00:00.000Z</lastmod>',
-    '</url>',
-  ].join('\n')
-}

From dc1194a3e6981df6284a4dcac917eb58388ce778 Mon Sep 17 00:00:00 2001
From: DavidBabinec <hello@davidbabinec.com>
Date: Sun, 14 Jun 2026 20:00:41 +0200
Subject: [PATCH 26/26] docs(seo): drop stale 'two toggles' reference in
 aiCrawlers row

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
---
 docs/features/seo.md | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/docs/features/seo.md b/docs/features/seo.md
index 5f204c130..ee5eb167c 100644
--- a/docs/features/seo.md
+++ b/docs/features/seo.md
@@ -21,7 +21,7 @@ One engine module owns everything: **`src/core/seo/`** (barrel-gated).
 | `jsonLd.ts` | `buildJsonLdEntities` (`WebSite`, `Organization`, `Article`, `BreadcrumbList`) + `serializeJsonLd` (escapes `</script`, `<!--`) |
 | `robots.ts` | `generateRobotsTxt` — serves the stored body verbatim (`SeoRobotsSettings.content`), falling back to `DEFAULT_ROBOTS_TEMPLATE` when empty and appending the origin-resolved `Sitemap:` line unless the body already has one. `SYSTEM_DISALLOW_PATHS` seeds the default template + the tab's "block system paths" shortcut. `blockAll` serves a bare `Disallow: /` for preview hosts. |
 | `robotsAnalysis.ts` | `lintRobotsTxt` (flags unknown directives, rules before any `User-agent`, malformed values) + `matchRobots` (is a path crawlable for a UA — Google longest-match, `Allow` tie-break, `*`/`$` support). Powers the Robots tab's issue list and URL tester, plus the contextual recommendations. |
-| `aiCrawlers.ts` | The AI-crawler user-agent lists behind the Robots tab's two toggles |
+| `aiCrawlers.ts` | The AI-crawler user-agent lists the Robots tab's "block AI crawlers" shortcuts insert (training + answer groups) |
 | `health.ts` | `computeSeoReport` — per-target weighted checks + 0–100 score (`aggregateSeoScore`, `seoScoreTier` for the site-wide rollup and good/fair/poor tiers) |
 | `lengthMeter.ts` | Approximate pixel-width metering with an ideal band (~580px title / ~990px description budgets; "ok" only between the too-short minimum and the budget) |