CoreBunch · DavidBabinec · Jun 12, 2026 · Jun 12, 2026 · Jun 12, 2026 · Jun 12, 2026
diff --git 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
@@ -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
@@ -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
@@ -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/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/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
@@ -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
@@ -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.