From c7692446631e83a4d4c2094c3037fd3b099fabc8 Mon Sep 17 00:00:00 2001
From: "copilot-swe-agent[bot]" <198982749+Copilot@users.noreply.github.com>
Date: Mon, 30 Mar 2026 17:38:20 +0000
Subject: [PATCH 01/19] Initial plan


From ee7dc1e9bf1747bd72b2686d2ba343ac3246db2d Mon Sep 17 00:00:00 2001
From: "copilot-swe-agent[bot]" <198982749+Copilot@users.noreply.github.com>
Date: Mon, 30 Mar 2026 17:54:49 +0000
Subject: [PATCH 02/19] feat: add page content type and exposeToHomepage to
 ottablog + worker APIs + admin editor

Agent-Logs-Url: https://github.com/thinkdj/ottabase/sessions/046b035e-9b57-4779-b4ad-6fa561dfc03b
---
 .../pages/admin/blog/AdminBlogEditorPage.tsx  | 26 ++++++-
 .../src/types/blog.ts                         |  1 +
 .../worker/routes/blog.ts                     | 71 +++++++++++++++++--
 .../worker/routes/router.ts                   | 11 +++
 packages/ottablog/src/index.ts                |  1 +
 .../src/ottaorm-models/Post.schema.ts         |  6 ++
 packages/ottablog/src/ottaorm-models/Post.ts  | 21 ++++++
 packages/ottablog/src/types.ts                | 12 +++-
 8 files changed, 141 insertions(+), 8 deletions(-)

diff --git a/apps/ottabase-template-app-tanstack/src/pages/admin/blog/AdminBlogEditorPage.tsx b/apps/ottabase-template-app-tanstack/src/pages/admin/blog/AdminBlogEditorPage.tsx
index 06cc1b1fc..0b46a3960 100644
--- a/apps/ottabase-template-app-tanstack/src/pages/admin/blog/AdminBlogEditorPage.tsx
+++ b/apps/ottabase-template-app-tanstack/src/pages/admin/blog/AdminBlogEditorPage.tsx
@@ -107,6 +107,7 @@ interface BlogPost {
     allowComments: boolean;
     isProtected?: boolean;
     passwordHint?: string | null;
+    exposeToHomepage?: boolean;
     publishedAt: string | null;
     maxVersionsToKeep: number | null;
     wordCount: number | null;
@@ -239,6 +240,7 @@ function BlogEditorForm({ postId, isEditMode, initialData }: BlogEditorFormProps
     const [isFeatured, setIsFeatured] = useState(initialData?.isFeatured || false);
     const [allowComments, setAllowComments] = useState(initialData?.allowComments ?? true);
     const [isProtected, setIsProtected] = useState(initialData?.isProtected ?? false);
+    const [exposeToHomepage, setExposeToHomepage] = useState(initialData?.exposeToHomepage ?? false);
     const [passwordHint, setPasswordHint] = useState(initialData?.passwordHint ?? '');
     const [password, setPassword] = useState(''); // transient: only sent when setting/changing
     const [publishedAt, setPublishedAt] = useState(
@@ -483,6 +485,7 @@ function BlogEditorForm({ postId, isEditMode, initialData }: BlogEditorFormProps
             isFeatured === initialData.isFeatured &&
             allowComments === initialData.allowComments &&
             isProtected === (initialData.isProtected ?? false) &&
+            exposeToHomepage === (initialData.exposeToHomepage ?? false) &&
             (passwordHint ?? '') === (initialData.passwordHint ?? '') &&
             !password &&
             (publishedAt || '') ===
@@ -519,6 +522,7 @@ function BlogEditorForm({ postId, isEditMode, initialData }: BlogEditorFormProps
         authorName,
         isFeatured,
         allowComments,
+        exposeToHomepage,
         publishedAt,
         seriesId,
         seriesOrder,
@@ -881,6 +885,7 @@ function BlogEditorForm({ postId, isEditMode, initialData }: BlogEditorFormProps
                 isFeatured,
                 allowComments,
                 isProtected,
+                exposeToHomepage: contentType === 'page' ? exposeToHomepage : false,
                 passwordHint: passwordHint || undefined,
                 ...(isProtected && password.trim() ? { password: password.trim() } : {}),
                 publishedAt: publishNow && !publishedAt ? Date.now() : publishedAt || undefined,
@@ -1350,7 +1355,12 @@ function BlogEditorForm({ postId, isEditMode, initialData }: BlogEditorFormProps
                                     id="contentType"
                                     aria-label="Content type"
                                     value={contentType}
-                                    onChange={(e) => setContentType(e.target.value as ContentType)}
+                                    onChange={(e) => {
+                                        const next = e.target.value as ContentType;
+                                        setContentType(next);
+                                        // Clear exposeToHomepage when switching away from 'page'
+                                        if (next !== 'page') setExposeToHomepage(false);
+                                    }}
                                     className="w-full rounded-md border border-input bg-background px-3 py-2 text-sm"
                                 >
                                     {Object.entries(CONTENT_TYPES).map(([value, { label }]) => (
@@ -1409,6 +1419,20 @@ function BlogEditorForm({ postId, isEditMode, initialData }: BlogEditorFormProps
                                     <Label htmlFor="isFeatured">Featured Post</Label>
                                 </div>
 
+                                {contentType === 'page' && (
+                                    <div className="flex items-center gap-2">
+                                        <input
+                                            type="checkbox"
+                                            id="exposeToHomepage"
+                                            aria-label="Expose to homepage navbar"
+                                            checked={exposeToHomepage}
+                                            onChange={(e) => setExposeToHomepage(e.target.checked)}
+                                            className="rounded"
+                                        />
+                                        <Label htmlFor="exposeToHomepage">Expose to Homepage Navbar</Label>
+                                    </div>
+                                )}
+
                                 <div className="flex items-center gap-2">
                                     <input
                                         type="checkbox"
diff --git a/apps/ottabase-template-app-tanstack/src/types/blog.ts b/apps/ottabase-template-app-tanstack/src/types/blog.ts
index 163e6f6f3..9d9f8f89c 100644
--- a/apps/ottabase-template-app-tanstack/src/types/blog.ts
+++ b/apps/ottabase-template-app-tanstack/src/types/blog.ts
@@ -48,6 +48,7 @@ export interface BlogPost {
     authorAvatar: string | null;
     isFeatured: boolean;
     allowComments: boolean;
+    exposeToHomepage?: boolean;
     viewCount: number;
     readingTimeMinutes: number | null;
     wordCount: number | null;
diff --git a/apps/ottabase-template-app-tanstack/worker/routes/blog.ts b/apps/ottabase-template-app-tanstack/worker/routes/blog.ts
index d94b93766..a836d6e69 100644
--- a/apps/ottabase-template-app-tanstack/worker/routes/blog.ts
+++ b/apps/ottabase-template-app-tanstack/worker/routes/blog.ts
@@ -1,6 +1,7 @@
 import { verifyPassword } from '@ottabase/auth/backend';
 import { createD1Driver } from '@ottabase/db/drizzle-d1';
 import {
+    BLOG_FEED_CONTENT_TYPES,
     OttablogPlugin,
     OttablogTheme,
     Post,
@@ -246,8 +247,8 @@ export async function handleBlogPostsList(context: BlogRouteContext): Promise<Re
     if (contentType) {
         where.contentType = contentType;
     } else {
-        // Dedicated changelog lives at /changelog (changelog_entries); keep blog list blog-only
-        where.contentType = { $ne: 'changelog' };
+        // Public blog feed: only show blog articles (exclude changelog + page)
+        where.contentType = { $in: BLOG_FEED_CONTENT_TYPES };
     }
     if (seriesId) where.seriesId = seriesId;
 
@@ -353,7 +354,7 @@ export async function handleBlogPostBySlug(context: BlogRouteContext, slug: stri
         return errorResponse('Post not found', 404, { code: 'NOT_FOUND' });
     }
 
-    if (record.get('contentType') === 'changelog') {
+    if (record.get('contentType') === 'changelog' || record.get('contentType') === 'page') {
         return errorResponse('Post not found', 404, { code: 'NOT_FOUND' });
     }
 
@@ -368,6 +369,62 @@ export async function handleBlogPostBySlug(context: BlogRouteContext, slug: stri
     return jsonResponse(data);
 }
 
+/**
+ * GET /api/blog/pages/by-slug/:slug
+ * Returns a published page (contentType === 'page') by slug.
+ * This is the dedicated public API for marketing/static pages.
+ */
+export async function handleBlogPageBySlug(context: BlogRouteContext, slug: string): Promise<Response> {
+    const { env, url } = context;
+    const d1Error = ensureD1(env);
+    if (d1Error) return d1Error;
+    registerConnection('default', createD1Driver(env.OBCF_D1));
+
+    const appId = url.searchParams.get('appId') || null;
+    const where: Record<string, unknown> = { slug, status: 'published', contentType: 'page' };
+    if (appId) where.appId = appId;
+    const record = await Post.first(where);
+    if (!record) {
+        return errorResponse('Page not found', 404, { code: 'NOT_FOUND' });
+    }
+
+    const data = await publicPostJson(record, { enrichTags: true, enrichCategory: true });
+    return jsonResponse(data);
+}
+
+/**
+ * GET /api/blog/pages/exposed
+ * Returns published pages with exposeToHomepage: true.
+ * Used by the marketing homepage to build navbar links.
+ */
+export async function handleExposedPages(context: BlogRouteContext): Promise<Response> {
+    const { env, url } = context;
+    const d1Error = ensureD1(env);
+    if (d1Error) return d1Error;
+    registerConnection('default', createD1Driver(env.OBCF_D1));
+
+    const appId = url.searchParams.get('appId') || null;
+
+    try {
+        const where: Record<string, unknown> = {
+            contentType: 'page',
+            status: 'published',
+            exposeToHomepage: true,
+        };
+        if (appId) where.appId = appId;
+
+        const pages = await Post.where(where, { orderBy: 'title', orderDirection: 'asc' });
+        const exposedPages = pages.map((p) => ({
+            slug: p.get('slug') as string,
+            title: p.get('title') as string,
+        }));
+        return jsonResponse({ exposedPages });
+    } catch {
+        // Never hard-fail: return empty array
+        return jsonResponse({ exposedPages: [] });
+    }
+}
+
 export async function handleBlogPostUnlock(context: BlogRouteContext): Promise<Response> {
     const { request, env, url } = context;
     const d1Error = ensureD1(env);
@@ -390,7 +447,7 @@ export async function handleBlogPostUnlock(context: BlogRouteContext): Promise<R
         return errorResponse('Post not found', 404, { code: 'NOT_FOUND' });
     }
 
-    if (record.get('contentType') === 'changelog') {
+    if (record.get('contentType') === 'changelog' || record.get('contentType') === 'page') {
         return errorResponse('Post not found', 404, { code: 'NOT_FOUND' });
     }
 
@@ -536,7 +593,8 @@ export async function handleBlogRssFeed(context: BlogRouteContext): Promise<Resp
     if (contentType) {
         where.contentType = contentType;
     } else {
-        where.contentType = { $ne: 'changelog' };
+        // Public RSS feed: only blog articles (exclude changelog + page)
+        where.contentType = { $in: BLOG_FEED_CONTENT_TYPES };
     }
 
     const posts = await Post.where(where, {
@@ -621,7 +679,8 @@ export async function handleBlogSitemap(context: BlogRouteContext): Promise<Resp
     registerConnection('default', createD1Driver(env.OBCF_D1));
 
     const appId = url.searchParams.get('appId') || null;
-    const where: Record<string, unknown> = { status: 'published', contentType: { $ne: 'changelog' } };
+    // Sitemap: only blog articles (exclude changelog + page)
+    const where: Record<string, unknown> = { status: 'published', contentType: { $in: BLOG_FEED_CONTENT_TYPES } };
     if (appId) where.appId = appId;
 
     const posts = await Post.where(where, {
diff --git a/apps/ottabase-template-app-tanstack/worker/routes/router.ts b/apps/ottabase-template-app-tanstack/worker/routes/router.ts
index 8dae78dc5..185cb8382 100644
--- a/apps/ottabase-template-app-tanstack/worker/routes/router.ts
+++ b/apps/ottabase-template-app-tanstack/worker/routes/router.ts
@@ -50,6 +50,7 @@ import {
 } from './auth';
 import {
     handleBlogCategoryBySlug,
+    handleBlogPageBySlug,
     handleBlogPostBySlug,
     handleBlogPostUnlock,
     handleBlogPostsList,
@@ -63,6 +64,7 @@ import {
     handleBlogStudioPluginEnable,
     handleBlogStudioState,
     handleBlogTagBySlug,
+    handleExposedPages,
 } from './blog';
 import { handleChangelogEntriesList, handleChangelogEntryBySlug } from './changelog';
 import { handleBrandApi } from './brand';
@@ -219,6 +221,15 @@ async function handleGetRoutes(context: ApiRouteContext): Promise<Response | nul
         if (route === '/api/blog/posts') {
             return handleBlogPostsList(context);
         }
+        // Pages endpoints (before posts by-slug to avoid path collision)
+        if (route === '/api/blog/pages/exposed') {
+            return handleExposedPages(context);
+        }
+        const pageBySlugMatch = route.match(/^\/api\/blog\/pages\/by-slug\/([^/]+)$/);
+        if (pageBySlugMatch) {
+            const slug = decodeURIComponent(pageBySlugMatch[1]);
+            return handleBlogPageBySlug(context, slug);
+        }
         const blogRelatedMatch = route.match(/^\/api\/blog\/posts\/([^/]+)\/related$/);
         if (blogRelatedMatch) {
             const postId = decodeURIComponent(blogRelatedMatch[1]);
diff --git a/packages/ottablog/src/index.ts b/packages/ottablog/src/index.ts
index e5edc18b9..cf9750bfc 100644
--- a/packages/ottablog/src/index.ts
+++ b/packages/ottablog/src/index.ts
@@ -92,6 +92,7 @@ export type { Author, ContentType, EditorJSData, HeroImage, PostStatus, ReadingT
 
 // Constants and helpers
 export {
+    BLOG_FEED_CONTENT_TYPES,
     CONTENT_TYPES,
     DEFAULT_SEO_META,
     POST_STATUSES,
diff --git a/packages/ottablog/src/ottaorm-models/Post.schema.ts b/packages/ottablog/src/ottaorm-models/Post.schema.ts
index 25dfaff5f..7e33c2849 100644
--- a/packages/ottablog/src/ottaorm-models/Post.schema.ts
+++ b/packages/ottablog/src/ottaorm-models/Post.schema.ts
@@ -109,6 +109,9 @@ export const postsTable = sqliteTable(
         // Featured/pinned post
         isFeatured: integer('is_featured', { mode: 'boolean' }).notNull().default(false),
 
+        // Expose page to homepage navbar (only meaningful for contentType='page')
+        exposeToHomepage: integer('expose_to_homepage', { mode: 'boolean' }).notNull().default(false),
+
         // Allow comments
         allowComments: integer('allow_comments', { mode: 'boolean' }).notNull().default(true),
 
@@ -178,6 +181,9 @@ export const postsTable = sqliteTable(
         // Featured posts: isFeatured + publishedAt for featured queries
         index('posts_is_featured_published_at_idx').on(table.isFeatured, table.publishedAt),
 
+        // Exposed pages: contentType + status + exposeToHomepage for homepage nav
+        index('posts_content_type_status_expose_idx').on(table.contentType, table.status, table.exposeToHomepage),
+
         // Scheduled posts: publishAt for auto-publish scheduling
         index('posts_publish_at_idx').on(table.publishAt),
 
diff --git a/packages/ottablog/src/ottaorm-models/Post.ts b/packages/ottablog/src/ottaorm-models/Post.ts
index 0e2691dd6..1474cb5b2 100644
--- a/packages/ottablog/src/ottaorm-models/Post.ts
+++ b/packages/ottablog/src/ottaorm-models/Post.ts
@@ -40,6 +40,7 @@ export class Post extends BaseModel {
         privateNotes: 'json' as const,
         footnotes: 'json' as const,
         isFeatured: 'boolean' as const,
+        exposeToHomepage: 'boolean' as const,
         allowComments: 'boolean' as const,
         isProtected: 'boolean' as const,
         readingTimeMinutes: 'number' as const,
@@ -58,6 +59,7 @@ export class Post extends BaseModel {
         status: 'draft',
         contentType: 'blog',
         isFeatured: false,
+        exposeToHomepage: false,
         allowComments: true,
         isProtected: false,
         viewCount: 0,
@@ -86,6 +88,7 @@ export class Post extends BaseModel {
             'readingTimeMinutes',
             'wordCount',
             'isFeatured',
+            'exposeToHomepage',
             'allowComments',
             'isProtected',
             'passwordHash',
@@ -119,6 +122,7 @@ export class Post extends BaseModel {
             'readingTimeMinutes',
             'wordCount',
             'isFeatured',
+            'exposeToHomepage',
             'allowComments',
             'isProtected',
             'passwordHash',
@@ -480,6 +484,23 @@ export class Post extends BaseModel {
                 colWidth: 120,
             },
         },
+        exposeToHomepage: {
+            type: 'boolean',
+            editable: true,
+            filterable: true,
+            uiConfig: {
+                label: 'Expose to Homepage',
+                description: 'Show this page as a link in the marketing homepage navbar',
+                defaultValue: false,
+            },
+            formConfig: {
+                visible: true,
+                fieldType: 'boolean',
+            },
+            tableConfig: {
+                visible: false,
+            },
+        },
         allowComments: {
             type: 'boolean',
             editable: true,
diff --git a/packages/ottablog/src/types.ts b/packages/ottablog/src/types.ts
index a6e2f9d9e..35ee3d540 100644
--- a/packages/ottablog/src/types.ts
+++ b/packages/ottablog/src/types.ts
@@ -6,7 +6,7 @@
 /**
  * Content type determines the purpose and display style of the content
  */
-export type ContentType = 'blog' | 'changelog' | 'docs' | 'news' | 'announcement';
+export type ContentType = 'blog' | 'changelog' | 'docs' | 'news' | 'announcement' | 'page';
 
 /**
  * Publication status of the content
@@ -121,8 +121,18 @@ export const CONTENT_TYPES: Record<ContentType, { label: string; description: st
         label: 'Announcement',
         description: 'Important announcements and notices',
     },
+    page: {
+        label: 'Page',
+        description: 'Static/marketing page managed via CMS',
+    },
 };
 
+/**
+ * Content types included in public blog feeds (list, RSS, sitemap).
+ * Excludes 'changelog' (separate product surface) and 'page' (marketing-only, not "blog articles").
+ */
+export const BLOG_FEED_CONTENT_TYPES: ContentType[] = ['blog', 'docs', 'news', 'announcement'];
+
 /**
  * All post statuses with their labels
  */

From 7aae3bb9fdd8342194125c72edc88bb53f18d384 Mon Sep 17 00:00:00 2001
From: "copilot-swe-agent[bot]" <198982749+Copilot@users.noreply.github.com>
Date: Mon, 30 Mar 2026 18:01:11 +0000
Subject: [PATCH 03/19] feat: add Next.js page route, navbar integration, and
 tests for exposed pages

Agent-Logs-Url: https://github.com/thinkdj/ottabase/sessions/046b035e-9b57-4779-b4ad-6fa561dfc03b
---
 .../.env.example                              |  3 +
 .../__tests__/components.test.tsx             | 50 +++++++++++
 .../app/{ => (site)}/page.tsx                 |  0
 .../app/layout-shell.tsx                      | 44 ++++++++--
 .../app/layout.tsx                            |  8 +-
 .../app/page/[slug]/page-content.tsx          | 37 ++++++++
 .../app/page/[slug]/page.tsx                  | 26 ++++++
 .../lib/api.ts                                | 86 +++++++++++++++++++
 .../package.json                              |  1 +
 packages/ottablog/src/__tests__/types.test.ts | 52 ++++++++++-
 pnpm-lock.yaml                                |  3 +
 11 files changed, 301 insertions(+), 9 deletions(-)
 rename apps/ottabase-template-app-nextjs-homepage/app/{ => (site)}/page.tsx (100%)
 create mode 100644 apps/ottabase-template-app-nextjs-homepage/app/page/[slug]/page-content.tsx
 create mode 100644 apps/ottabase-template-app-nextjs-homepage/app/page/[slug]/page.tsx
 create mode 100644 apps/ottabase-template-app-nextjs-homepage/lib/api.ts

diff --git a/apps/ottabase-template-app-nextjs-homepage/.env.example b/apps/ottabase-template-app-nextjs-homepage/.env.example
index 9dbdc953c..82309a117 100644
--- a/apps/ottabase-template-app-nextjs-homepage/.env.example
+++ b/apps/ottabase-template-app-nextjs-homepage/.env.example
@@ -51,6 +51,9 @@ NODE_ENV="development"
 # Set to "true" to show on production, or leave unset to auto-show in dev only
 # NEXT_PUBLIC_SHOW_CONFIG_PANEL="true"
 
+# Ottabase Worker API URL (for CMS pages, exposed pages)
+# NEXT_PUBLIC_API_URL="http://localhost:3004"
+
 # ============================================================
 # Database Configuration (Prisma + D1)
 # ============================================================
diff --git a/apps/ottabase-template-app-nextjs-homepage/__tests__/components.test.tsx b/apps/ottabase-template-app-nextjs-homepage/__tests__/components.test.tsx
index 03c50152b..e7a5cbf4c 100644
--- a/apps/ottabase-template-app-nextjs-homepage/__tests__/components.test.tsx
+++ b/apps/ottabase-template-app-nextjs-homepage/__tests__/components.test.tsx
@@ -314,3 +314,53 @@ describe('ThemePresetSwitcher', () => {
         });
     });
 });
+
+describe('LayoutShell navbar merge', () => {
+    let mergeNavLinks: any;
+
+    beforeEach(async () => {
+        ({ mergeNavLinks } = await import('../app/layout-shell'));
+    });
+
+    it('returns base links when no exposed pages', () => {
+        const base = [
+            { href: '/', label: 'Home' },
+            { href: '/about', label: 'About' },
+        ];
+        const result = mergeNavLinks(base, []);
+        expect(result).toEqual(base);
+    });
+
+    it('appends exposed pages as /page/slug links', () => {
+        const base = [{ href: '/', label: 'Home' }];
+        const exposedPages = [
+            { slug: 'about-us', title: 'About Us' },
+            { slug: 'pricing', title: 'Pricing' },
+        ];
+        const result = mergeNavLinks(base, exposedPages);
+        expect(result).toEqual([
+            { href: '/', label: 'Home' },
+            { href: '/page/about-us', label: 'About Us' },
+            { href: '/page/pricing', label: 'Pricing' },
+        ]);
+    });
+
+    it('deduplicates exposed pages by href', () => {
+        const base = [{ href: '/page/about-us', label: 'Existing About' }];
+        const exposedPages = [
+            { slug: 'about-us', title: 'About Us' },
+            { slug: 'pricing', title: 'Pricing' },
+        ];
+        const result = mergeNavLinks(base, exposedPages);
+        // /page/about-us already exists in base, so only pricing is appended
+        expect(result).toEqual([
+            { href: '/page/about-us', label: 'Existing About' },
+            { href: '/page/pricing', label: 'Pricing' },
+        ]);
+    });
+
+    it('handles empty base links with exposed pages', () => {
+        const result = mergeNavLinks([], [{ slug: 'faq', title: 'FAQ' }]);
+        expect(result).toEqual([{ href: '/page/faq', label: 'FAQ' }]);
+    });
+});
diff --git a/apps/ottabase-template-app-nextjs-homepage/app/page.tsx b/apps/ottabase-template-app-nextjs-homepage/app/(site)/page.tsx
similarity index 100%
rename from apps/ottabase-template-app-nextjs-homepage/app/page.tsx
rename to apps/ottabase-template-app-nextjs-homepage/app/(site)/page.tsx
diff --git a/apps/ottabase-template-app-nextjs-homepage/app/layout-shell.tsx b/apps/ottabase-template-app-nextjs-homepage/app/layout-shell.tsx
index 1cd24f54e..0f7939a6e 100644
--- a/apps/ottabase-template-app-nextjs-homepage/app/layout-shell.tsx
+++ b/apps/ottabase-template-app-nextjs-homepage/app/layout-shell.tsx
@@ -2,13 +2,15 @@
 
 import { ConfigPanel } from '../components/ConfigPanel';
 import { SlotRenderer } from '../components/SlotRenderer';
+import type { NavLink } from '../components/variants/navbar/types';
 
 const GITHUB_URL = 'https://github.com/thinkdj/ottabase';
 
-const NAVBAR_DATA = {
-    title: 'Ottabase',
-    githubUrl: GITHUB_URL,
-};
+const BASE_NAVBAR_LINKS: NavLink[] = [
+    { href: '/', label: 'Home' },
+    { href: '/about', label: 'About' },
+    { href: '/theme-demo', label: 'Themes' },
+];
 
 const FOOTER_DATA = {
     siteName: 'Ottabase',
@@ -21,10 +23,40 @@ const FOOTER_DATA = {
     ],
 };
 
-export function LayoutShell({ children }: { children: React.ReactNode }) {
+/** Merge exposed CMS pages into navbar links, deduplicating by href. */
+export function mergeNavLinks(baseLinks: NavLink[], exposedPages: { slug: string; title: string }[]): NavLink[] {
+    const pageLinks: NavLink[] = exposedPages.map((p) => ({
+        href: `/page/${p.slug}`,
+        label: p.title,
+    }));
+    const seen = new Set(baseLinks.map((l) => l.href));
+    const merged = [...baseLinks];
+    for (const link of pageLinks) {
+        if (!seen.has(link.href)) {
+            seen.add(link.href);
+            merged.push(link);
+        }
+    }
+    return merged;
+}
+
+export interface LayoutShellProps {
+    children: React.ReactNode;
+    /** Exposed pages from the CMS, passed from server layout. */
+    exposedPages?: { slug: string; title: string }[];
+}
+
+export function LayoutShell({ children, exposedPages = [] }: LayoutShellProps) {
+    const navbarLinks = mergeNavLinks(BASE_NAVBAR_LINKS, exposedPages);
+    const navbarData = {
+        title: 'Ottabase',
+        githubUrl: GITHUB_URL,
+        links: navbarLinks.length > 0 ? navbarLinks : undefined,
+    };
+
     return (
         <>
-            <SlotRenderer slot="navbar" data={NAVBAR_DATA} />
+            <SlotRenderer slot="navbar" data={navbarData} />
             <main className="flex-1">{children}</main>
             <SlotRenderer slot="footer" data={FOOTER_DATA} />
             <ConfigPanel />
diff --git a/apps/ottabase-template-app-nextjs-homepage/app/layout.tsx b/apps/ottabase-template-app-nextjs-homepage/app/layout.tsx
index 173a78777..adc3ed82f 100644
--- a/apps/ottabase-template-app-nextjs-homepage/app/layout.tsx
+++ b/apps/ottabase-template-app-nextjs-homepage/app/layout.tsx
@@ -1,5 +1,6 @@
 import { buildCriticalCSS } from '@ottabase/brand-engine';
 import type { Metadata } from 'next';
+import { fetchExposedPages } from '../lib/api';
 import { generateBrandConfig } from '../lib/brand-server';
 import './globals.css';
 import { LayoutShell } from './layout-shell';
@@ -13,7 +14,7 @@ export const metadata: Metadata = {
     authors: [{ name: 'Ottabase' }],
 };
 
-export default function RootLayout({ children }: { children: React.ReactNode }) {
+export default async function RootLayout({ children }: { children: React.ReactNode }) {
     // Generate brand config server-side (SSR)
     // Note: Using 'light' for initial SSR. BrandProvider will handle dynamic theme switching on client.
     const brandConfig = generateBrandConfig('light');
@@ -22,6 +23,9 @@ export default function RootLayout({ children }: { children: React.ReactNode })
     // Generate critical CSS for SSR (prevents FOUC)
     const criticalCSS = buildCriticalCSS(theme);
 
+    // Fetch exposed CMS pages for navbar
+    const exposedPages = await fetchExposedPages();
+
     return (
         <html lang="en" suppressHydrationWarning>
             <head>
@@ -34,7 +38,7 @@ export default function RootLayout({ children }: { children: React.ReactNode })
             </head>
             <body className="flex min-h-screen flex-col bg-background text-foreground">
                 <Providers initialBrandConfig={brandConfig}>
-                    <LayoutShell>{children}</LayoutShell>
+                    <LayoutShell exposedPages={exposedPages}>{children}</LayoutShell>
                 </Providers>
             </body>
         </html>
diff --git a/apps/ottabase-template-app-nextjs-homepage/app/page/[slug]/page-content.tsx b/apps/ottabase-template-app-nextjs-homepage/app/page/[slug]/page-content.tsx
new file mode 100644
index 000000000..8d16b50f8
--- /dev/null
+++ b/apps/ottabase-template-app-nextjs-homepage/app/page/[slug]/page-content.tsx
@@ -0,0 +1,37 @@
+'use client';
+
+import { Blocks, customRenderers, defaultEJSRConfigs } from '@ottabase/ottarenderer';
+import '@ottabase/ottarenderer/styles';
+import type { PageData } from '../../../lib/api';
+
+export function PageContent({ page }: { page: PageData }) {
+    const hasContent = page.content?.blocks && page.content.blocks.length > 0;
+
+    return (
+        <article className="mx-auto max-w-4xl px-4 py-12">
+            <header className="mb-8">
+                <h1 className="text-4xl font-bold text-foreground md:text-5xl">{page.title}</h1>
+                {page.excerpt && <p className="mt-4 text-lg text-muted-foreground">{page.excerpt}</p>}
+            </header>
+
+            {page.heroImage?.url && (
+                <div className="mb-8 overflow-hidden rounded-lg">
+                    <img
+                        src={page.heroImage.url}
+                        alt={page.heroImage.alt || page.title}
+                        className="w-full object-cover"
+                    />
+                    {page.heroImage.caption && (
+                        <p className="mt-2 text-center text-sm text-muted-foreground">{page.heroImage.caption}</p>
+                    )}
+                </div>
+            )}
+
+            {hasContent && (
+                <div className="prose prose-slate dark:prose-invert max-w-none">
+                    <Blocks data={page.content!} renderers={customRenderers} config={defaultEJSRConfigs} />
+                </div>
+            )}
+        </article>
+    );
+}
diff --git a/apps/ottabase-template-app-nextjs-homepage/app/page/[slug]/page.tsx b/apps/ottabase-template-app-nextjs-homepage/app/page/[slug]/page.tsx
new file mode 100644
index 000000000..9a04f05d3
--- /dev/null
+++ b/apps/ottabase-template-app-nextjs-homepage/app/page/[slug]/page.tsx
@@ -0,0 +1,26 @@
+import type { Metadata } from 'next';
+import { notFound } from 'next/navigation';
+import { fetchPageBySlug } from '../../../lib/api';
+import { PageContent } from './page-content';
+
+interface PageProps {
+    params: Promise<{ slug: string }>;
+}
+
+export async function generateMetadata({ params }: PageProps): Promise<Metadata> {
+    const { slug } = await params;
+    const page = await fetchPageBySlug(slug);
+    if (!page) return { title: 'Not Found' };
+    return {
+        title: page.seoMeta?.title || page.title,
+        description: page.seoMeta?.description || page.excerpt || undefined,
+        keywords: page.seoMeta?.keywords,
+    };
+}
+
+export default async function CmsPage({ params }: PageProps) {
+    const { slug } = await params;
+    const page = await fetchPageBySlug(slug);
+    if (!page) notFound();
+    return <PageContent page={page} />;
+}
diff --git a/apps/ottabase-template-app-nextjs-homepage/lib/api.ts b/apps/ottabase-template-app-nextjs-homepage/lib/api.ts
new file mode 100644
index 000000000..0d597ccfa
--- /dev/null
+++ b/apps/ottabase-template-app-nextjs-homepage/lib/api.ts
@@ -0,0 +1,86 @@
+/**
+ * API helpers for fetching data from the Ottabase worker backend.
+ *
+ * Requires NEXT_PUBLIC_API_URL to be set (e.g. http://localhost:3004).
+ */
+
+const API_URL = process.env.NEXT_PUBLIC_API_URL ?? '';
+
+/** EditorJS block data shape */
+export interface EditorJSData {
+    time?: number;
+    blocks: Array<{
+        id?: string;
+        type: string;
+        data: Record<string, unknown>;
+    }>;
+    version?: string;
+}
+
+/** Public page data returned by /api/blog/pages/by-slug/:slug */
+export interface PageData {
+    id: string;
+    title: string;
+    slug: string;
+    excerpt: string | null;
+    content: EditorJSData | null;
+    contentType: string;
+    status: string;
+    heroImage: {
+        url: string;
+        alt?: string;
+        caption?: string;
+    } | null;
+    seoMeta: {
+        title?: string;
+        description?: string;
+        keywords?: string[];
+    } | null;
+    authorName: string | null;
+    publishedAt: string | null;
+    createdAt: string;
+    updatedAt: string;
+}
+
+/** Exposed page link for homepage navbar */
+export interface ExposedPage {
+    slug: string;
+    title: string;
+}
+
+/**
+ * Fetch a published page by slug from the worker API.
+ * Returns null if not found or on error.
+ */
+export async function fetchPageBySlug(slug: string): Promise<PageData | null> {
+    if (!API_URL) return null;
+    try {
+        const res = await fetch(`${API_URL}/api/blog/pages/by-slug/${encodeURIComponent(slug)}`, {
+            next: { revalidate: 60 },
+        });
+        if (!res.ok) return null;
+        const data = await res.json();
+        if (data.contentType !== 'page') return null;
+        return data as PageData;
+    } catch {
+        return null;
+    }
+}
+
+/**
+ * Fetch exposed pages for the homepage navbar.
+ * Returns an empty array on error so the homepage never hard-fails.
+ */
+export async function fetchExposedPages(): Promise<ExposedPage[]> {
+    if (!API_URL) return [];
+    try {
+        const res = await fetch(`${API_URL}/api/blog/pages/exposed`, {
+            next: { revalidate: 60 },
+        });
+        if (!res.ok) return [];
+        const data = await res.json();
+        return Array.isArray(data.exposedPages) ? data.exposedPages : [];
+    } catch {
+        return [];
+    }
+}
diff --git a/apps/ottabase-template-app-nextjs-homepage/package.json b/apps/ottabase-template-app-nextjs-homepage/package.json
index 76ebd4d44..ea453c28f 100644
--- a/apps/ottabase-template-app-nextjs-homepage/package.json
+++ b/apps/ottabase-template-app-nextjs-homepage/package.json
@@ -22,6 +22,7 @@
         "@ottabase/brand-engine-react": "workspace:*",
         "@ottabase/config": "workspace:*",
         "@ottabase/ottalayout": "workspace:*",
+        "@ottabase/ottarenderer": "workspace:*",
         "@ottabase/ui-components": "workspace:*",
         "@ottabase/ui-shadcn": "workspace:*",
         "@radix-ui/react-slot": "^1.1.1",
diff --git a/packages/ottablog/src/__tests__/types.test.ts b/packages/ottablog/src/__tests__/types.test.ts
index 4acc1afd2..98c0a2b4c 100644
--- a/packages/ottablog/src/__tests__/types.test.ts
+++ b/packages/ottablog/src/__tests__/types.test.ts
@@ -1,5 +1,14 @@
 import { describe, expect, it } from 'vitest';
-import { calculateReadingTime, extractExcerpt, generateSlug, formatDate, formatShortDate } from '../types';
+import {
+    BLOG_FEED_CONTENT_TYPES,
+    CONTENT_TYPES,
+    calculateReadingTime,
+    extractExcerpt,
+    formatDate,
+    formatShortDate,
+    generateSlug,
+} from '../types';
+import type { ContentType } from '../types';
 
 describe('ottablog helpers', () => {
     describe('generateSlug', () => {
@@ -108,4 +117,45 @@ describe('ottablog helpers', () => {
             expect(formatted).toMatch(/Dec 25, 2024/);
         });
     });
+
+    describe('CONTENT_TYPES', () => {
+        it('includes all 6 content types', () => {
+            const keys = Object.keys(CONTENT_TYPES);
+            expect(keys).toEqual(['blog', 'changelog', 'docs', 'news', 'announcement', 'page']);
+        });
+
+        it('page content type has correct metadata', () => {
+            expect(CONTENT_TYPES.page).toEqual({
+                label: 'Page',
+                description: 'Static/marketing page managed via CMS',
+            });
+        });
+
+        it('every ContentType key has label and description', () => {
+            for (const [, meta] of Object.entries(CONTENT_TYPES)) {
+                expect(meta).toHaveProperty('label');
+                expect(meta).toHaveProperty('description');
+                expect(typeof meta.label).toBe('string');
+                expect(typeof meta.description).toBe('string');
+            }
+        });
+    });
+
+    describe('BLOG_FEED_CONTENT_TYPES', () => {
+        it('includes blog, docs, news, announcement', () => {
+            expect(BLOG_FEED_CONTENT_TYPES).toEqual(['blog', 'docs', 'news', 'announcement']);
+        });
+
+        it('excludes changelog and page', () => {
+            expect(BLOG_FEED_CONTENT_TYPES).not.toContain('changelog');
+            expect(BLOG_FEED_CONTENT_TYPES).not.toContain('page');
+        });
+
+        it('is a subset of CONTENT_TYPES keys', () => {
+            const allTypes = Object.keys(CONTENT_TYPES);
+            for (const type of BLOG_FEED_CONTENT_TYPES) {
+                expect(allTypes).toContain(type);
+            }
+        });
+    });
 });
diff --git a/pnpm-lock.yaml b/pnpm-lock.yaml
index 4f191026a..e699ee2ee 100644
--- a/pnpm-lock.yaml
+++ b/pnpm-lock.yaml
@@ -362,6 +362,9 @@ importers:
       '@ottabase/ottalayout':
         specifier: workspace:*
         version: link:../../packages/ottalayout
+      '@ottabase/ottarenderer':
+        specifier: workspace:*
+        version: link:../../packages/ottarenderer
       '@ottabase/ui-components':
         specifier: workspace:*
         version: link:../../packages/ui-components

From 72478b60ffcf079ef11bf2d4e32b0ed8749b2112 Mon Sep 17 00:00:00 2001
From: "copilot-swe-agent[bot]" <198982749+Copilot@users.noreply.github.com>
Date: Mon, 30 Mar 2026 18:07:12 +0000
Subject: [PATCH 04/19] fix: correct import path in (site)/page.tsx for route
 group, update ottablog README docs

Agent-Logs-Url: https://github.com/thinkdj/ottabase/sessions/046b035e-9b57-4779-b4ad-6fa561dfc03b
---
 .../app/(site)/page.tsx                       |  2 +-
 packages/ottablog/README.md                   | 23 ++++++++++++++++++-
 .../ottablog/src/__tests__/models.test.ts     | 23 +++++++++++++++++++
 3 files changed, 46 insertions(+), 2 deletions(-)

diff --git a/apps/ottabase-template-app-nextjs-homepage/app/(site)/page.tsx b/apps/ottabase-template-app-nextjs-homepage/app/(site)/page.tsx
index 4dfb59eb5..e772ba669 100644
--- a/apps/ottabase-template-app-nextjs-homepage/app/(site)/page.tsx
+++ b/apps/ottabase-template-app-nextjs-homepage/app/(site)/page.tsx
@@ -1,7 +1,7 @@
 'use client';
 
 import { Github, Palette, Rocket } from 'lucide-react';
-import { SlotRenderer } from '../components/SlotRenderer';
+import { SlotRenderer } from '../../components/SlotRenderer';
 
 /**
  * Homepage content data — single source of truth.
diff --git a/packages/ottablog/README.md b/packages/ottablog/README.md
index 6bc75504e..445ea7212 100644
--- a/packages/ottablog/README.md
+++ b/packages/ottablog/README.md
@@ -102,7 +102,7 @@ const post = await Post.create({
     content: {
         /* EditorJS JSON */
     },
-    contentType: 'blog', // blog, changelog, docs, news, announcement
+    contentType: 'blog', // blog, changelog, docs, news, announcement, page
     status: 'published', // draft, published, archived, scheduled
     categoryId: 'cat-123',
     seriesId: 'series-123',
@@ -164,6 +164,7 @@ post.generateExcerpt(); // Auto-generate from content
 - `readingTimeMinutes`, `wordCount` - Auto-calculated stats
 - `viewCount` - View/hit counter (incremented via `trackView()`)
 - `isFeatured` - Pin to top
+- `exposeToHomepage` - Show page link in marketing homepage navbar (only for `page` content type)
 - `allowComments` - Enable comments
 - `publishAt`, `publishedAt`, `postedAt` - Dates
 - `appId` - Multi-app identifier
@@ -375,6 +376,7 @@ const customCats = await PostCategory.where({
 - `docs` - Documentation
 - `changelog` - Change logs
 - `announcement` - Announcements
+- `page` - Static/marketing pages managed via CMS
 - Custom types supported
 
 ## Relationships
@@ -508,6 +510,25 @@ GET /api/blog/posts/by-slug/{slug}
 Returns a single post with tags, categories (via junction), and series title. View tracking is opt-in (call
 `trackView()` explicitly to avoid D1 write costs per page view).
 
+> **Note:** Returns 404 for `changelog` and `page` content types — they have dedicated endpoints.
+
+### Page by Slug
+
+```
+GET /api/blog/pages/by-slug/{slug}
+```
+
+Returns a published page (`contentType: 'page'`). Used by the marketing homepage to render CMS-managed static pages.
+
+### Exposed Pages
+
+```
+GET /api/blog/pages/exposed
+```
+
+Returns `{ exposedPages: [{ slug, title }] }` — all published pages with `exposeToHomepage: true`, sorted by title. Used
+by the marketing homepage to build navbar links. Returns `{ exposedPages: [] }` on failure.
+
 ### Related Posts
 
 ```
diff --git a/packages/ottablog/src/__tests__/models.test.ts b/packages/ottablog/src/__tests__/models.test.ts
index bbe7e0bab..7ca93c736 100644
--- a/packages/ottablog/src/__tests__/models.test.ts
+++ b/packages/ottablog/src/__tests__/models.test.ts
@@ -65,6 +65,29 @@ describe('ottablog models', () => {
             expect(fields.viewCount.editable).toBe(false);
             expect(fields.viewCount.sortable).toBe(true);
         });
+
+        it('should have exposeToHomepage in casts', () => {
+            expect(Post.casts).toHaveProperty('exposeToHomepage');
+            expect(Post.casts.exposeToHomepage).toBe('boolean');
+        });
+
+        it('should have exposeToHomepage in writable fields', () => {
+            expect(Post.writable.create).toContain('exposeToHomepage');
+            expect(Post.writable.update).toContain('exposeToHomepage');
+        });
+
+        it('should have exposeToHomepage field metadata', () => {
+            const fields = Post.getFields();
+            expect(fields).toHaveProperty('exposeToHomepage');
+            expect(fields.exposeToHomepage.type).toBe('boolean');
+            expect(fields.exposeToHomepage.editable).toBe(true);
+            expect(fields.exposeToHomepage.filterable).toBe(true);
+        });
+
+        it('should have exposeToHomepage default to false', () => {
+            const defaults = (Post as any).defaults;
+            expect(defaults.exposeToHomepage).toBe(false);
+        });
     });
 
     describe('PostCategory model', () => {

From 4db1801cd2fd6fc788ef903eaa326078c92a56db Mon Sep 17 00:00:00 2001
From: "copilot-swe-agent[bot]" <198982749+Copilot@users.noreply.github.com>
Date: Mon, 30 Mar 2026 18:43:09 +0000
Subject: [PATCH 05/19] feat: add homepage DB models (Section, Feature, Action,
 DisplaySettings) + GET /api/homepage/data

Agent-Logs-Url: https://github.com/thinkdj/ottabase/sessions/b9bee764-b52d-4fdc-a63f-1aa2b58b0afb
---
 .../app/layout-shell.tsx                      |  73 ++++++-
 .../app/layout.tsx                            |  10 +-
 .../lib/api.ts                                |  60 ++++++
 .../ottabase/db/schemas-helper.ts             |  12 ++
 .../ottabase/models/HomepageAction.schema.ts  |  34 ++++
 .../ottabase/models/HomepageAction.ts         | 104 ++++++++++
 .../models/HomepageDisplaySettings.schema.ts  |  38 ++++
 .../models/HomepageDisplaySettings.ts         | 101 ++++++++++
 .../ottabase/models/HomepageFeature.schema.ts |  30 +++
 .../ottabase/models/HomepageFeature.ts        |  92 +++++++++
 .../ottabase/models/HomepageSection.schema.ts |  40 ++++
 .../ottabase/models/HomepageSection.ts        | 108 ++++++++++
 .../worker/lib/db-utils.ts                    |   6 +-
 .../worker/routes/homepage.ts                 | 190 ++++++++++++++++++
 .../worker/routes/router.ts                   |   6 +
 15 files changed, 897 insertions(+), 7 deletions(-)
 create mode 100644 apps/ottabase-template-app-tanstack/ottabase/models/HomepageAction.schema.ts
 create mode 100644 apps/ottabase-template-app-tanstack/ottabase/models/HomepageAction.ts
 create mode 100644 apps/ottabase-template-app-tanstack/ottabase/models/HomepageDisplaySettings.schema.ts
 create mode 100644 apps/ottabase-template-app-tanstack/ottabase/models/HomepageDisplaySettings.ts
 create mode 100644 apps/ottabase-template-app-tanstack/ottabase/models/HomepageFeature.schema.ts
 create mode 100644 apps/ottabase-template-app-tanstack/ottabase/models/HomepageFeature.ts
 create mode 100644 apps/ottabase-template-app-tanstack/ottabase/models/HomepageSection.schema.ts
 create mode 100644 apps/ottabase-template-app-tanstack/ottabase/models/HomepageSection.ts
 create mode 100644 apps/ottabase-template-app-tanstack/worker/routes/homepage.ts

diff --git a/apps/ottabase-template-app-nextjs-homepage/app/layout-shell.tsx b/apps/ottabase-template-app-nextjs-homepage/app/layout-shell.tsx
index 0f7939a6e..11f6b002a 100644
--- a/apps/ottabase-template-app-nextjs-homepage/app/layout-shell.tsx
+++ b/apps/ottabase-template-app-nextjs-homepage/app/layout-shell.tsx
@@ -2,6 +2,7 @@
 
 import { ConfigPanel } from '../components/ConfigPanel';
 import { SlotRenderer } from '../components/SlotRenderer';
+import type { HomepageDataPayload } from '../lib/api';
 import type { NavLink } from '../components/variants/navbar/types';
 
 const GITHUB_URL = 'https://github.com/thinkdj/ottabase';
@@ -40,25 +41,93 @@ export function mergeNavLinks(baseLinks: NavLink[], exposedPages: { slug: string
     return merged;
 }
 
+/**
+ * Build slot data overrides from the homepage API sections.
+ * Maps section data to the SlotRenderer data contracts.
+ */
+function buildSlotDataFromSections(sections: HomepageDataPayload['sections']) {
+    const dataBySlot: Record<string, Record<string, unknown>> = {};
+    for (const section of sections) {
+        const slot = section.slot;
+        if (slot === 'hero') {
+            dataBySlot[slot] = {
+                title: section.title ?? '',
+                subtitle: section.subtitle ?? undefined,
+                body: section.body ?? undefined,
+                actions: section.actions.map((a) => ({
+                    label: a.label,
+                    href: a.href,
+                    variant: a.variant ?? 'default',
+                    external: a.external,
+                })),
+            };
+        } else if (slot === 'features') {
+            dataBySlot[slot] = {
+                title: section.title ?? undefined,
+                features: section.features,
+            };
+        } else if (slot === 'cta') {
+            dataBySlot[slot] = {
+                title: section.title ?? '',
+                description: section.subtitle ?? undefined,
+                actions: section.actions.map((a) => ({
+                    label: a.label,
+                    href: a.href,
+                    variant: a.variant ?? 'default',
+                    external: a.external,
+                })),
+            };
+        } else if (slot === 'about') {
+            dataBySlot[slot] = {
+                title: section.title ?? undefined,
+                description: section.subtitle ?? undefined,
+                githubUrl: section.githubUrl ?? undefined,
+            };
+        } else if (slot === 'navbar') {
+            dataBySlot[slot] = {
+                title: section.title ?? 'Ottabase',
+                githubUrl: section.githubUrl ?? undefined,
+            };
+        } else if (slot === 'footer') {
+            dataBySlot[slot] = {
+                siteName: section.title ?? 'Ottabase',
+                tagline: section.subtitle ?? undefined,
+            };
+        }
+    }
+    return dataBySlot;
+}
+
 export interface LayoutShellProps {
     children: React.ReactNode;
     /** Exposed pages from the CMS, passed from server layout. */
     exposedPages?: { slug: string; title: string }[];
+    /** Full homepage data payload from the API. */
+    homepageData?: HomepageDataPayload;
 }
 
-export function LayoutShell({ children, exposedPages = [] }: LayoutShellProps) {
+export function LayoutShell({ children, exposedPages = [], homepageData }: LayoutShellProps) {
     const navbarLinks = mergeNavLinks(BASE_NAVBAR_LINKS, exposedPages);
+
+    // Build slot data overrides from DB sections (if available)
+    const dbSlotData = homepageData?.sections?.length ? buildSlotDataFromSections(homepageData.sections) : {};
+
     const navbarData = {
         title: 'Ottabase',
         githubUrl: GITHUB_URL,
+        // Override with DB data if present (title/githubUrl from navbar section)
+        ...(dbSlotData.navbar ?? {}),
+        // Always include merged links (DB navbar data should not override links)
         links: navbarLinks.length > 0 ? navbarLinks : undefined,
     };
 
+    const footerData = dbSlotData.footer ? { ...FOOTER_DATA, ...dbSlotData.footer } : FOOTER_DATA;
+
     return (
         <>
             <SlotRenderer slot="navbar" data={navbarData} />
             <main className="flex-1">{children}</main>
-            <SlotRenderer slot="footer" data={FOOTER_DATA} />
+            <SlotRenderer slot="footer" data={footerData} />
             <ConfigPanel />
         </>
     );
diff --git a/apps/ottabase-template-app-nextjs-homepage/app/layout.tsx b/apps/ottabase-template-app-nextjs-homepage/app/layout.tsx
index adc3ed82f..7c01d00a5 100644
--- a/apps/ottabase-template-app-nextjs-homepage/app/layout.tsx
+++ b/apps/ottabase-template-app-nextjs-homepage/app/layout.tsx
@@ -1,6 +1,6 @@
 import { buildCriticalCSS } from '@ottabase/brand-engine';
 import type { Metadata } from 'next';
-import { fetchExposedPages } from '../lib/api';
+import { fetchHomepageData } from '../lib/api';
 import { generateBrandConfig } from '../lib/brand-server';
 import './globals.css';
 import { LayoutShell } from './layout-shell';
@@ -23,8 +23,8 @@ export default async function RootLayout({ children }: { children: React.ReactNo
     // Generate critical CSS for SSR (prevents FOUC)
     const criticalCSS = buildCriticalCSS(theme);
 
-    // Fetch exposed CMS pages for navbar
-    const exposedPages = await fetchExposedPages();
+    // Fetch full homepage data (sections, display settings, exposed pages) from the worker API
+    const homepageData = await fetchHomepageData();
 
     return (
         <html lang="en" suppressHydrationWarning>
@@ -38,7 +38,9 @@ export default async function RootLayout({ children }: { children: React.ReactNo
             </head>
             <body className="flex min-h-screen flex-col bg-background text-foreground">
                 <Providers initialBrandConfig={brandConfig}>
-                    <LayoutShell exposedPages={exposedPages}>{children}</LayoutShell>
+                    <LayoutShell exposedPages={homepageData.exposedPages} homepageData={homepageData}>
+                        {children}
+                    </LayoutShell>
                 </Providers>
             </body>
         </html>
diff --git a/apps/ottabase-template-app-nextjs-homepage/lib/api.ts b/apps/ottabase-template-app-nextjs-homepage/lib/api.ts
index 0d597ccfa..cc9b8cd7e 100644
--- a/apps/ottabase-template-app-nextjs-homepage/lib/api.ts
+++ b/apps/ottabase-template-app-nextjs-homepage/lib/api.ts
@@ -48,6 +48,38 @@ export interface ExposedPage {
     title: string;
 }
 
+/** Homepage section from the public API */
+export interface HomepageSectionPayload {
+    id: string;
+    slot: string;
+    title: string | null;
+    subtitle: string | null;
+    body: string | null;
+    githubUrl: string | null;
+    sortOrder: number;
+    features: Array<{ title: string; description: string }>;
+    actions: Array<{
+        label: string;
+        href: string;
+        variant: string | null;
+        external: boolean;
+    }>;
+}
+
+/** Homepage display settings from the public API */
+export interface HomepageDisplayPayload {
+    variantBySlot: Record<string, string> | null;
+    themePreset: string | null;
+    fallbackThemePresetId: string | null;
+}
+
+/** Full homepage data payload from GET /api/homepage/data */
+export interface HomepageDataPayload {
+    sections: HomepageSectionPayload[];
+    display: HomepageDisplayPayload;
+    exposedPages: ExposedPage[];
+}
+
 /**
  * Fetch a published page by slug from the worker API.
  * Returns null if not found or on error.
@@ -67,6 +99,34 @@ export async function fetchPageBySlug(slug: string): Promise<PageData | null> {
     }
 }
 
+/**
+ * Fetch the full homepage data payload from the worker API.
+ * Includes sections (with features + actions), display settings, and exposed pages.
+ * Returns safe defaults on error so the homepage never hard-fails.
+ */
+export async function fetchHomepageData(): Promise<HomepageDataPayload> {
+    const fallback: HomepageDataPayload = {
+        sections: [],
+        display: { variantBySlot: null, themePreset: null, fallbackThemePresetId: null },
+        exposedPages: [],
+    };
+    if (!API_URL) return fallback;
+    try {
+        const res = await fetch(`${API_URL}/api/homepage/data`, {
+            next: { revalidate: 60 },
+        });
+        if (!res.ok) return fallback;
+        const data = await res.json();
+        return {
+            sections: Array.isArray(data.sections) ? data.sections : [],
+            display: data.display ?? fallback.display,
+            exposedPages: Array.isArray(data.exposedPages) ? data.exposedPages : [],
+        };
+    } catch {
+        return fallback;
+    }
+}
+
 /**
  * Fetch exposed pages for the homepage navbar.
  * Returns an empty array on error so the homepage never hard-fails.
diff --git a/apps/ottabase-template-app-tanstack/ottabase/db/schemas-helper.ts b/apps/ottabase-template-app-tanstack/ottabase/db/schemas-helper.ts
index 0bd67a87f..23df84d12 100644
--- a/apps/ottabase-template-app-tanstack/ottabase/db/schemas-helper.ts
+++ b/apps/ottabase-template-app-tanstack/ottabase/db/schemas-helper.ts
@@ -34,6 +34,10 @@ import {
 } from '@ottabase/ottaorm';
 import { getEnabledPackageTables } from '../config.migrations';
 import { changelogEntriesTable } from '../models/ChangelogEntry';
+import { homepageActionsTable } from '../models/HomepageAction';
+import { homepageDisplaySettingsTable } from '../models/HomepageDisplaySettings';
+import { homepageFeaturesTable } from '../models/HomepageFeature';
+import { homepageSectionsTable } from '../models/HomepageSection';
 import { todosTable } from '../models/Todo';
 
 /**
@@ -63,6 +67,10 @@ export function getAllSchemas() {
     const appTables = {
         changelogEntriesTable,
         todosTable,
+        homepageSectionsTable,
+        homepageFeaturesTable,
+        homepageActionsTable,
+        homepageDisplaySettingsTable,
     };
 
     // 3. Package schemas from enabled packages (ottablog, shortlinks, referrals, etc.)
@@ -105,6 +113,10 @@ export function getSchemaSummary() {
     const appTables = {
         changelogEntriesTable,
         todosTable,
+        homepageSectionsTable,
+        homepageFeaturesTable,
+        homepageActionsTable,
+        homepageDisplaySettingsTable,
     };
 
     const packageTables = getEnabledPackageTables();
diff --git a/apps/ottabase-template-app-tanstack/ottabase/models/HomepageAction.schema.ts b/apps/ottabase-template-app-tanstack/ottabase/models/HomepageAction.schema.ts
new file mode 100644
index 000000000..e7a6cd572
--- /dev/null
+++ b/apps/ottabase-template-app-tanstack/ottabase/models/HomepageAction.schema.ts
@@ -0,0 +1,34 @@
+// ============================================================
+// Homepage Action table (App-specific)
+// ============================================================
+
+import { integer, sqliteTable, text } from 'drizzle-orm/sqlite-core';
+import { homepageSectionsTable } from './HomepageSection.schema';
+
+export const homepageActionsTable = sqliteTable('homepage_actions', {
+    id: text('id')
+        .primaryKey()
+        .$defaultFn(() => crypto.randomUUID()),
+    /** Parent section (hero, cta, about, etc.) */
+    sectionId: text('section_id')
+        .notNull()
+        .references(() => homepageSectionsTable.id, { onDelete: 'cascade' }),
+    label: text('label').notNull(),
+    href: text('href').notNull(),
+    /** Button style variant: default, secondary, outline, ghost */
+    variant: text('variant').default('default'),
+    /** Whether the link opens in a new tab */
+    external: integer('external', { mode: 'boolean' }).default(false),
+    /** Display order */
+    sortOrder: integer('sort_order').notNull().default(0),
+    createdAt: integer('created_at')
+        .$defaultFn(() => Date.now())
+        .notNull(),
+    updatedAt: integer('updated_at')
+        .$defaultFn(() => Date.now())
+        .$onUpdateFn(() => Date.now())
+        .notNull(),
+});
+
+export type HomepageActionRow = typeof homepageActionsTable.$inferSelect;
+export type NewHomepageActionRow = typeof homepageActionsTable.$inferInsert;
diff --git a/apps/ottabase-template-app-tanstack/ottabase/models/HomepageAction.ts b/apps/ottabase-template-app-tanstack/ottabase/models/HomepageAction.ts
new file mode 100644
index 000000000..d310e8080
--- /dev/null
+++ b/apps/ottabase-template-app-tanstack/ottabase/models/HomepageAction.ts
@@ -0,0 +1,104 @@
+// ============================================================
+// HomepageAction Model (App-specific fat model)
+// ============================================================
+
+import { BaseModel, ModelFields, type PackageType } from '@ottabase/ottaorm';
+import { homepageActionsTable } from './HomepageAction.schema';
+
+export { homepageActionsTable, type HomepageActionRow, type NewHomepageActionRow } from './HomepageAction.schema';
+
+/**
+ * A call-to-action button belonging to a homepage section (hero, cta, about, etc.).
+ */
+export class HomepageAction extends BaseModel {
+    static entity = 'homepage_actions';
+    static table = homepageActionsTable;
+    static primaryKey = 'id';
+    static packageName = 'app';
+    static packageType: PackageType = 'app';
+
+    static casts = {
+        external: 'boolean' as const,
+        sortOrder: 'number' as const,
+        createdAt: 'date' as const,
+        updatedAt: 'date' as const,
+    };
+
+    static writable = {
+        create: ['sectionId', 'label', 'href', 'variant', 'external', 'sortOrder'],
+        update: ['sectionId', 'label', 'href', 'variant', 'external', 'sortOrder'],
+    };
+
+    protected static fields: ModelFields = {
+        id: { type: 'id', primaryKey: true, editable: false, uiConfig: { label: 'ID' } },
+        sectionId: {
+            type: 'string',
+            editable: true,
+            filterable: true,
+            uiConfig: { label: 'Section', description: 'Parent section ID' },
+            formConfig: { visible: true, fieldType: 'input' },
+            tableConfig: { visible: true, colWidth: 200 },
+            validation: { rules: 'required', messages: { required: 'Section is required' } },
+        },
+        label: {
+            type: 'string',
+            editable: true,
+            searchable: true,
+            uiConfig: { label: 'Label', placeholder: 'Button text' },
+            formConfig: { visible: true, fieldType: 'input' },
+            tableConfig: { visible: true, colWidth: 'auto' },
+            validation: { rules: 'required', messages: { required: 'Label is required' } },
+        },
+        href: {
+            type: 'string',
+            editable: true,
+            uiConfig: { label: 'URL', placeholder: '/path or https://...' },
+            formConfig: { visible: true, fieldType: 'input' },
+            tableConfig: { visible: true, colWidth: 200 },
+            validation: { rules: 'required', messages: { required: 'URL is required' } },
+        },
+        variant: {
+            type: 'string',
+            editable: true,
+            filterable: true,
+            uiConfig: { label: 'Style variant', description: 'default, secondary, outline, ghost' },
+            formConfig: { visible: true, fieldType: 'select' },
+            tableConfig: { visible: true, colWidth: 120 },
+        },
+        external: {
+            type: 'boolean',
+            editable: true,
+            uiConfig: { label: 'External link', description: 'Opens in new tab' },
+            formConfig: { visible: true, fieldType: 'checkbox' },
+            tableConfig: { visible: true, colWidth: 100 },
+        },
+        sortOrder: {
+            type: 'number',
+            editable: true,
+            sortable: true,
+            uiConfig: { label: 'Sort Order' },
+            formConfig: { visible: true, fieldType: 'number' },
+            tableConfig: { visible: true, colWidth: 100 },
+        },
+        createdAt: {
+            type: 'date',
+            editable: false,
+            sortable: true,
+            uiConfig: { label: 'Created' },
+            tableConfig: { visible: false },
+        },
+        updatedAt: {
+            type: 'date',
+            editable: false,
+            sortable: true,
+            uiConfig: { label: 'Updated' },
+            tableConfig: { visible: false },
+        },
+    };
+
+    protected static validationRules = {
+        sectionId: { rules: 'required', fieldName: 'Section', messages: { required: 'Section is required' } },
+        label: { rules: 'required', fieldName: 'Label', messages: { required: 'Label is required' } },
+        href: { rules: 'required', fieldName: 'URL', messages: { required: 'URL is required' } },
+    };
+}
diff --git a/apps/ottabase-template-app-tanstack/ottabase/models/HomepageDisplaySettings.schema.ts b/apps/ottabase-template-app-tanstack/ottabase/models/HomepageDisplaySettings.schema.ts
new file mode 100644
index 000000000..4daef09b4
--- /dev/null
+++ b/apps/ottabase-template-app-tanstack/ottabase/models/HomepageDisplaySettings.schema.ts
@@ -0,0 +1,38 @@
+// ============================================================
+// Homepage Display Settings table (App-specific)
+// ============================================================
+
+import { integer, sqliteTable, text } from 'drizzle-orm/sqlite-core';
+
+/**
+ * Single-row settings table storing the full homepage display state:
+ * - Variant selections per slot (JSON matching HomepageConfig)
+ * - Active theme preset name
+ * - Fallback theme preset ID
+ */
+export const homepageDisplaySettingsTable = sqliteTable('homepage_display_settings', {
+    id: text('id')
+        .primaryKey()
+        .$defaultFn(() => 'default'),
+    /**
+     * JSON object mapping slot names to active variant IDs.
+     * Shape: Record<SlotName, string> e.g. { hero: 'centered', features: 'grid', ... }
+     */
+    variantBySlotJson: text('variant_by_slot_json', { mode: 'json' }).$type<Record<string, string>>(),
+    /** Active theme preset name (e.g. 'default', 'neo', 'crisp') */
+    themePreset: text('theme_preset').default('default'),
+    /** Fallback theme preset ID for SSR */
+    fallbackThemePresetId: text('fallback_theme_preset_id'),
+    /** Multi-app identifier */
+    appId: text('app_id'),
+    createdAt: integer('created_at')
+        .$defaultFn(() => Date.now())
+        .notNull(),
+    updatedAt: integer('updated_at')
+        .$defaultFn(() => Date.now())
+        .$onUpdateFn(() => Date.now())
+        .notNull(),
+});
+
+export type HomepageDisplaySettingsRow = typeof homepageDisplaySettingsTable.$inferSelect;
+export type NewHomepageDisplaySettingsRow = typeof homepageDisplaySettingsTable.$inferInsert;
diff --git a/apps/ottabase-template-app-tanstack/ottabase/models/HomepageDisplaySettings.ts b/apps/ottabase-template-app-tanstack/ottabase/models/HomepageDisplaySettings.ts
new file mode 100644
index 000000000..3c6522449
--- /dev/null
+++ b/apps/ottabase-template-app-tanstack/ottabase/models/HomepageDisplaySettings.ts
@@ -0,0 +1,101 @@
+// ============================================================
+// HomepageDisplaySettings Model (App-specific fat model)
+// ============================================================
+
+import { BaseModel, ModelFields, type PackageType } from '@ottabase/ottaorm';
+import { homepageDisplaySettingsTable } from './HomepageDisplaySettings.schema';
+
+export {
+    homepageDisplaySettingsTable,
+    type HomepageDisplaySettingsRow,
+    type NewHomepageDisplaySettingsRow,
+} from './HomepageDisplaySettings.schema';
+
+/**
+ * Single-row settings model for the homepage display state.
+ * Stores variant selections per slot and the active theme preset.
+ */
+export class HomepageDisplaySettings extends BaseModel {
+    static entity = 'homepage_display_settings';
+    static table = homepageDisplaySettingsTable;
+    static primaryKey = 'id';
+    static packageName = 'app';
+    static packageType: PackageType = 'app';
+
+    static casts = {
+        variantBySlotJson: 'json' as const,
+        createdAt: 'date' as const,
+        updatedAt: 'date' as const,
+    };
+
+    static writable = {
+        create: ['id', 'variantBySlotJson', 'themePreset', 'fallbackThemePresetId', 'appId'],
+        update: ['variantBySlotJson', 'themePreset', 'fallbackThemePresetId', 'appId'],
+    };
+
+    protected static defaults = {
+        themePreset: 'default',
+    };
+
+    protected static fields: ModelFields = {
+        id: { type: 'id', primaryKey: true, editable: false, uiConfig: { label: 'ID' } },
+        variantBySlotJson: {
+            type: 'json',
+            editable: true,
+            uiConfig: {
+                label: 'Variant selections',
+                description: 'JSON mapping slot names to variant IDs',
+            },
+            formConfig: { visible: true, fieldType: 'textarea' },
+            tableConfig: { visible: false },
+        },
+        themePreset: {
+            type: 'string',
+            editable: true,
+            uiConfig: { label: 'Theme preset', description: 'Active theme preset name' },
+            formConfig: { visible: true, fieldType: 'input' },
+            tableConfig: { visible: true, colWidth: 150 },
+        },
+        fallbackThemePresetId: {
+            type: 'string',
+            editable: true,
+            uiConfig: { label: 'Fallback theme', description: 'Theme preset for SSR fallback' },
+            formConfig: { visible: true, fieldType: 'input' },
+            tableConfig: { visible: false },
+        },
+        appId: {
+            type: 'string',
+            editable: true,
+            filterable: true,
+            uiConfig: { label: 'App ID' },
+            tableConfig: { visible: false },
+        },
+        createdAt: {
+            type: 'date',
+            editable: false,
+            sortable: true,
+            uiConfig: { label: 'Created' },
+            tableConfig: { visible: false },
+        },
+        updatedAt: {
+            type: 'date',
+            editable: false,
+            sortable: true,
+            uiConfig: { label: 'Updated' },
+            tableConfig: { visible: false },
+        },
+    };
+
+    /**
+     * Get or create the default settings row.
+     */
+    static async getOrCreateDefault(appId?: string | null): Promise<HomepageDisplaySettings> {
+        const where: Record<string, unknown> = { id: 'default' };
+        if (appId) where.appId = appId;
+
+        const existing = await this.first(where);
+        if (existing) return existing as HomepageDisplaySettings;
+
+        return (await this.create({ id: 'default', appId: appId ?? undefined })) as HomepageDisplaySettings;
+    }
+}
diff --git a/apps/ottabase-template-app-tanstack/ottabase/models/HomepageFeature.schema.ts b/apps/ottabase-template-app-tanstack/ottabase/models/HomepageFeature.schema.ts
new file mode 100644
index 000000000..64a4acf25
--- /dev/null
+++ b/apps/ottabase-template-app-tanstack/ottabase/models/HomepageFeature.schema.ts
@@ -0,0 +1,30 @@
+// ============================================================
+// Homepage Feature table (App-specific)
+// ============================================================
+
+import { integer, sqliteTable, text } from 'drizzle-orm/sqlite-core';
+import { homepageSectionsTable } from './HomepageSection.schema';
+
+export const homepageFeaturesTable = sqliteTable('homepage_features', {
+    id: text('id')
+        .primaryKey()
+        .$defaultFn(() => crypto.randomUUID()),
+    /** Parent section (typically the "features" slot) */
+    sectionId: text('section_id')
+        .notNull()
+        .references(() => homepageSectionsTable.id, { onDelete: 'cascade' }),
+    title: text('title').notNull(),
+    description: text('description').notNull(),
+    /** Display order */
+    sortOrder: integer('sort_order').notNull().default(0),
+    createdAt: integer('created_at')
+        .$defaultFn(() => Date.now())
+        .notNull(),
+    updatedAt: integer('updated_at')
+        .$defaultFn(() => Date.now())
+        .$onUpdateFn(() => Date.now())
+        .notNull(),
+});
+
+export type HomepageFeatureRow = typeof homepageFeaturesTable.$inferSelect;
+export type NewHomepageFeatureRow = typeof homepageFeaturesTable.$inferInsert;
diff --git a/apps/ottabase-template-app-tanstack/ottabase/models/HomepageFeature.ts b/apps/ottabase-template-app-tanstack/ottabase/models/HomepageFeature.ts
new file mode 100644
index 000000000..61545a227
--- /dev/null
+++ b/apps/ottabase-template-app-tanstack/ottabase/models/HomepageFeature.ts
@@ -0,0 +1,92 @@
+// ============================================================
+// HomepageFeature Model (App-specific fat model)
+// ============================================================
+
+import { BaseModel, ModelFields, type PackageType } from '@ottabase/ottaorm';
+import { homepageFeaturesTable } from './HomepageFeature.schema';
+
+export { homepageFeaturesTable, type HomepageFeatureRow, type NewHomepageFeatureRow } from './HomepageFeature.schema';
+
+/**
+ * A feature item belonging to a homepage section (typically the "features" slot).
+ */
+export class HomepageFeature extends BaseModel {
+    static entity = 'homepage_features';
+    static table = homepageFeaturesTable;
+    static primaryKey = 'id';
+    static packageName = 'app';
+    static packageType: PackageType = 'app';
+
+    static casts = {
+        sortOrder: 'number' as const,
+        createdAt: 'date' as const,
+        updatedAt: 'date' as const,
+    };
+
+    static writable = {
+        create: ['sectionId', 'title', 'description', 'sortOrder'],
+        update: ['sectionId', 'title', 'description', 'sortOrder'],
+    };
+
+    protected static fields: ModelFields = {
+        id: { type: 'id', primaryKey: true, editable: false, uiConfig: { label: 'ID' } },
+        sectionId: {
+            type: 'string',
+            editable: true,
+            filterable: true,
+            uiConfig: { label: 'Section', description: 'Parent section ID' },
+            formConfig: { visible: true, fieldType: 'input' },
+            tableConfig: { visible: true, colWidth: 200 },
+            validation: { rules: 'required', messages: { required: 'Section is required' } },
+        },
+        title: {
+            type: 'string',
+            editable: true,
+            searchable: true,
+            uiConfig: { label: 'Title', placeholder: 'Feature name' },
+            formConfig: { visible: true, fieldType: 'input' },
+            tableConfig: { visible: true, colWidth: 'auto' },
+            validation: { rules: 'required', messages: { required: 'Title is required' } },
+        },
+        description: {
+            type: 'string',
+            editable: true,
+            uiConfig: { label: 'Description' },
+            formConfig: { visible: true, fieldType: 'textarea' },
+            tableConfig: { visible: true, colWidth: 'auto' },
+            validation: { rules: 'required', messages: { required: 'Description is required' } },
+        },
+        sortOrder: {
+            type: 'number',
+            editable: true,
+            sortable: true,
+            uiConfig: { label: 'Sort Order' },
+            formConfig: { visible: true, fieldType: 'number' },
+            tableConfig: { visible: true, colWidth: 100 },
+        },
+        createdAt: {
+            type: 'date',
+            editable: false,
+            sortable: true,
+            uiConfig: { label: 'Created' },
+            tableConfig: { visible: false },
+        },
+        updatedAt: {
+            type: 'date',
+            editable: false,
+            sortable: true,
+            uiConfig: { label: 'Updated' },
+            tableConfig: { visible: false },
+        },
+    };
+
+    protected static validationRules = {
+        sectionId: { rules: 'required', fieldName: 'Section', messages: { required: 'Section is required' } },
+        title: { rules: 'required', fieldName: 'Title', messages: { required: 'Title is required' } },
+        description: {
+            rules: 'required',
+            fieldName: 'Description',
+            messages: { required: 'Description is required' },
+        },
+    };
+}
diff --git a/apps/ottabase-template-app-tanstack/ottabase/models/HomepageSection.schema.ts b/apps/ottabase-template-app-tanstack/ottabase/models/HomepageSection.schema.ts
new file mode 100644
index 000000000..7614d6501
--- /dev/null
+++ b/apps/ottabase-template-app-tanstack/ottabase/models/HomepageSection.schema.ts
@@ -0,0 +1,40 @@
+// ============================================================
+// Homepage Section table (App-specific)
+// ============================================================
+
+import { sql } from 'drizzle-orm';
+import { index, integer, sqliteTable, text } from 'drizzle-orm/sqlite-core';
+
+export const homepageSectionsTable = sqliteTable(
+    'homepage_sections',
+    {
+        id: text('id')
+            .primaryKey()
+            .$defaultFn(() => crypto.randomUUID()),
+        /** Slot name: navbar, hero, features, cta, footer, about */
+        slot: text('slot').notNull(),
+        title: text('title'),
+        subtitle: text('subtitle'),
+        body: text('body'),
+        /** Optional GitHub URL (used by navbar/about slots) */
+        githubUrl: text('github_url'),
+        /** Display order for listing */
+        sortOrder: integer('sort_order').notNull().default(0),
+        /** Multi-app identifier */
+        appId: text('app_id'),
+        createdAt: integer('created_at')
+            .$defaultFn(() => Date.now())
+            .notNull(),
+        updatedAt: integer('updated_at')
+            .$defaultFn(() => Date.now())
+            .$onUpdateFn(() => Date.now())
+            .notNull(),
+    },
+    (table) => [
+        index('homepage_sections_slot_idx').on(table.slot),
+        index('homepage_sections_app_slot_idx').on(table.appId, table.slot),
+    ],
+);
+
+export type HomepageSectionRow = typeof homepageSectionsTable.$inferSelect;
+export type NewHomepageSectionRow = typeof homepageSectionsTable.$inferInsert;
diff --git a/apps/ottabase-template-app-tanstack/ottabase/models/HomepageSection.ts b/apps/ottabase-template-app-tanstack/ottabase/models/HomepageSection.ts
new file mode 100644
index 000000000..9e66b7b69
--- /dev/null
+++ b/apps/ottabase-template-app-tanstack/ottabase/models/HomepageSection.ts
@@ -0,0 +1,108 @@
+// ============================================================
+// HomepageSection Model (App-specific fat model)
+// ============================================================
+
+import { BaseModel, ModelFields, type PackageType } from '@ottabase/ottaorm';
+import { homepageSectionsTable } from './HomepageSection.schema';
+
+export { homepageSectionsTable, type HomepageSectionRow, type NewHomepageSectionRow } from './HomepageSection.schema';
+
+/**
+ * A homepage section maps to a SlotRenderer slot (navbar, hero, features, cta, footer, about).
+ * Contains the title/subtitle/body for that slot.
+ * Features and actions are stored in child tables (HomepageFeature, HomepageAction).
+ */
+export class HomepageSection extends BaseModel {
+    static entity = 'homepage_sections';
+    static table = homepageSectionsTable;
+    static primaryKey = 'id';
+    static packageName = 'app';
+    static packageType: PackageType = 'app';
+
+    static casts = {
+        sortOrder: 'number' as const,
+        createdAt: 'date' as const,
+        updatedAt: 'date' as const,
+    };
+
+    static writable = {
+        create: ['slot', 'title', 'subtitle', 'body', 'githubUrl', 'sortOrder', 'appId'],
+        update: ['slot', 'title', 'subtitle', 'body', 'githubUrl', 'sortOrder', 'appId'],
+    };
+
+    protected static fields: ModelFields = {
+        id: { type: 'id', primaryKey: true, editable: false, uiConfig: { label: 'ID' } },
+        slot: {
+            type: 'string',
+            editable: true,
+            filterable: true,
+            sortable: true,
+            uiConfig: { label: 'Slot', description: 'Homepage slot name (hero, features, cta, etc.)' },
+            formConfig: { visible: true, fieldType: 'input' },
+            tableConfig: { visible: true, colWidth: 120 },
+            validation: { rules: 'required', messages: { required: 'Slot is required' } },
+        },
+        title: {
+            type: 'string',
+            editable: true,
+            searchable: true,
+            uiConfig: { label: 'Title', placeholder: 'Section heading' },
+            formConfig: { visible: true, fieldType: 'input' },
+            tableConfig: { visible: true, colWidth: 'auto' },
+        },
+        subtitle: {
+            type: 'string',
+            editable: true,
+            uiConfig: { label: 'Subtitle' },
+            formConfig: { visible: true, fieldType: 'input' },
+            tableConfig: { visible: true, colWidth: 200 },
+        },
+        body: {
+            type: 'string',
+            editable: true,
+            uiConfig: { label: 'Body text' },
+            formConfig: { visible: true, fieldType: 'textarea' },
+            tableConfig: { visible: false },
+        },
+        githubUrl: {
+            type: 'string',
+            editable: true,
+            uiConfig: { label: 'GitHub URL' },
+            formConfig: { visible: true, fieldType: 'input' },
+            tableConfig: { visible: false },
+        },
+        sortOrder: {
+            type: 'number',
+            editable: true,
+            sortable: true,
+            uiConfig: { label: 'Sort Order' },
+            formConfig: { visible: true, fieldType: 'number' },
+            tableConfig: { visible: true, colWidth: 100 },
+        },
+        appId: {
+            type: 'string',
+            editable: true,
+            filterable: true,
+            uiConfig: { label: 'App ID' },
+            tableConfig: { visible: false },
+        },
+        createdAt: {
+            type: 'date',
+            editable: false,
+            sortable: true,
+            uiConfig: { label: 'Created' },
+            tableConfig: { visible: false },
+        },
+        updatedAt: {
+            type: 'date',
+            editable: false,
+            sortable: true,
+            uiConfig: { label: 'Updated' },
+            tableConfig: { visible: false },
+        },
+    };
+
+    protected static validationRules = {
+        slot: { rules: 'required', fieldName: 'Slot', messages: { required: 'Slot is required' } },
+    };
+}
diff --git a/apps/ottabase-template-app-tanstack/worker/lib/db-utils.ts b/apps/ottabase-template-app-tanstack/worker/lib/db-utils.ts
index f1926dfd9..aeb0d207f 100644
--- a/apps/ottabase-template-app-tanstack/worker/lib/db-utils.ts
+++ b/apps/ottabase-template-app-tanstack/worker/lib/db-utils.ts
@@ -39,6 +39,10 @@ import { errorResponse } from '@ottabase/utils/http-errors';
 import { getOttabaseConfig } from '../../ottabase/config.loader';
 import { ChangelogEntry } from '../../ottabase/models/ChangelogEntry';
 import { changelogPolicy } from '../../ottabase/models/changelogPolicy';
+import { HomepageAction } from '../../ottabase/models/HomepageAction';
+import { HomepageDisplaySettings } from '../../ottabase/models/HomepageDisplaySettings';
+import { HomepageFeature } from '../../ottabase/models/HomepageFeature';
+import { HomepageSection } from '../../ottabase/models/HomepageSection';
 import { Todo } from '../../ottabase/models/Todo';
 import { mediaLibraryPolicy } from '../../ottabase/models/mediaLibraryPolicy';
 import type { CloudflareEnv } from '../cloudflare-env';
@@ -127,7 +131,7 @@ export function initDbConnection(env: CloudflareEnv): void {
     registerPolicy(mediaLibraryPolicy);
     registerPolicy(changelogPolicy);
 
-    const appModels = [Todo, ChangelogEntry];
+    const appModels = [Todo, ChangelogEntry, HomepageSection, HomepageFeature, HomepageAction, HomepageDisplaySettings];
 
     registerModels([...coreModels, ...ottablogModels, ...packageModels, ...brandModels, ...appModels]);
 
diff --git a/apps/ottabase-template-app-tanstack/worker/routes/homepage.ts b/apps/ottabase-template-app-tanstack/worker/routes/homepage.ts
new file mode 100644
index 000000000..7b79ec95e
--- /dev/null
+++ b/apps/ottabase-template-app-tanstack/worker/routes/homepage.ts
@@ -0,0 +1,190 @@
+// ============================================================
+// Homepage public API route
+// ============================================================
+// GET /api/homepage/data — returns all homepage content:
+//   sections (with features and actions), display settings, and exposed CMS pages.
+//
+// Pattern follows worker/routes/changelog.ts (public, read-only, no auth).
+// ============================================================
+
+import { BLOG_FEED_CONTENT_TYPES, Post } from '@ottabase/ottablog';
+import { createD1Driver } from '@ottabase/db/drizzle-d1';
+import { registerConnection } from '@ottabase/ottaorm';
+import { errorResponse } from '@ottabase/utils/http-errors';
+import { jsonResponse } from '@ottabase/utils/http-response';
+import type { CloudflareEnv } from '../../cloudflare-env';
+import { HomepageAction } from '../../ottabase/models/HomepageAction';
+import { HomepageDisplaySettings } from '../../ottabase/models/HomepageDisplaySettings';
+import { HomepageFeature } from '../../ottabase/models/HomepageFeature';
+import { HomepageSection } from '../../ottabase/models/HomepageSection';
+
+export interface HomepageRouteContext {
+    request: Request;
+    env: CloudflareEnv;
+    url: URL;
+}
+
+function ensureD1(env: CloudflareEnv): Response | null {
+    if (!env.OBCF_D1) {
+        return errorResponse('D1 database binding not configured', 500, {
+            code: 'CONFIG_ERROR',
+        });
+    }
+    return null;
+}
+
+/** Shape of a section in the public payload */
+interface PublicSection {
+    id: string;
+    slot: string;
+    title: string | null;
+    subtitle: string | null;
+    body: string | null;
+    githubUrl: string | null;
+    sortOrder: number;
+    features: Array<{ title: string; description: string }>;
+    actions: Array<{
+        label: string;
+        href: string;
+        variant: string | null;
+        external: boolean;
+    }>;
+}
+
+/** Shape of display settings in the public payload */
+interface PublicDisplay {
+    variantBySlot: Record<string, string> | null;
+    themePreset: string | null;
+    fallbackThemePresetId: string | null;
+}
+
+/** Shape of the full public payload */
+export interface HomepagePublicPayload {
+    sections: PublicSection[];
+    display: PublicDisplay;
+    exposedPages: Array<{ slug: string; title: string }>;
+}
+
+/**
+ * GET /api/homepage/data
+ *
+ * Returns the full homepage content payload for the Next.js consumer.
+ * All content comes from D1 via OttaORM; the Next.js app has no D1 binding.
+ */
+export async function handleHomepageData(context: HomepageRouteContext): Promise<Response> {
+    const { env, url } = context;
+    const d1Error = ensureD1(env);
+    if (d1Error) return d1Error;
+    registerConnection('default', createD1Driver(env.OBCF_D1));
+
+    const appId = url.searchParams.get('appId') || null;
+
+    // ── 1. Sections with child features + actions ──────────────────────
+    let sections: PublicSection[] = [];
+    try {
+        const sectionWhere: Record<string, unknown> = {};
+        if (appId) sectionWhere.appId = appId;
+
+        const sectionRecords = await HomepageSection.where(sectionWhere, {
+            orderBy: 'sortOrder',
+            orderDirection: 'asc',
+        });
+
+        // Batch-load all features and actions for these sections
+        const sectionIds = sectionRecords.map((s) => s.get('id') as string);
+
+        let allFeatures: InstanceType<typeof HomepageFeature>[] = [];
+        let allActions: InstanceType<typeof HomepageAction>[] = [];
+
+        if (sectionIds.length > 0) {
+            allFeatures = (await HomepageFeature.where(
+                { sectionId: { $in: sectionIds } },
+                { orderBy: 'sortOrder', orderDirection: 'asc' },
+            )) as InstanceType<typeof HomepageFeature>[];
+
+            allActions = (await HomepageAction.where(
+                { sectionId: { $in: sectionIds } },
+                { orderBy: 'sortOrder', orderDirection: 'asc' },
+            )) as InstanceType<typeof HomepageAction>[];
+        }
+
+        // Group by sectionId
+        const featuresBySectionId = new Map<string, Array<{ title: string; description: string }>>();
+        for (const f of allFeatures) {
+            const sid = f.get('sectionId') as string;
+            if (!featuresBySectionId.has(sid)) featuresBySectionId.set(sid, []);
+            featuresBySectionId.get(sid)!.push({
+                title: f.get('title') as string,
+                description: f.get('description') as string,
+            });
+        }
+
+        const actionsBySectionId = new Map<
+            string,
+            Array<{ label: string; href: string; variant: string | null; external: boolean }>
+        >();
+        for (const a of allActions) {
+            const sid = a.get('sectionId') as string;
+            if (!actionsBySectionId.has(sid)) actionsBySectionId.set(sid, []);
+            actionsBySectionId.get(sid)!.push({
+                label: a.get('label') as string,
+                href: a.get('href') as string,
+                variant: (a.get('variant') as string) ?? null,
+                external: (a.get('external') as boolean) ?? false,
+            });
+        }
+
+        sections = sectionRecords.map((s) => {
+            const id = s.get('id') as string;
+            return {
+                id,
+                slot: s.get('slot') as string,
+                title: (s.get('title') as string) ?? null,
+                subtitle: (s.get('subtitle') as string) ?? null,
+                body: (s.get('body') as string) ?? null,
+                githubUrl: (s.get('githubUrl') as string) ?? null,
+                sortOrder: (s.get('sortOrder') as number) ?? 0,
+                features: featuresBySectionId.get(id) ?? [],
+                actions: actionsBySectionId.get(id) ?? [],
+            };
+        });
+    } catch {
+        // Non-fatal: return empty sections
+        sections = [];
+    }
+
+    // ── 2. Display settings ────────────────────────────────────────────
+    let display: PublicDisplay = { variantBySlot: null, themePreset: null, fallbackThemePresetId: null };
+    try {
+        const settings = await HomepageDisplaySettings.getOrCreateDefault(appId);
+        display = {
+            variantBySlot: (settings.get('variantBySlotJson') as Record<string, string>) ?? null,
+            themePreset: (settings.get('themePreset') as string) ?? null,
+            fallbackThemePresetId: (settings.get('fallbackThemePresetId') as string) ?? null,
+        };
+    } catch {
+        // Non-fatal: keep defaults
+    }
+
+    // ── 3. Exposed CMS pages (for navbar links) ───────────────────────
+    let exposedPages: Array<{ slug: string; title: string }> = [];
+    try {
+        const pageWhere: Record<string, unknown> = {
+            contentType: 'page',
+            status: 'published',
+            exposeToHomepage: true,
+        };
+        if (appId) pageWhere.appId = appId;
+
+        const pages = await Post.where(pageWhere, { orderBy: 'title', orderDirection: 'asc' });
+        exposedPages = pages.map((p) => ({
+            slug: p.get('slug') as string,
+            title: p.get('title') as string,
+        }));
+    } catch {
+        // Non-fatal: return empty
+    }
+
+    const payload: HomepagePublicPayload = { sections, display, exposedPages };
+    return jsonResponse(payload);
+}
diff --git a/apps/ottabase-template-app-tanstack/worker/routes/router.ts b/apps/ottabase-template-app-tanstack/worker/routes/router.ts
index 185cb8382..1cb3bad2e 100644
--- a/apps/ottabase-template-app-tanstack/worker/routes/router.ts
+++ b/apps/ottabase-template-app-tanstack/worker/routes/router.ts
@@ -68,6 +68,7 @@ import {
 } from './blog';
 import { handleChangelogEntriesList, handleChangelogEntryBySlug } from './changelog';
 import { handleBrandApi } from './brand';
+import { handleHomepageData } from './homepage';
 import {
     handleAIChat,
     handleAIGatewayChat,
@@ -181,6 +182,11 @@ async function handleGetRoutes(context: ApiRouteContext): Promise<Response | nul
         return handleChangelogEntryBySlug(context, slug);
     }
 
+    // Homepage public data (sections + display settings + exposed pages)
+    if (route === '/api/homepage/data') {
+        return handleHomepageData(context);
+    }
+
     if (route === '/api/system/kill-switches') {
         return jsonResponse({
             ...getKillSwitchStatus(context.env),

From 67d57e20859de77f98c4091e9ef79735f8bf628d Mon Sep 17 00:00:00 2001
From: "copilot-swe-agent[bot]" <198982749+Copilot@users.noreply.github.com>
Date: Mon, 30 Mar 2026 18:46:08 +0000
Subject: [PATCH 06/19] =?UTF-8?q?fix:=20address=20code=20review=20?=
 =?UTF-8?q?=E2=80=94=20remove=20unused=20import,=20add=20error=20logging,?=
 =?UTF-8?q?=20fix=20empty=20array=20check?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Agent-Logs-Url: https://github.com/thinkdj/ottabase/sessions/b9bee764-b52d-4fdc-a63f-1aa2b58b0afb
---
 .../__tests__/components.test.tsx             | 50 +++++++++++++++++++
 .../app/layout-shell.tsx                      |  2 +-
 .../ottabase/models/HomepageSection.schema.ts |  1 -
 .../worker/routes/homepage.ts                 | 11 ++--
 4 files changed, 58 insertions(+), 6 deletions(-)

diff --git a/apps/ottabase-template-app-nextjs-homepage/__tests__/components.test.tsx b/apps/ottabase-template-app-nextjs-homepage/__tests__/components.test.tsx
index e7a5cbf4c..30368f36e 100644
--- a/apps/ottabase-template-app-nextjs-homepage/__tests__/components.test.tsx
+++ b/apps/ottabase-template-app-nextjs-homepage/__tests__/components.test.tsx
@@ -364,3 +364,53 @@ describe('LayoutShell navbar merge', () => {
         expect(result).toEqual([{ href: '/page/faq', label: 'FAQ' }]);
     });
 });
+
+describe('Homepage API types', () => {
+    it('fetchHomepageData returns safe fallback when API_URL is empty', async () => {
+        const { fetchHomepageData } = await import('../lib/api');
+        // NEXT_PUBLIC_API_URL is not set in test env, so should return fallback
+        const result = await fetchHomepageData();
+        expect(result).toEqual({
+            sections: [],
+            display: { variantBySlot: null, themePreset: null, fallbackThemePresetId: null },
+            exposedPages: [],
+        });
+    });
+
+    it('fetchExposedPages returns empty array when API_URL is empty', async () => {
+        const { fetchExposedPages } = await import('../lib/api');
+        const result = await fetchExposedPages();
+        expect(result).toEqual([]);
+    });
+
+    it('fetchPageBySlug returns null when API_URL is empty', async () => {
+        const { fetchPageBySlug } = await import('../lib/api');
+        const result = await fetchPageBySlug('test');
+        expect(result).toBeNull();
+    });
+
+    it('HomepageDataPayload types are correctly shaped', async () => {
+        const api = await import('../lib/api');
+        // Verify the type shape exists by constructing a valid object
+        const payload: api.HomepageDataPayload = {
+            sections: [
+                {
+                    id: '1',
+                    slot: 'hero',
+                    title: 'Title',
+                    subtitle: 'Sub',
+                    body: null,
+                    githubUrl: null,
+                    sortOrder: 0,
+                    features: [],
+                    actions: [{ label: 'Go', href: '/go', variant: 'default', external: false }],
+                },
+            ],
+            display: { variantBySlot: { hero: 'centered' }, themePreset: 'neo', fallbackThemePresetId: null },
+            exposedPages: [{ slug: 'about', title: 'About' }],
+        };
+        expect(payload.sections).toHaveLength(1);
+        expect(payload.display.themePreset).toBe('neo');
+        expect(payload.exposedPages[0].slug).toBe('about');
+    });
+});
diff --git a/apps/ottabase-template-app-nextjs-homepage/app/layout-shell.tsx b/apps/ottabase-template-app-nextjs-homepage/app/layout-shell.tsx
index 11f6b002a..01a2cf710 100644
--- a/apps/ottabase-template-app-nextjs-homepage/app/layout-shell.tsx
+++ b/apps/ottabase-template-app-nextjs-homepage/app/layout-shell.tsx
@@ -110,7 +110,7 @@ export function LayoutShell({ children, exposedPages = [], homepageData }: Layou
     const navbarLinks = mergeNavLinks(BASE_NAVBAR_LINKS, exposedPages);
 
     // Build slot data overrides from DB sections (if available)
-    const dbSlotData = homepageData?.sections?.length ? buildSlotDataFromSections(homepageData.sections) : {};
+    const dbSlotData = homepageData?.sections ? buildSlotDataFromSections(homepageData.sections) : {};
 
     const navbarData = {
         title: 'Ottabase',
diff --git a/apps/ottabase-template-app-tanstack/ottabase/models/HomepageSection.schema.ts b/apps/ottabase-template-app-tanstack/ottabase/models/HomepageSection.schema.ts
index 7614d6501..f6d8b367e 100644
--- a/apps/ottabase-template-app-tanstack/ottabase/models/HomepageSection.schema.ts
+++ b/apps/ottabase-template-app-tanstack/ottabase/models/HomepageSection.schema.ts
@@ -2,7 +2,6 @@
 // Homepage Section table (App-specific)
 // ============================================================
 
-import { sql } from 'drizzle-orm';
 import { index, integer, sqliteTable, text } from 'drizzle-orm/sqlite-core';
 
 export const homepageSectionsTable = sqliteTable(
diff --git a/apps/ottabase-template-app-tanstack/worker/routes/homepage.ts b/apps/ottabase-template-app-tanstack/worker/routes/homepage.ts
index 7b79ec95e..19e7b6379 100644
--- a/apps/ottabase-template-app-tanstack/worker/routes/homepage.ts
+++ b/apps/ottabase-template-app-tanstack/worker/routes/homepage.ts
@@ -7,7 +7,7 @@
 // Pattern follows worker/routes/changelog.ts (public, read-only, no auth).
 // ============================================================
 
-import { BLOG_FEED_CONTENT_TYPES, Post } from '@ottabase/ottablog';
+import { Post } from '@ottabase/ottablog';
 import { createD1Driver } from '@ottabase/db/drizzle-d1';
 import { registerConnection } from '@ottabase/ottaorm';
 import { errorResponse } from '@ottabase/utils/http-errors';
@@ -148,8 +148,9 @@ export async function handleHomepageData(context: HomepageRouteContext): Promise
                 actions: actionsBySectionId.get(id) ?? [],
             };
         });
-    } catch {
+    } catch (err) {
         // Non-fatal: return empty sections
+        console.error('[homepage/data] Failed to load sections:', err);
         sections = [];
     }
 
@@ -162,8 +163,9 @@ export async function handleHomepageData(context: HomepageRouteContext): Promise
             themePreset: (settings.get('themePreset') as string) ?? null,
             fallbackThemePresetId: (settings.get('fallbackThemePresetId') as string) ?? null,
         };
-    } catch {
+    } catch (err) {
         // Non-fatal: keep defaults
+        console.error('[homepage/data] Failed to load display settings:', err);
     }
 
     // ── 3. Exposed CMS pages (for navbar links) ───────────────────────
@@ -181,8 +183,9 @@ export async function handleHomepageData(context: HomepageRouteContext): Promise
             slug: p.get('slug') as string,
             title: p.get('title') as string,
         }));
-    } catch {
+    } catch (err) {
         // Non-fatal: return empty
+        console.error('[homepage/data] Failed to load exposed pages:', err);
     }
 
     const payload: HomepagePublicPayload = { sections, display, exposedPages };

From a85fd4ff2dafff71ccebee1d48844e9a29724b61 Mon Sep 17 00:00:00 2001
From: "copilot-swe-agent[bot]" <198982749+Copilot@users.noreply.github.com>
Date: Mon, 30 Mar 2026 19:08:54 +0000
Subject: [PATCH 07/19] =?UTF-8?q?feat:=20add=20admin=20UI=20for=20homepage?=
 =?UTF-8?q?=20management=20=E2=80=94=20sections,=20features,=20actions,=20?=
 =?UTF-8?q?display=20settings?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Agent-Logs-Url: https://github.com/thinkdj/ottabase/sessions/100ba360-6a73-4e2b-ad44-5369c4583ca8
---
 .../src/hooks/homepageHooks.ts                |  72 +++
 .../src/pages/admin/AdminIndexPage.tsx        |   7 +
 .../homepage/AdminHomepageDisplayPage.tsx     | 262 ++++++++++
 .../AdminHomepageSectionEditorPage.tsx        | 485 ++++++++++++++++++
 .../homepage/AdminHomepageSectionsPage.tsx    | 427 +++++++++++++++
 .../pages/admin/homepage/HomepageAdminNav.tsx |  38 ++
 .../src/pages/admin/homepage/index.ts         |   4 +
 .../src/router.tsx                            |  34 ++
 8 files changed, 1329 insertions(+)
 create mode 100644 apps/ottabase-template-app-tanstack/src/hooks/homepageHooks.ts
 create mode 100644 apps/ottabase-template-app-tanstack/src/pages/admin/homepage/AdminHomepageDisplayPage.tsx
 create mode 100644 apps/ottabase-template-app-tanstack/src/pages/admin/homepage/AdminHomepageSectionEditorPage.tsx
 create mode 100644 apps/ottabase-template-app-tanstack/src/pages/admin/homepage/AdminHomepageSectionsPage.tsx
 create mode 100644 apps/ottabase-template-app-tanstack/src/pages/admin/homepage/HomepageAdminNav.tsx
 create mode 100644 apps/ottabase-template-app-tanstack/src/pages/admin/homepage/index.ts

diff --git a/apps/ottabase-template-app-tanstack/src/hooks/homepageHooks.ts b/apps/ottabase-template-app-tanstack/src/hooks/homepageHooks.ts
new file mode 100644
index 000000000..043a0c5c4
--- /dev/null
+++ b/apps/ottabase-template-app-tanstack/src/hooks/homepageHooks.ts
@@ -0,0 +1,72 @@
+/**
+ * Homepage Admin Hooks
+ *
+ * Pre-configured model hooks for homepage entities to avoid duplication across pages.
+ * Follows the same pattern as blogHooks.ts / mediaLibraryHooks.ts.
+ */
+import { createModelHooks } from '@ottabase/ottaorm/client';
+
+// ── Row types ───────────────────────────────────────────────────────────────
+
+export interface HomepageSectionRow {
+    id: string;
+    slot: string;
+    title: string | null;
+    subtitle: string | null;
+    body: string | null;
+    githubUrl: string | null;
+    sortOrder: number;
+    appId: string | null;
+    createdAt: string;
+    updatedAt: string;
+}
+
+export interface HomepageFeatureRow {
+    id: string;
+    sectionId: string;
+    title: string;
+    description: string;
+    sortOrder: number;
+    createdAt: string;
+    updatedAt: string;
+}
+
+export interface HomepageActionRow {
+    id: string;
+    sectionId: string;
+    label: string;
+    href: string;
+    variant: string | null;
+    external: boolean;
+    sortOrder: number;
+    createdAt: string;
+    updatedAt: string;
+}
+
+export interface HomepageDisplaySettingsRow {
+    id: string;
+    variantBySlotJson: Record<string, string> | null;
+    themePreset: string | null;
+    fallbackThemePresetId: string | null;
+    appId: string | null;
+    createdAt: string;
+    updatedAt: string;
+}
+
+// ── Hooks ───────────────────────────────────────────────────────────────────
+
+export const homepageSectionHooks = createModelHooks<HomepageSectionRow>({
+    entityName: 'homepage_sections',
+});
+
+export const homepageFeatureHooks = createModelHooks<HomepageFeatureRow>({
+    entityName: 'homepage_features',
+});
+
+export const homepageActionHooks = createModelHooks<HomepageActionRow>({
+    entityName: 'homepage_actions',
+});
+
+export const homepageDisplaySettingsHooks = createModelHooks<HomepageDisplaySettingsRow>({
+    entityName: 'homepage_display_settings',
+});
diff --git a/apps/ottabase-template-app-tanstack/src/pages/admin/AdminIndexPage.tsx b/apps/ottabase-template-app-tanstack/src/pages/admin/AdminIndexPage.tsx
index 704fe3d40..578f85f55 100644
--- a/apps/ottabase-template-app-tanstack/src/pages/admin/AdminIndexPage.tsx
+++ b/apps/ottabase-template-app-tanstack/src/pages/admin/AdminIndexPage.tsx
@@ -10,6 +10,7 @@ import {
     Clock,
     Database,
     FileText,
+    Home,
     Layers,
     Layout,
     Mail,
@@ -87,6 +88,12 @@ const ADMIN_CATEGORIES: AdminCategory[] = [
                 href: '/admin/changelog',
                 icon: FileText,
             },
+            {
+                title: 'Homepage',
+                description: 'Manage homepage sections, features, actions, and display settings.',
+                href: '/admin/homepage',
+                icon: Home,
+            },
             ...(MEDIA_LIBRARY_ENABLED
                 ? [
                       {
diff --git a/apps/ottabase-template-app-tanstack/src/pages/admin/homepage/AdminHomepageDisplayPage.tsx b/apps/ottabase-template-app-tanstack/src/pages/admin/homepage/AdminHomepageDisplayPage.tsx
new file mode 100644
index 000000000..7fc834873
--- /dev/null
+++ b/apps/ottabase-template-app-tanstack/src/pages/admin/homepage/AdminHomepageDisplayPage.tsx
@@ -0,0 +1,262 @@
+/**
+ * Admin Homepage Display Settings
+ *
+ * Manages the homepage display state:
+ * - Variant selection per slot (maps to SLOT_REGISTRY on the Next.js side)
+ * - Theme preset
+ *
+ * Single-row settings model (id = 'default'). Uses upsert semantics via
+ * getOrCreateDefault on the API side.
+ */
+import { ADMIN_LIST_QUERY_CONFIG } from '@/config/queryConfig';
+import { homepageDisplaySettingsHooks, type HomepageDisplaySettingsRow } from '@/hooks/homepageHooks';
+import {
+    Badge,
+    Button,
+    Card,
+    CardContent,
+    CardDescription,
+    CardHeader,
+    CardTitle,
+    Input,
+    Label,
+} from '@ottabase/ui-shadcn';
+import { Check, Monitor, Save } from 'lucide-react';
+import { useCallback, useEffect, useState } from 'react';
+import { HomepageAdminNav } from './HomepageAdminNav';
+
+/** Matches SLOT_NAMES + SLOT_REGISTRY from the Next.js homepage-config. */
+const SLOT_CONFIG = {
+    navbar: {
+        label: 'Navigation Bar',
+        variants: [
+            { id: 'default', label: 'Default', desc: 'Logo left, links right, mobile hamburger.' },
+            { id: 'centered', label: 'Centered', desc: 'Logo and links centered.' },
+            { id: 'minimal', label: 'Minimal', desc: 'Logo and dark-mode toggle only.' },
+        ],
+        default: 'default',
+    },
+    hero: {
+        label: 'Hero Section',
+        variants: [
+            { id: 'centered', label: 'Centered', desc: 'Large centered headline with buttons.' },
+            { id: 'split', label: 'Split', desc: 'Text left, visual right.' },
+            { id: 'minimal', label: 'Minimal', desc: 'Compact headline.' },
+        ],
+        default: 'centered',
+    },
+    features: {
+        label: 'Features Section',
+        variants: [
+            { id: 'grid', label: 'Grid', desc: 'Two-column bordered list.' },
+            { id: 'cards', label: 'Cards', desc: 'Card layout with hover effects.' },
+            { id: 'list', label: 'List', desc: 'Vertical stacked list.' },
+        ],
+        default: 'grid',
+    },
+    cta: {
+        label: 'Call-to-Action',
+        variants: [
+            { id: 'default', label: 'Default', desc: 'Centered text with buttons.' },
+            { id: 'banner', label: 'Banner', desc: 'Full-width colored banner.' },
+            { id: 'minimal', label: 'Minimal', desc: 'Compact inline CTA.' },
+        ],
+        default: 'default',
+    },
+    footer: {
+        label: 'Footer',
+        variants: [
+            { id: 'default', label: 'Default', desc: 'Copyright and links row.' },
+            { id: 'minimal', label: 'Minimal', desc: 'Single-line copyright.' },
+            { id: 'columns', label: 'Columns', desc: 'Multi-column grouped links.' },
+        ],
+        default: 'default',
+    },
+    about: {
+        label: 'About Page',
+        variants: [
+            { id: 'default', label: 'Default', desc: 'Full content with features, steps, CTA.' },
+            { id: 'minimal', label: 'Minimal', desc: 'Concise single-section.' },
+            { id: 'detailed', label: 'Detailed', desc: 'Card-based with tech-stack badges.' },
+        ],
+        default: 'default',
+    },
+} as const;
+
+type SlotName = keyof typeof SLOT_CONFIG;
+const SLOT_NAMES = Object.keys(SLOT_CONFIG) as SlotName[];
+
+function getDefaults(): Record<string, string> {
+    const d: Record<string, string> = {};
+    for (const [k, v] of Object.entries(SLOT_CONFIG)) {
+        d[k] = v.default;
+    }
+    return d;
+}
+
+export function AdminHomepageDisplayPage() {
+    const { data, isLoading } = homepageDisplaySettingsHooks.useList({}, ADMIN_LIST_QUERY_CONFIG);
+    const createSettings = homepageDisplaySettingsHooks.useCreate();
+    const updateSettings = homepageDisplaySettingsHooks.useUpdate();
+
+    // Normalize response: list may return array or paginated
+    const rows = (Array.isArray(data) ? data : []) as HomepageDisplaySettingsRow[];
+    const existing = rows.find((r) => r.id === 'default') ?? null;
+
+    const [variantBySlot, setVariantBySlot] = useState<Record<string, string>>(getDefaults());
+    const [themePreset, setThemePreset] = useState('default');
+    const [initialized, setInitialized] = useState(false);
+
+    // Populate from DB when data loads
+    useEffect(() => {
+        if (existing && !initialized) {
+            setVariantBySlot({ ...getDefaults(), ...(existing.variantBySlotJson ?? {}) });
+            setThemePreset(existing.themePreset ?? 'default');
+            setInitialized(true);
+        } else if (!isLoading && !existing && !initialized) {
+            // No row yet — use defaults
+            setInitialized(true);
+        }
+    }, [existing, isLoading, initialized]);
+
+    const isDirty =
+        initialized &&
+        (JSON.stringify(variantBySlot) !==
+            JSON.stringify({ ...getDefaults(), ...(existing?.variantBySlotJson ?? {}) }) ||
+            themePreset !== (existing?.themePreset ?? 'default'));
+
+    const handleSave = useCallback(async () => {
+        const payload = {
+            variantBySlotJson: variantBySlot,
+            themePreset,
+        };
+        if (existing) {
+            await updateSettings.mutateAsync({ id: 'default', data: payload });
+        } else {
+            await createSettings.mutateAsync({ id: 'default', ...payload });
+        }
+    }, [existing, variantBySlot, themePreset, updateSettings, createSettings]);
+
+    const handleVariantChange = (slot: SlotName, variantId: string) => {
+        setVariantBySlot((prev) => ({ ...prev, [slot]: variantId }));
+    };
+
+    const handleResetDefaults = () => {
+        setVariantBySlot(getDefaults());
+        setThemePreset('default');
+    };
+
+    if (isLoading) {
+        return (
+            <div className="space-y-6">
+                <HomepageAdminNav />
+                <Card>
+                    <CardContent className="py-12 text-center">
+                        <p className="text-muted-foreground">Loading display settings…</p>
+                    </CardContent>
+                </Card>
+            </div>
+        );
+    }
+
+    return (
+        <div className="space-y-6">
+            <HomepageAdminNav />
+
+            {/* Header */}
+            <div className="flex flex-col gap-4 sm:flex-row sm:items-center sm:justify-between">
+                <div>
+                    <h1 className="text-3xl font-bold tracking-tight">Display Settings</h1>
+                    <p className="text-muted-foreground mt-1">
+                        Choose which variant to display for each slot, and set the active theme preset.
+                    </p>
+                </div>
+                <div className="flex gap-2">
+                    <Button variant="outline" onClick={handleResetDefaults}>
+                        Reset Defaults
+                    </Button>
+                    <Button
+                        onClick={handleSave}
+                        disabled={!isDirty || updateSettings.isPending || createSettings.isPending}
+                    >
+                        <Save className="mr-2 h-4 w-4" />
+                        {updateSettings.isPending || createSettings.isPending ? 'Saving…' : 'Save'}
+                    </Button>
+                </div>
+            </div>
+
+            {/* Theme Preset */}
+            <Card>
+                <CardHeader>
+                    <CardTitle className="text-base flex items-center gap-2">
+                        <Monitor className="h-4 w-4" />
+                        Theme Preset
+                    </CardTitle>
+                    <CardDescription>The theme preset name used for SSR and initial page load.</CardDescription>
+                </CardHeader>
+                <CardContent>
+                    <div className="flex items-center gap-3">
+                        <Label htmlFor="theme-preset" className="shrink-0">
+                            Preset name:
+                        </Label>
+                        <Input
+                            id="theme-preset"
+                            value={themePreset}
+                            onChange={(e) => setThemePreset(e.target.value)}
+                            placeholder="default"
+                            className="max-w-xs"
+                        />
+                    </div>
+                </CardContent>
+            </Card>
+
+            {/* Slot Variant Pickers */}
+            {SLOT_NAMES.map((slot) => {
+                const config = SLOT_CONFIG[slot];
+                const selected = variantBySlot[slot] ?? config.default;
+
+                return (
+                    <Card key={slot}>
+                        <CardHeader className="pb-3">
+                            <CardTitle className="text-base">{config.label}</CardTitle>
+                            <CardDescription>
+                                Select which variant to use for the{' '}
+                                <Badge variant="outline" className="font-mono text-xs">
+                                    {slot}
+                                </Badge>{' '}
+                                slot.
+                            </CardDescription>
+                        </CardHeader>
+                        <CardContent>
+                            <div className="grid gap-3 sm:grid-cols-3">
+                                {config.variants.map((v) => {
+                                    const isActive = selected === v.id;
+                                    return (
+                                        <button
+                                            key={v.id}
+                                            type="button"
+                                            onClick={() => handleVariantChange(slot, v.id)}
+                                            className={`relative rounded-lg border-2 p-4 text-left transition-all ${
+                                                isActive
+                                                    ? 'border-primary bg-primary/5 ring-1 ring-primary/20'
+                                                    : 'border-border hover:border-muted-foreground/30 hover:bg-muted/50'
+                                            }`}
+                                        >
+                                            {isActive && (
+                                                <div className="absolute top-2 right-2 rounded-full bg-primary p-0.5">
+                                                    <Check className="h-3 w-3 text-primary-foreground" />
+                                                </div>
+                                            )}
+                                            <p className="font-medium text-sm">{v.label}</p>
+                                            <p className="mt-1 text-xs text-muted-foreground">{v.desc}</p>
+                                        </button>
+                                    );
+                                })}
+                            </div>
+                        </CardContent>
+                    </Card>
+                );
+            })}
+        </div>
+    );
+}
diff --git a/apps/ottabase-template-app-tanstack/src/pages/admin/homepage/AdminHomepageSectionEditorPage.tsx b/apps/ottabase-template-app-tanstack/src/pages/admin/homepage/AdminHomepageSectionEditorPage.tsx
new file mode 100644
index 000000000..dbb64d867
--- /dev/null
+++ b/apps/ottabase-template-app-tanstack/src/pages/admin/homepage/AdminHomepageSectionEditorPage.tsx
@@ -0,0 +1,485 @@
+/**
+ * Admin Homepage Section Editor
+ *
+ * Full CRUD editor for a single homepage section. Includes inline editing of
+ * child features and actions. Auto-saves on blur or button click.
+ *
+ * Pattern: follows AdminChangelogEditorPage (single-entity form with nested items).
+ */
+import { ADMIN_LIST_QUERY_CONFIG } from '@/config/queryConfig';
+import {
+    homepageActionHooks,
+    homepageFeatureHooks,
+    homepageSectionHooks,
+    type HomepageActionRow,
+    type HomepageFeatureRow,
+} from '@/hooks/homepageHooks';
+import {
+    AlertDialog,
+    AlertDialogAction,
+    AlertDialogCancel,
+    AlertDialogContent,
+    AlertDialogDescription,
+    AlertDialogFooter,
+    AlertDialogHeader,
+    AlertDialogTitle,
+    Badge,
+    Button,
+    Card,
+    CardContent,
+    CardDescription,
+    CardHeader,
+    CardTitle,
+    Input,
+    Label,
+    Separator,
+    Switch,
+    Textarea,
+} from '@ottabase/ui-shadcn';
+import { useNavigate, useParams } from '@tanstack/react-router';
+import { ArrowLeft, ExternalLink, GripVertical, Plus, Save, Trash2 } from 'lucide-react';
+import { useCallback, useEffect, useState } from 'react';
+import { HomepageAdminNav } from './HomepageAdminNav';
+
+const SLOT_LABELS: Record<string, string> = {
+    navbar: 'Navigation Bar',
+    hero: 'Hero Section',
+    features: 'Features Section',
+    cta: 'Call-to-Action',
+    footer: 'Footer',
+    about: 'About Page',
+};
+
+const ACTION_VARIANTS = [
+    { value: 'default', label: 'Default' },
+    { value: 'secondary', label: 'Secondary' },
+    { value: 'outline', label: 'Outline' },
+    { value: 'ghost', label: 'Ghost' },
+] as const;
+
+// ── Feature row editor ──────────────────────────────────────────────────────
+
+function FeatureEditor({ feature, onDelete }: { feature: HomepageFeatureRow; onDelete: (id: string) => void }) {
+    const updateFeature = homepageFeatureHooks.useUpdate();
+    const [title, setTitle] = useState(feature.title);
+    const [description, setDescription] = useState(feature.description);
+    const dirty = title !== feature.title || description !== feature.description;
+
+    const handleSave = useCallback(() => {
+        if (!dirty) return;
+        updateFeature.mutate({ id: feature.id, data: { title, description } });
+    }, [dirty, feature.id, title, description, updateFeature]);
+
+    return (
+        <div className="flex items-start gap-2 rounded-lg border p-3">
+            <GripVertical className="mt-2 h-4 w-4 shrink-0 text-muted-foreground/40 cursor-grab" />
+            <div className="flex-1 space-y-2">
+                <Input
+                    value={title}
+                    onChange={(e) => setTitle(e.target.value)}
+                    onBlur={handleSave}
+                    placeholder="Feature title"
+                    className="h-8 text-sm font-medium"
+                />
+                <Textarea
+                    value={description}
+                    onChange={(e) => setDescription(e.target.value)}
+                    onBlur={handleSave}
+                    placeholder="Short description"
+                    rows={2}
+                    className="text-sm"
+                />
+            </div>
+            <div className="flex flex-col items-center gap-1">
+                {dirty && (
+                    <Button variant="ghost" size="icon" className="h-7 w-7" onClick={handleSave}>
+                        <Save className="h-3.5 w-3.5 text-primary" />
+                    </Button>
+                )}
+                <Button variant="ghost" size="icon" className="h-7 w-7" onClick={() => onDelete(feature.id)}>
+                    <Trash2 className="h-3.5 w-3.5 text-destructive" />
+                </Button>
+            </div>
+        </div>
+    );
+}
+
+// ── Action row editor ───────────────────────────────────────────────────────
+
+function ActionEditor({ action, onDelete }: { action: HomepageActionRow; onDelete: (id: string) => void }) {
+    const updateAction = homepageActionHooks.useUpdate();
+    const [label, setLabel] = useState(action.label);
+    const [href, setHref] = useState(action.href);
+    const [variant, setVariant] = useState(action.variant ?? 'default');
+    const [external, setExternal] = useState(action.external);
+    const dirty =
+        label !== action.label ||
+        href !== action.href ||
+        variant !== (action.variant ?? 'default') ||
+        external !== action.external;
+
+    const handleSave = useCallback(() => {
+        if (!dirty) return;
+        updateAction.mutate({
+            id: action.id,
+            data: { label, href, variant, external },
+        });
+    }, [dirty, action.id, label, href, variant, external, updateAction]);
+
+    return (
+        <div className="flex items-start gap-2 rounded-lg border p-3">
+            <GripVertical className="mt-2 h-4 w-4 shrink-0 text-muted-foreground/40 cursor-grab" />
+            <div className="flex-1 space-y-2">
+                <div className="flex gap-2">
+                    <Input
+                        value={label}
+                        onChange={(e) => setLabel(e.target.value)}
+                        onBlur={handleSave}
+                        placeholder="Button label"
+                        className="h-8 text-sm font-medium"
+                    />
+                    <Input
+                        value={href}
+                        onChange={(e) => setHref(e.target.value)}
+                        onBlur={handleSave}
+                        placeholder="/about or https://..."
+                        className="h-8 text-sm"
+                    />
+                </div>
+                <div className="flex items-center gap-4">
+                    <div className="flex items-center gap-2">
+                        <Label className="text-xs">Style:</Label>
+                        <select
+                            value={variant}
+                            onChange={(e) => {
+                                setVariant(e.target.value);
+                                // Trigger save after state update
+                                setTimeout(() => handleSave(), 0);
+                            }}
+                            className="h-7 rounded-md border border-input bg-background px-2 text-xs"
+                            aria-label="Button style variant"
+                        >
+                            {ACTION_VARIANTS.map((v) => (
+                                <option key={v.value} value={v.value}>
+                                    {v.label}
+                                </option>
+                            ))}
+                        </select>
+                    </div>
+                    <div className="flex items-center gap-2">
+                        <Switch
+                            id={`external-${action.id}`}
+                            checked={external}
+                            onCheckedChange={(checked) => {
+                                setExternal(checked);
+                                setTimeout(() => handleSave(), 0);
+                            }}
+                        />
+                        <Label htmlFor={`external-${action.id}`} className="text-xs">
+                            External
+                        </Label>
+                        {external && <ExternalLink className="h-3 w-3 text-muted-foreground" />}
+                    </div>
+                </div>
+            </div>
+            <div className="flex flex-col items-center gap-1">
+                {dirty && (
+                    <Button variant="ghost" size="icon" className="h-7 w-7" onClick={handleSave}>
+                        <Save className="h-3.5 w-3.5 text-primary" />
+                    </Button>
+                )}
+                <Button variant="ghost" size="icon" className="h-7 w-7" onClick={() => onDelete(action.id)}>
+                    <Trash2 className="h-3.5 w-3.5 text-destructive" />
+                </Button>
+            </div>
+        </div>
+    );
+}
+
+// ── Main editor page ────────────────────────────────────────────────────────
+
+export function AdminHomepageSectionEditorPage() {
+    const { sectionId } = useParams({ strict: false }) as { sectionId?: string };
+    const navigate = useNavigate();
+
+    // Section data
+    const { data: sectionData, isLoading: sectionLoading } = homepageSectionHooks.useDetail(sectionId ?? '', {
+        enabled: !!sectionId,
+    });
+    const updateSection = homepageSectionHooks.useUpdate();
+
+    // Child features & actions
+    const { data: featuresData } = homepageFeatureHooks.useList(
+        { where: { sectionId }, orderBy: 'sortOrder', orderDirection: 'asc' },
+        { ...ADMIN_LIST_QUERY_CONFIG, enabled: !!sectionId },
+    );
+    const { data: actionsData } = homepageActionHooks.useList(
+        { where: { sectionId }, orderBy: 'sortOrder', orderDirection: 'asc' },
+        { ...ADMIN_LIST_QUERY_CONFIG, enabled: !!sectionId },
+    );
+
+    const createFeature = homepageFeatureHooks.useCreate();
+    const deleteFeature = homepageFeatureHooks.useDelete();
+    const createAction = homepageActionHooks.useCreate();
+    const deleteAction = homepageActionHooks.useDelete();
+
+    const features = (Array.isArray(featuresData) ? featuresData : []) as HomepageFeatureRow[];
+    const actions = (Array.isArray(actionsData) ? actionsData : []) as HomepageActionRow[];
+
+    // Local section form state
+    const section = sectionData as Record<string, unknown> | undefined;
+    const [title, setTitle] = useState('');
+    const [subtitle, setSubtitle] = useState('');
+    const [body, setBody] = useState('');
+    const [githubUrl, setGithubUrl] = useState('');
+    const [initialized, setInitialized] = useState(false);
+
+    // Populate form when section data loads
+    useEffect(() => {
+        if (section && !initialized) {
+            setTitle((section.title as string) ?? '');
+            setSubtitle((section.subtitle as string) ?? '');
+            setBody((section.body as string) ?? '');
+            setGithubUrl((section.githubUrl as string) ?? '');
+            setInitialized(true);
+        }
+    }, [section, initialized]);
+
+    const [deleteDialog, setDeleteDialog] = useState<{ type: 'feature' | 'action'; id: string } | null>(null);
+
+    const slot = (section?.slot as string) ?? '';
+    const dirty =
+        initialized &&
+        (title !== ((section?.title as string) ?? '') ||
+            subtitle !== ((section?.subtitle as string) ?? '') ||
+            body !== ((section?.body as string) ?? '') ||
+            githubUrl !== ((section?.githubUrl as string) ?? ''));
+
+    const handleSaveSection = useCallback(async () => {
+        if (!sectionId || !dirty) return;
+        await updateSection.mutateAsync({ id: sectionId, data: { title, subtitle, body, githubUrl } });
+    }, [sectionId, dirty, title, subtitle, body, githubUrl, updateSection]);
+
+    const handleAddFeature = useCallback(async () => {
+        if (!sectionId) return;
+        await createFeature.mutateAsync({
+            sectionId,
+            title: 'New Feature',
+            description: 'Describe this feature',
+            sortOrder: features.length,
+        });
+    }, [sectionId, createFeature, features.length]);
+
+    const handleAddAction = useCallback(async () => {
+        if (!sectionId) return;
+        await createAction.mutateAsync({
+            sectionId,
+            label: 'New Button',
+            href: '/',
+            variant: 'default',
+            external: false,
+            sortOrder: actions.length,
+        });
+    }, [sectionId, createAction, actions.length]);
+
+    const handleConfirmDelete = async () => {
+        if (!deleteDialog) return;
+        if (deleteDialog.type === 'feature') {
+            await deleteFeature.mutateAsync(deleteDialog.id);
+        } else {
+            await deleteAction.mutateAsync(deleteDialog.id);
+        }
+        setDeleteDialog(null);
+    };
+
+    if (sectionLoading) {
+        return (
+            <div className="space-y-6">
+                <HomepageAdminNav />
+                <Card>
+                    <CardContent className="py-12 text-center">
+                        <p className="text-muted-foreground">Loading section…</p>
+                    </CardContent>
+                </Card>
+            </div>
+        );
+    }
+
+    if (!section) {
+        return (
+            <div className="space-y-6">
+                <HomepageAdminNav />
+                <Card>
+                    <CardContent className="py-12 text-center">
+                        <p className="text-muted-foreground">Section not found.</p>
+                        <Button variant="outline" className="mt-4" onClick={() => navigate({ to: '/admin/homepage' })}>
+                            Back to Sections
+                        </Button>
+                    </CardContent>
+                </Card>
+            </div>
+        );
+    }
+
+    return (
+        <div className="space-y-6">
+            <HomepageAdminNav />
+
+            {/* Header */}
+            <div className="flex items-center gap-4">
+                <Button variant="ghost" size="icon" onClick={() => navigate({ to: '/admin/homepage' })}>
+                    <ArrowLeft className="h-4 w-4" />
+                </Button>
+                <div className="flex-1">
+                    <div className="flex items-center gap-2">
+                        <Badge variant="outline" className="font-mono text-xs">
+                            {slot}
+                        </Badge>
+                        <h1 className="text-2xl font-bold tracking-tight">{SLOT_LABELS[slot] ?? slot}</h1>
+                    </div>
+                    <p className="text-muted-foreground text-sm mt-0.5">
+                        Edit section content, features, and action buttons.
+                    </p>
+                </div>
+                <Button onClick={handleSaveSection} disabled={!dirty || updateSection.isPending}>
+                    <Save className="mr-2 h-4 w-4" />
+                    {updateSection.isPending ? 'Saving…' : 'Save'}
+                </Button>
+            </div>
+
+            {/* Section fields */}
+            <Card>
+                <CardHeader>
+                    <CardTitle className="text-base">Section Content</CardTitle>
+                    <CardDescription>Title, subtitle, and body text for this slot.</CardDescription>
+                </CardHeader>
+                <CardContent className="space-y-4">
+                    <div className="space-y-2">
+                        <Label htmlFor="section-title">Title</Label>
+                        <Input
+                            id="section-title"
+                            value={title}
+                            onChange={(e) => setTitle(e.target.value)}
+                            placeholder="Section heading"
+                        />
+                    </div>
+                    <div className="space-y-2">
+                        <Label htmlFor="section-subtitle">Subtitle</Label>
+                        <Input
+                            id="section-subtitle"
+                            value={subtitle}
+                            onChange={(e) => setSubtitle(e.target.value)}
+                            placeholder="Optional subtitle or tagline"
+                        />
+                    </div>
+                    <div className="space-y-2">
+                        <Label htmlFor="section-body">Body</Label>
+                        <Textarea
+                            id="section-body"
+                            value={body}
+                            onChange={(e) => setBody(e.target.value)}
+                            placeholder="Longer description (optional)"
+                            rows={4}
+                        />
+                    </div>
+                    <div className="space-y-2">
+                        <Label htmlFor="section-github">GitHub URL</Label>
+                        <Input
+                            id="section-github"
+                            value={githubUrl}
+                            onChange={(e) => setGithubUrl(e.target.value)}
+                            placeholder="https://github.com/..."
+                        />
+                    </div>
+                </CardContent>
+            </Card>
+
+            {/* Features */}
+            <Card>
+                <CardHeader className="pb-3">
+                    <div className="flex items-center justify-between">
+                        <div>
+                            <CardTitle className="text-base">Features</CardTitle>
+                            <CardDescription>Feature items displayed in this section.</CardDescription>
+                        </div>
+                        <Button
+                            variant="outline"
+                            size="sm"
+                            onClick={handleAddFeature}
+                            disabled={createFeature.isPending}
+                        >
+                            <Plus className="mr-1.5 h-3.5 w-3.5" />
+                            Add Feature
+                        </Button>
+                    </div>
+                </CardHeader>
+                <CardContent>
+                    {features.length === 0 ? (
+                        <p className="text-sm text-muted-foreground py-4 text-center">
+                            No features yet. Add one to display feature items in this section.
+                        </p>
+                    ) : (
+                        <div className="space-y-2">
+                            {features.map((f) => (
+                                <FeatureEditor
+                                    key={f.id}
+                                    feature={f}
+                                    onDelete={(id) => setDeleteDialog({ type: 'feature', id })}
+                                />
+                            ))}
+                        </div>
+                    )}
+                </CardContent>
+            </Card>
+
+            {/* Actions */}
+            <Card>
+                <CardHeader className="pb-3">
+                    <div className="flex items-center justify-between">
+                        <div>
+                            <CardTitle className="text-base">Action Buttons</CardTitle>
+                            <CardDescription>Call-to-action buttons for this section.</CardDescription>
+                        </div>
+                        <Button variant="outline" size="sm" onClick={handleAddAction} disabled={createAction.isPending}>
+                            <Plus className="mr-1.5 h-3.5 w-3.5" />
+                            Add Action
+                        </Button>
+                    </div>
+                </CardHeader>
+                <CardContent>
+                    {actions.length === 0 ? (
+                        <p className="text-sm text-muted-foreground py-4 text-center">
+                            No actions yet. Add buttons like "Get Started" or "Learn More".
+                        </p>
+                    ) : (
+                        <div className="space-y-2">
+                            {actions.map((a) => (
+                                <ActionEditor
+                                    key={a.id}
+                                    action={a}
+                                    onDelete={(id) => setDeleteDialog({ type: 'action', id })}
+                                />
+                            ))}
+                        </div>
+                    )}
+                </CardContent>
+            </Card>
+
+            {/* Delete confirmation */}
+            <AlertDialog open={deleteDialog !== null} onOpenChange={(open) => !open && setDeleteDialog(null)}>
+                <AlertDialogContent>
+                    <AlertDialogHeader>
+                        <AlertDialogTitle>
+                            Delete {deleteDialog?.type === 'feature' ? 'Feature' : 'Action'}?
+                        </AlertDialogTitle>
+                        <AlertDialogDescription>This item will be permanently removed.</AlertDialogDescription>
+                    </AlertDialogHeader>
+                    <AlertDialogFooter>
+                        <AlertDialogCancel>Cancel</AlertDialogCancel>
+                        <AlertDialogAction onClick={handleConfirmDelete}>Delete</AlertDialogAction>
+                    </AlertDialogFooter>
+                </AlertDialogContent>
+            </AlertDialog>
+        </div>
+    );
+}
diff --git a/apps/ottabase-template-app-tanstack/src/pages/admin/homepage/AdminHomepageSectionsPage.tsx b/apps/ottabase-template-app-tanstack/src/pages/admin/homepage/AdminHomepageSectionsPage.tsx
new file mode 100644
index 000000000..b62cf54f2
--- /dev/null
+++ b/apps/ottabase-template-app-tanstack/src/pages/admin/homepage/AdminHomepageSectionsPage.tsx
@@ -0,0 +1,427 @@
+/**
+ * Admin Homepage Sections List
+ *
+ * Lists all homepage sections (one per slot) with CRUD operations.
+ * Pattern: follows AdminBlogListPage.tsx / AdminChangelogListPage.tsx.
+ */
+import { ADMIN_LIST_QUERY_CONFIG } from '@/config/queryConfig';
+import {
+    homepageActionHooks,
+    homepageFeatureHooks,
+    homepageSectionHooks,
+    type HomepageActionRow,
+    type HomepageFeatureRow,
+    type HomepageSectionRow,
+} from '@/hooks/homepageHooks';
+import {
+    AlertDialog,
+    AlertDialogAction,
+    AlertDialogCancel,
+    AlertDialogContent,
+    AlertDialogDescription,
+    AlertDialogFooter,
+    AlertDialogHeader,
+    AlertDialogTitle,
+    Badge,
+    Button,
+    Card,
+    CardContent,
+    CardDescription,
+    CardHeader,
+    CardTitle,
+    Input,
+    Label,
+    Separator,
+    Textarea,
+} from '@ottabase/ui-shadcn';
+import { Link } from '@tanstack/react-router';
+import { Edit, ExternalLink, GripVertical, Layout, Plus, Trash2 } from 'lucide-react';
+import { useCallback, useState } from 'react';
+import { HomepageAdminNav } from './HomepageAdminNav';
+
+/** All homepage slot names — matches SLOT_NAMES on the Next.js side. */
+const SLOT_NAMES = ['navbar', 'hero', 'features', 'cta', 'footer', 'about'] as const;
+
+const SLOT_LABELS: Record<string, string> = {
+    navbar: 'Navigation Bar',
+    hero: 'Hero Section',
+    features: 'Features Section',
+    cta: 'Call-to-Action',
+    footer: 'Footer',
+    about: 'About Page',
+};
+
+// ── Inline mini-editors ─────────────────────────────────────────────────────
+
+/** Inline feature list for a section */
+function SectionFeatures({ sectionId }: { sectionId: string }) {
+    const { data, isLoading } = homepageFeatureHooks.useList(
+        { where: { sectionId }, orderBy: 'sortOrder', orderDirection: 'asc' },
+        ADMIN_LIST_QUERY_CONFIG,
+    );
+    const createFeature = homepageFeatureHooks.useCreate();
+    const deleteFeature = homepageFeatureHooks.useDelete();
+    const [adding, setAdding] = useState(false);
+    const [newTitle, setNewTitle] = useState('');
+    const [newDesc, setNewDesc] = useState('');
+
+    const features = (Array.isArray(data) ? data : []) as HomepageFeatureRow[];
+
+    const handleAdd = useCallback(async () => {
+        if (!newTitle.trim() || !newDesc.trim()) return;
+        await createFeature.mutateAsync({
+            sectionId,
+            title: newTitle.trim(),
+            description: newDesc.trim(),
+            sortOrder: features.length,
+        });
+        setNewTitle('');
+        setNewDesc('');
+        setAdding(false);
+    }, [createFeature, sectionId, newTitle, newDesc, features.length]);
+
+    if (isLoading) return <p className="text-xs text-muted-foreground">Loading features…</p>;
+
+    return (
+        <div className="space-y-2">
+            <div className="flex items-center justify-between">
+                <p className="text-xs font-medium text-muted-foreground uppercase tracking-wider">
+                    Features ({features.length})
+                </p>
+                <Button variant="ghost" size="sm" className="h-6 px-2 text-xs" onClick={() => setAdding(!adding)}>
+                    <Plus className="mr-1 h-3 w-3" />
+                    Add
+                </Button>
+            </div>
+            {features.map((f) => (
+                <div key={f.id} className="flex items-start gap-2 rounded border p-2 text-sm">
+                    <GripVertical className="mt-0.5 h-3.5 w-3.5 shrink-0 text-muted-foreground/50" />
+                    <div className="min-w-0 flex-1">
+                        <p className="font-medium">{f.title}</p>
+                        <p className="text-xs text-muted-foreground line-clamp-1">{f.description}</p>
+                    </div>
+                    <Button variant="ghost" size="icon" className="h-6 w-6" onClick={() => deleteFeature.mutate(f.id)}>
+                        <Trash2 className="h-3 w-3 text-destructive" />
+                    </Button>
+                </div>
+            ))}
+            {adding && (
+                <div className="space-y-2 rounded border border-dashed p-2">
+                    <Input
+                        placeholder="Feature title"
+                        value={newTitle}
+                        onChange={(e) => setNewTitle(e.target.value)}
+                        className="h-8 text-sm"
+                    />
+                    <Textarea
+                        placeholder="Short description"
+                        value={newDesc}
+                        onChange={(e) => setNewDesc(e.target.value)}
+                        rows={2}
+                        className="text-sm"
+                    />
+                    <div className="flex gap-2">
+                        <Button
+                            size="sm"
+                            className="h-7 text-xs"
+                            onClick={handleAdd}
+                            disabled={createFeature.isPending}
+                        >
+                            Save
+                        </Button>
+                        <Button
+                            variant="ghost"
+                            size="sm"
+                            className="h-7 text-xs"
+                            onClick={() => {
+                                setAdding(false);
+                                setNewTitle('');
+                                setNewDesc('');
+                            }}
+                        >
+                            Cancel
+                        </Button>
+                    </div>
+                </div>
+            )}
+        </div>
+    );
+}
+
+/** Inline action list for a section */
+function SectionActions({ sectionId }: { sectionId: string }) {
+    const { data, isLoading } = homepageActionHooks.useList(
+        { where: { sectionId }, orderBy: 'sortOrder', orderDirection: 'asc' },
+        ADMIN_LIST_QUERY_CONFIG,
+    );
+    const createAction = homepageActionHooks.useCreate();
+    const deleteAction = homepageActionHooks.useDelete();
+    const [adding, setAdding] = useState(false);
+    const [newLabel, setNewLabel] = useState('');
+    const [newHref, setNewHref] = useState('');
+    const [newVariant, setNewVariant] = useState('default');
+
+    const actions = (Array.isArray(data) ? data : []) as HomepageActionRow[];
+
+    const handleAdd = useCallback(async () => {
+        if (!newLabel.trim() || !newHref.trim()) return;
+        await createAction.mutateAsync({
+            sectionId,
+            label: newLabel.trim(),
+            href: newHref.trim(),
+            variant: newVariant,
+            external: newHref.startsWith('http'),
+            sortOrder: actions.length,
+        });
+        setNewLabel('');
+        setNewHref('');
+        setNewVariant('default');
+        setAdding(false);
+    }, [createAction, sectionId, newLabel, newHref, newVariant, actions.length]);
+
+    if (isLoading) return <p className="text-xs text-muted-foreground">Loading actions…</p>;
+
+    return (
+        <div className="space-y-2">
+            <div className="flex items-center justify-between">
+                <p className="text-xs font-medium text-muted-foreground uppercase tracking-wider">
+                    Actions ({actions.length})
+                </p>
+                <Button variant="ghost" size="sm" className="h-6 px-2 text-xs" onClick={() => setAdding(!adding)}>
+                    <Plus className="mr-1 h-3 w-3" />
+                    Add
+                </Button>
+            </div>
+            {actions.map((a) => (
+                <div key={a.id} className="flex items-center gap-2 rounded border p-2 text-sm">
+                    <GripVertical className="h-3.5 w-3.5 shrink-0 text-muted-foreground/50" />
+                    <Badge variant="outline" className="shrink-0 text-[10px]">
+                        {a.variant ?? 'default'}
+                    </Badge>
+                    <span className="truncate font-medium">{a.label}</span>
+                    <span className="ml-auto truncate text-xs text-muted-foreground">{a.href}</span>
+                    {a.external && <ExternalLink className="h-3 w-3 shrink-0 text-muted-foreground" />}
+                    <Button
+                        variant="ghost"
+                        size="icon"
+                        className="h-6 w-6 shrink-0"
+                        onClick={() => deleteAction.mutate(a.id)}
+                    >
+                        <Trash2 className="h-3 w-3 text-destructive" />
+                    </Button>
+                </div>
+            ))}
+            {adding && (
+                <div className="space-y-2 rounded border border-dashed p-2">
+                    <div className="flex gap-2">
+                        <Input
+                            placeholder="Label"
+                            value={newLabel}
+                            onChange={(e) => setNewLabel(e.target.value)}
+                            className="h-8 text-sm"
+                        />
+                        <Input
+                            placeholder="URL (e.g. /about or https://...)"
+                            value={newHref}
+                            onChange={(e) => setNewHref(e.target.value)}
+                            className="h-8 text-sm"
+                        />
+                    </div>
+                    <div className="flex items-center gap-2">
+                        <Label className="text-xs shrink-0">Style:</Label>
+                        <select
+                            value={newVariant}
+                            onChange={(e) => setNewVariant(e.target.value)}
+                            className="h-8 rounded-md border border-input bg-background px-2 text-xs"
+                            aria-label="Button variant"
+                        >
+                            <option value="default">Default</option>
+                            <option value="secondary">Secondary</option>
+                            <option value="outline">Outline</option>
+                            <option value="ghost">Ghost</option>
+                        </select>
+                    </div>
+                    <div className="flex gap-2">
+                        <Button size="sm" className="h-7 text-xs" onClick={handleAdd} disabled={createAction.isPending}>
+                            Save
+                        </Button>
+                        <Button
+                            variant="ghost"
+                            size="sm"
+                            className="h-7 text-xs"
+                            onClick={() => {
+                                setAdding(false);
+                                setNewLabel('');
+                                setNewHref('');
+                            }}
+                        >
+                            Cancel
+                        </Button>
+                    </div>
+                </div>
+            )}
+        </div>
+    );
+}
+
+// ── Main page ───────────────────────────────────────────────────────────────
+
+export function AdminHomepageSectionsPage() {
+    const { data, isLoading } = homepageSectionHooks.useList(
+        { orderBy: 'sortOrder', orderDirection: 'asc' },
+        ADMIN_LIST_QUERY_CONFIG,
+    );
+    const createSection = homepageSectionHooks.useCreate();
+    const deleteSection = homepageSectionHooks.useDelete();
+    const [deleteDialog, setDeleteDialog] = useState<{ id: string; slot: string } | null>(null);
+
+    const sections = (Array.isArray(data) ? data : []) as HomepageSectionRow[];
+    const usedSlots = new Set(sections.map((s) => s.slot));
+    const availableSlots = SLOT_NAMES.filter((s) => !usedSlots.has(s));
+
+    const handleCreateSection = async (slot: string) => {
+        await createSection.mutateAsync({
+            slot,
+            title: SLOT_LABELS[slot] ?? slot,
+            sortOrder: sections.length,
+        });
+    };
+
+    const handleConfirmDelete = async () => {
+        if (!deleteDialog) return;
+        try {
+            await deleteSection.mutateAsync(deleteDialog.id);
+        } catch (err) {
+            console.error('Failed to delete section:', err);
+        } finally {
+            setDeleteDialog(null);
+        }
+    };
+
+    return (
+        <div className="space-y-6">
+            <HomepageAdminNav />
+
+            {/* Header */}
+            <div className="flex flex-col gap-4 sm:flex-row sm:items-center sm:justify-between">
+                <div>
+                    <h1 className="text-3xl font-bold tracking-tight">Homepage Sections</h1>
+                    <p className="text-muted-foreground mt-1">
+                        Manage content for each homepage slot. Each slot drives the corresponding section on the Next.js
+                        homepage.
+                    </p>
+                </div>
+            </div>
+
+            {/* Quick-add for missing slots */}
+            {availableSlots.length > 0 && (
+                <Card>
+                    <CardHeader className="pb-3">
+                        <CardTitle className="text-base">Add Section</CardTitle>
+                        <CardDescription>Create a section for a slot that doesn't have one yet.</CardDescription>
+                    </CardHeader>
+                    <CardContent>
+                        <div className="flex flex-wrap gap-2">
+                            {availableSlots.map((slot) => (
+                                <Button
+                                    key={slot}
+                                    variant="outline"
+                                    size="sm"
+                                    onClick={() => handleCreateSection(slot)}
+                                    disabled={createSection.isPending}
+                                >
+                                    <Plus className="mr-1.5 h-3.5 w-3.5" />
+                                    {SLOT_LABELS[slot]}
+                                </Button>
+                            ))}
+                        </div>
+                    </CardContent>
+                </Card>
+            )}
+
+            {/* Loading */}
+            {isLoading && (
+                <Card>
+                    <CardContent className="py-12 text-center">
+                        <p className="text-muted-foreground">Loading sections…</p>
+                    </CardContent>
+                </Card>
+            )}
+
+            {/* Empty state */}
+            {!isLoading && sections.length === 0 && (
+                <Card>
+                    <CardContent className="py-12 text-center">
+                        <Layout className="mx-auto h-12 w-12 text-muted-foreground/50" />
+                        <h3 className="mt-4 text-lg font-semibold">No sections yet</h3>
+                        <p className="mt-2 text-muted-foreground">
+                            Create sections for each homepage slot to populate your site with DB-driven content.
+                        </p>
+                    </CardContent>
+                </Card>
+            )}
+
+            {/* Section cards */}
+            {sections.map((section) => (
+                <Card key={section.id}>
+                    <CardHeader className="pb-3">
+                        <div className="flex items-start justify-between">
+                            <div>
+                                <div className="flex items-center gap-2">
+                                    <Badge variant="outline" className="font-mono text-xs">
+                                        {section.slot}
+                                    </Badge>
+                                    <CardTitle className="text-lg">{section.title ?? '(untitled)'}</CardTitle>
+                                </div>
+                                {section.subtitle && (
+                                    <CardDescription className="mt-1">{section.subtitle}</CardDescription>
+                                )}
+                            </div>
+                            <div className="flex gap-1">
+                                <Button variant="ghost" size="icon" asChild>
+                                    <Link to="/admin/homepage/$sectionId/edit" params={{ sectionId: section.id }}>
+                                        <Edit className="h-4 w-4" />
+                                    </Link>
+                                </Button>
+                                <Button
+                                    variant="ghost"
+                                    size="icon"
+                                    onClick={() => setDeleteDialog({ id: section.id, slot: section.slot })}
+                                >
+                                    <Trash2 className="h-4 w-4 text-destructive" />
+                                </Button>
+                            </div>
+                        </div>
+                    </CardHeader>
+                    <CardContent className="space-y-4">
+                        {section.body && <p className="text-sm text-muted-foreground line-clamp-2">{section.body}</p>}
+
+                        <div className="grid gap-4 md:grid-cols-2">
+                            <SectionFeatures sectionId={section.id} />
+                            <SectionActions sectionId={section.id} />
+                        </div>
+                    </CardContent>
+                </Card>
+            ))}
+
+            {/* Delete confirmation */}
+            <AlertDialog open={deleteDialog !== null} onOpenChange={(open) => !open && setDeleteDialog(null)}>
+                <AlertDialogContent>
+                    <AlertDialogHeader>
+                        <AlertDialogTitle>Delete Section?</AlertDialogTitle>
+                        <AlertDialogDescription>
+                            This will permanently remove the "{deleteDialog?.slot}" section and all its features and
+                            actions. This cannot be undone.
+                        </AlertDialogDescription>
+                    </AlertDialogHeader>
+                    <AlertDialogFooter>
+                        <AlertDialogCancel disabled={deleteSection.isPending}>Cancel</AlertDialogCancel>
+                        <AlertDialogAction onClick={handleConfirmDelete} disabled={deleteSection.isPending}>
+                            Delete
+                        </AlertDialogAction>
+                    </AlertDialogFooter>
+                </AlertDialogContent>
+            </AlertDialog>
+        </div>
+    );
+}
diff --git a/apps/ottabase-template-app-tanstack/src/pages/admin/homepage/HomepageAdminNav.tsx b/apps/ottabase-template-app-tanstack/src/pages/admin/homepage/HomepageAdminNav.tsx
new file mode 100644
index 000000000..ad2aade63
--- /dev/null
+++ b/apps/ottabase-template-app-tanstack/src/pages/admin/homepage/HomepageAdminNav.tsx
@@ -0,0 +1,38 @@
+/**
+ * Homepage Admin Navigation
+ *
+ * Tab navigation for the homepage management section.
+ * Pattern: follows BlogAdminNav.tsx.
+ */
+import { Link, useRouterState } from '@tanstack/react-router';
+
+const TABS = [
+    { href: '/admin/homepage', label: 'Sections', exact: true },
+    { href: '/admin/homepage/display', label: 'Display Settings' },
+] as const;
+
+export function HomepageAdminNav() {
+    const { location } = useRouterState();
+    const pathname = location.pathname;
+
+    return (
+        <nav className="flex gap-1 border-b pb-2" aria-label="Homepage admin navigation">
+            {TABS.map(({ href, label, exact }) => {
+                const isActive = exact ? pathname === href : pathname.startsWith(href);
+                return (
+                    <Link
+                        key={href}
+                        to={href}
+                        className={`rounded-md px-3 py-1.5 text-sm font-medium transition-colors ${
+                            isActive
+                                ? 'bg-primary text-primary-foreground'
+                                : 'text-muted-foreground hover:bg-muted hover:text-foreground'
+                        }`}
+                    >
+                        {label}
+                    </Link>
+                );
+            })}
+        </nav>
+    );
+}
diff --git a/apps/ottabase-template-app-tanstack/src/pages/admin/homepage/index.ts b/apps/ottabase-template-app-tanstack/src/pages/admin/homepage/index.ts
new file mode 100644
index 000000000..7c3d4dbdf
--- /dev/null
+++ b/apps/ottabase-template-app-tanstack/src/pages/admin/homepage/index.ts
@@ -0,0 +1,4 @@
+export { AdminHomepageDisplayPage } from './AdminHomepageDisplayPage';
+export { AdminHomepageSectionEditorPage } from './AdminHomepageSectionEditorPage';
+export { AdminHomepageSectionsPage } from './AdminHomepageSectionsPage';
+export { HomepageAdminNav } from './HomepageAdminNav';
diff --git a/apps/ottabase-template-app-tanstack/src/router.tsx b/apps/ottabase-template-app-tanstack/src/router.tsx
index f91aeee1b..a76a4b371 100644
--- a/apps/ottabase-template-app-tanstack/src/router.tsx
+++ b/apps/ottabase-template-app-tanstack/src/router.tsx
@@ -931,6 +931,37 @@ const adminChangelogEditRoute = new Route({
     ),
 });
 
+// Homepage admin routes
+const adminHomepageRoute = new Route({
+    getParentRoute: () => rootRoute,
+    path: '/admin/homepage',
+    component: lazyRouteComponent(() =>
+        import('@/pages/admin/homepage/AdminHomepageSectionsPage').then((m) => ({
+            default: () => renderAdminRoute(<m.AdminHomepageSectionsPage />),
+        })),
+    ),
+});
+
+const adminHomepageSectionEditRoute = new Route({
+    getParentRoute: () => rootRoute,
+    path: '/admin/homepage/$sectionId/edit',
+    component: lazyRouteComponent(() =>
+        import('@/pages/admin/homepage/AdminHomepageSectionEditorPage').then((m) => ({
+            default: () => renderAdminRoute(<m.AdminHomepageSectionEditorPage />),
+        })),
+    ),
+});
+
+const adminHomepageDisplayRoute = new Route({
+    getParentRoute: () => rootRoute,
+    path: '/admin/homepage/display',
+    component: lazyRouteComponent(() =>
+        import('@/pages/admin/homepage/AdminHomepageDisplayPage').then((m) => ({
+            default: () => renderAdminRoute(<m.AdminHomepageDisplayPage />),
+        })),
+    ),
+});
+
 // Organizations routes
 const organizationsRoute = new Route({
     getParentRoute: () => rootRoute,
@@ -1162,6 +1193,9 @@ const coreRoutes = [
     adminChangelogRoute,
     adminChangelogNewRoute,
     adminChangelogEditRoute,
+    adminHomepageRoute,
+    adminHomepageSectionEditRoute,
+    adminHomepageDisplayRoute,
     adminDevMailRoute,
     adminQueueRoute,
     adminCronRoute,

From eeec6deb2177d537cc86af6eafe1141c8faeffa9 Mon Sep 17 00:00:00 2001
From: "copilot-swe-agent[bot]" <198982749+Copilot@users.noreply.github.com>
Date: Mon, 30 Mar 2026 19:13:10 +0000
Subject: [PATCH 08/19] refactor: extract shared homepage-constants.ts, fix
 setTimeout anti-pattern with useEffect+useRef

Agent-Logs-Url: https://github.com/thinkdj/ottabase/sessions/100ba360-6a73-4e2b-ad44-5369c4583ca8
---
 .../homepage/AdminHomepageDisplayPage.tsx     |  78 +-----------
 .../AdminHomepageSectionEditorPage.tsx        |  60 +++++----
 .../homepage/AdminHomepageSectionsPage.tsx    |  23 +---
 .../admin/homepage/homepage-constants.ts      | 115 ++++++++++++++++++
 .../src/pages/admin/homepage/index.ts         |   1 +
 5 files changed, 156 insertions(+), 121 deletions(-)
 create mode 100644 apps/ottabase-template-app-tanstack/src/pages/admin/homepage/homepage-constants.ts

diff --git a/apps/ottabase-template-app-tanstack/src/pages/admin/homepage/AdminHomepageDisplayPage.tsx b/apps/ottabase-template-app-tanstack/src/pages/admin/homepage/AdminHomepageDisplayPage.tsx
index 7fc834873..c9ca46f12 100644
--- a/apps/ottabase-template-app-tanstack/src/pages/admin/homepage/AdminHomepageDisplayPage.tsx
+++ b/apps/ottabase-template-app-tanstack/src/pages/admin/homepage/AdminHomepageDisplayPage.tsx
@@ -24,75 +24,7 @@ import {
 import { Check, Monitor, Save } from 'lucide-react';
 import { useCallback, useEffect, useState } from 'react';
 import { HomepageAdminNav } from './HomepageAdminNav';
-
-/** Matches SLOT_NAMES + SLOT_REGISTRY from the Next.js homepage-config. */
-const SLOT_CONFIG = {
-    navbar: {
-        label: 'Navigation Bar',
-        variants: [
-            { id: 'default', label: 'Default', desc: 'Logo left, links right, mobile hamburger.' },
-            { id: 'centered', label: 'Centered', desc: 'Logo and links centered.' },
-            { id: 'minimal', label: 'Minimal', desc: 'Logo and dark-mode toggle only.' },
-        ],
-        default: 'default',
-    },
-    hero: {
-        label: 'Hero Section',
-        variants: [
-            { id: 'centered', label: 'Centered', desc: 'Large centered headline with buttons.' },
-            { id: 'split', label: 'Split', desc: 'Text left, visual right.' },
-            { id: 'minimal', label: 'Minimal', desc: 'Compact headline.' },
-        ],
-        default: 'centered',
-    },
-    features: {
-        label: 'Features Section',
-        variants: [
-            { id: 'grid', label: 'Grid', desc: 'Two-column bordered list.' },
-            { id: 'cards', label: 'Cards', desc: 'Card layout with hover effects.' },
-            { id: 'list', label: 'List', desc: 'Vertical stacked list.' },
-        ],
-        default: 'grid',
-    },
-    cta: {
-        label: 'Call-to-Action',
-        variants: [
-            { id: 'default', label: 'Default', desc: 'Centered text with buttons.' },
-            { id: 'banner', label: 'Banner', desc: 'Full-width colored banner.' },
-            { id: 'minimal', label: 'Minimal', desc: 'Compact inline CTA.' },
-        ],
-        default: 'default',
-    },
-    footer: {
-        label: 'Footer',
-        variants: [
-            { id: 'default', label: 'Default', desc: 'Copyright and links row.' },
-            { id: 'minimal', label: 'Minimal', desc: 'Single-line copyright.' },
-            { id: 'columns', label: 'Columns', desc: 'Multi-column grouped links.' },
-        ],
-        default: 'default',
-    },
-    about: {
-        label: 'About Page',
-        variants: [
-            { id: 'default', label: 'Default', desc: 'Full content with features, steps, CTA.' },
-            { id: 'minimal', label: 'Minimal', desc: 'Concise single-section.' },
-            { id: 'detailed', label: 'Detailed', desc: 'Card-based with tech-stack badges.' },
-        ],
-        default: 'default',
-    },
-} as const;
-
-type SlotName = keyof typeof SLOT_CONFIG;
-const SLOT_NAMES = Object.keys(SLOT_CONFIG) as SlotName[];
-
-function getDefaults(): Record<string, string> {
-    const d: Record<string, string> = {};
-    for (const [k, v] of Object.entries(SLOT_CONFIG)) {
-        d[k] = v.default;
-    }
-    return d;
-}
+import { getDefaultVariantBySlot, SLOT_CONFIG, SLOT_NAMES, type SlotName } from './homepage-constants';
 
 export function AdminHomepageDisplayPage() {
     const { data, isLoading } = homepageDisplaySettingsHooks.useList({}, ADMIN_LIST_QUERY_CONFIG);
@@ -103,14 +35,14 @@ export function AdminHomepageDisplayPage() {
     const rows = (Array.isArray(data) ? data : []) as HomepageDisplaySettingsRow[];
     const existing = rows.find((r) => r.id === 'default') ?? null;
 
-    const [variantBySlot, setVariantBySlot] = useState<Record<string, string>>(getDefaults());
+    const [variantBySlot, setVariantBySlot] = useState<Record<string, string>>(getDefaultVariantBySlot());
     const [themePreset, setThemePreset] = useState('default');
     const [initialized, setInitialized] = useState(false);
 
     // Populate from DB when data loads
     useEffect(() => {
         if (existing && !initialized) {
-            setVariantBySlot({ ...getDefaults(), ...(existing.variantBySlotJson ?? {}) });
+            setVariantBySlot({ ...getDefaultVariantBySlot(), ...(existing.variantBySlotJson ?? {}) });
             setThemePreset(existing.themePreset ?? 'default');
             setInitialized(true);
         } else if (!isLoading && !existing && !initialized) {
@@ -122,7 +54,7 @@ export function AdminHomepageDisplayPage() {
     const isDirty =
         initialized &&
         (JSON.stringify(variantBySlot) !==
-            JSON.stringify({ ...getDefaults(), ...(existing?.variantBySlotJson ?? {}) }) ||
+            JSON.stringify({ ...getDefaultVariantBySlot(), ...(existing?.variantBySlotJson ?? {}) }) ||
             themePreset !== (existing?.themePreset ?? 'default'));
 
     const handleSave = useCallback(async () => {
@@ -142,7 +74,7 @@ export function AdminHomepageDisplayPage() {
     };
 
     const handleResetDefaults = () => {
-        setVariantBySlot(getDefaults());
+        setVariantBySlot(getDefaultVariantBySlot());
         setThemePreset('default');
     };
 
diff --git a/apps/ottabase-template-app-tanstack/src/pages/admin/homepage/AdminHomepageSectionEditorPage.tsx b/apps/ottabase-template-app-tanstack/src/pages/admin/homepage/AdminHomepageSectionEditorPage.tsx
index dbb64d867..a4389fbc7 100644
--- a/apps/ottabase-template-app-tanstack/src/pages/admin/homepage/AdminHomepageSectionEditorPage.tsx
+++ b/apps/ottabase-template-app-tanstack/src/pages/admin/homepage/AdminHomepageSectionEditorPage.tsx
@@ -32,30 +32,14 @@ import {
     CardTitle,
     Input,
     Label,
-    Separator,
     Switch,
     Textarea,
 } from '@ottabase/ui-shadcn';
 import { useNavigate, useParams } from '@tanstack/react-router';
 import { ArrowLeft, ExternalLink, GripVertical, Plus, Save, Trash2 } from 'lucide-react';
-import { useCallback, useEffect, useState } from 'react';
+import { useCallback, useEffect, useRef, useState } from 'react';
 import { HomepageAdminNav } from './HomepageAdminNav';
-
-const SLOT_LABELS: Record<string, string> = {
-    navbar: 'Navigation Bar',
-    hero: 'Hero Section',
-    features: 'Features Section',
-    cta: 'Call-to-Action',
-    footer: 'Footer',
-    about: 'About Page',
-};
-
-const ACTION_VARIANTS = [
-    { value: 'default', label: 'Default' },
-    { value: 'secondary', label: 'Secondary' },
-    { value: 'outline', label: 'Outline' },
-    { value: 'ghost', label: 'Ghost' },
-] as const;
+import { ACTION_VARIANTS, SLOT_LABELS } from './homepage-constants';
 
 // ── Feature row editor ──────────────────────────────────────────────────────
 
@@ -112,6 +96,11 @@ function ActionEditor({ action, onDelete }: { action: HomepageActionRow; onDelet
     const [href, setHref] = useState(action.href);
     const [variant, setVariant] = useState(action.variant ?? 'default');
     const [external, setExternal] = useState(action.external);
+
+    // Track previous values for useEffect-based auto-save
+    const prevVariantRef = useRef(variant);
+    const prevExternalRef = useRef(external);
+
     const dirty =
         label !== action.label ||
         href !== action.href ||
@@ -126,6 +115,26 @@ function ActionEditor({ action, onDelete }: { action: HomepageActionRow; onDelet
         });
     }, [dirty, action.id, label, href, variant, external, updateAction]);
 
+    // Auto-save when variant or external toggle changes (replaces setTimeout)
+    useEffect(() => {
+        if (variant !== prevVariantRef.current || external !== prevExternalRef.current) {
+            prevVariantRef.current = variant;
+            prevExternalRef.current = external;
+            // Compute dirty inline since the callback may have stale closure
+            const isDirty =
+                label !== action.label ||
+                href !== action.href ||
+                variant !== (action.variant ?? 'default') ||
+                external !== action.external;
+            if (isDirty) {
+                updateAction.mutate({
+                    id: action.id,
+                    data: { label, href, variant, external },
+                });
+            }
+        }
+    }, [variant, external]); // eslint-disable-line react-hooks/exhaustive-deps
+
     return (
         <div className="flex items-start gap-2 rounded-lg border p-3">
             <GripVertical className="mt-2 h-4 w-4 shrink-0 text-muted-foreground/40 cursor-grab" />
@@ -151,11 +160,7 @@ function ActionEditor({ action, onDelete }: { action: HomepageActionRow; onDelet
                         <Label className="text-xs">Style:</Label>
                         <select
                             value={variant}
-                            onChange={(e) => {
-                                setVariant(e.target.value);
-                                // Trigger save after state update
-                                setTimeout(() => handleSave(), 0);
-                            }}
+                            onChange={(e) => setVariant(e.target.value)}
                             className="h-7 rounded-md border border-input bg-background px-2 text-xs"
                             aria-label="Button style variant"
                         >
@@ -167,14 +172,7 @@ function ActionEditor({ action, onDelete }: { action: HomepageActionRow; onDelet
                         </select>
                     </div>
                     <div className="flex items-center gap-2">
-                        <Switch
-                            id={`external-${action.id}`}
-                            checked={external}
-                            onCheckedChange={(checked) => {
-                                setExternal(checked);
-                                setTimeout(() => handleSave(), 0);
-                            }}
-                        />
+                        <Switch id={`external-${action.id}`} checked={external} onCheckedChange={setExternal} />
                         <Label htmlFor={`external-${action.id}`} className="text-xs">
                             External
                         </Label>
diff --git a/apps/ottabase-template-app-tanstack/src/pages/admin/homepage/AdminHomepageSectionsPage.tsx b/apps/ottabase-template-app-tanstack/src/pages/admin/homepage/AdminHomepageSectionsPage.tsx
index b62cf54f2..5706f60cf 100644
--- a/apps/ottabase-template-app-tanstack/src/pages/admin/homepage/AdminHomepageSectionsPage.tsx
+++ b/apps/ottabase-template-app-tanstack/src/pages/admin/homepage/AdminHomepageSectionsPage.tsx
@@ -31,25 +31,13 @@ import {
     CardTitle,
     Input,
     Label,
-    Separator,
     Textarea,
 } from '@ottabase/ui-shadcn';
 import { Link } from '@tanstack/react-router';
 import { Edit, ExternalLink, GripVertical, Layout, Plus, Trash2 } from 'lucide-react';
 import { useCallback, useState } from 'react';
 import { HomepageAdminNav } from './HomepageAdminNav';
-
-/** All homepage slot names — matches SLOT_NAMES on the Next.js side. */
-const SLOT_NAMES = ['navbar', 'hero', 'features', 'cta', 'footer', 'about'] as const;
-
-const SLOT_LABELS: Record<string, string> = {
-    navbar: 'Navigation Bar',
-    hero: 'Hero Section',
-    features: 'Features Section',
-    cta: 'Call-to-Action',
-    footer: 'Footer',
-    about: 'About Page',
-};
+import { ACTION_VARIANTS, SLOT_LABELS, SLOT_NAMES } from './homepage-constants';
 
 // ── Inline mini-editors ─────────────────────────────────────────────────────
 
@@ -235,10 +223,11 @@ function SectionActions({ sectionId }: { sectionId: string }) {
                             className="h-8 rounded-md border border-input bg-background px-2 text-xs"
                             aria-label="Button variant"
                         >
-                            <option value="default">Default</option>
-                            <option value="secondary">Secondary</option>
-                            <option value="outline">Outline</option>
-                            <option value="ghost">Ghost</option>
+                            {ACTION_VARIANTS.map((v) => (
+                                <option key={v.value} value={v.value}>
+                                    {v.label}
+                                </option>
+                            ))}
                         </select>
                     </div>
                     <div className="flex gap-2">
diff --git a/apps/ottabase-template-app-tanstack/src/pages/admin/homepage/homepage-constants.ts b/apps/ottabase-template-app-tanstack/src/pages/admin/homepage/homepage-constants.ts
new file mode 100644
index 000000000..b51340b09
--- /dev/null
+++ b/apps/ottabase-template-app-tanstack/src/pages/admin/homepage/homepage-constants.ts
@@ -0,0 +1,115 @@
+/**
+ * Homepage Admin Constants
+ *
+ * Single source of truth for slot names, labels, variant metadata,
+ * and action button variants used across all homepage admin pages.
+ *
+ * Mirrors SLOT_NAMES and SLOT_REGISTRY from the Next.js homepage-config.ts.
+ */
+
+/** All homepage slot names — matches SLOT_NAMES on the Next.js side. */
+export const SLOT_NAMES = ['navbar', 'hero', 'features', 'cta', 'footer', 'about'] as const;
+export type SlotName = (typeof SLOT_NAMES)[number];
+
+/** Human-readable labels for each slot. */
+export const SLOT_LABELS: Record<SlotName, string> = {
+    navbar: 'Navigation Bar',
+    hero: 'Hero Section',
+    features: 'Features Section',
+    cta: 'Call-to-Action',
+    footer: 'Footer',
+    about: 'About Page',
+};
+
+/** Available button style variants (matches shadcn Button component). */
+export const ACTION_VARIANTS = [
+    { value: 'default', label: 'Default' },
+    { value: 'secondary', label: 'Secondary' },
+    { value: 'outline', label: 'Outline' },
+    { value: 'ghost', label: 'Ghost' },
+] as const;
+
+/** Variant option for a slot's display mode. */
+export interface SlotVariantOption {
+    id: string;
+    label: string;
+    desc: string;
+}
+
+/** Full slot configuration including available variants. */
+export interface SlotConfig {
+    label: string;
+    variants: readonly SlotVariantOption[];
+    default: string;
+}
+
+/**
+ * Slot configuration registry — maps each slot to its available
+ * variant options and default selection. Mirrors SLOT_REGISTRY on the
+ * Next.js side (homepage-config.ts).
+ */
+export const SLOT_CONFIG: Record<SlotName, SlotConfig> = {
+    navbar: {
+        label: 'Navigation Bar',
+        variants: [
+            { id: 'default', label: 'Default', desc: 'Logo left, links right, mobile hamburger.' },
+            { id: 'centered', label: 'Centered', desc: 'Logo and links centered.' },
+            { id: 'minimal', label: 'Minimal', desc: 'Logo and dark-mode toggle only.' },
+        ],
+        default: 'default',
+    },
+    hero: {
+        label: 'Hero Section',
+        variants: [
+            { id: 'centered', label: 'Centered', desc: 'Large centered headline with buttons.' },
+            { id: 'split', label: 'Split', desc: 'Text left, visual right.' },
+            { id: 'minimal', label: 'Minimal', desc: 'Compact headline.' },
+        ],
+        default: 'centered',
+    },
+    features: {
+        label: 'Features Section',
+        variants: [
+            { id: 'grid', label: 'Grid', desc: 'Two-column bordered list.' },
+            { id: 'cards', label: 'Cards', desc: 'Card layout with hover effects.' },
+            { id: 'list', label: 'List', desc: 'Vertical stacked list.' },
+        ],
+        default: 'grid',
+    },
+    cta: {
+        label: 'Call-to-Action',
+        variants: [
+            { id: 'default', label: 'Default', desc: 'Centered text with buttons.' },
+            { id: 'banner', label: 'Banner', desc: 'Full-width colored banner.' },
+            { id: 'minimal', label: 'Minimal', desc: 'Compact inline CTA.' },
+        ],
+        default: 'default',
+    },
+    footer: {
+        label: 'Footer',
+        variants: [
+            { id: 'default', label: 'Default', desc: 'Copyright and links row.' },
+            { id: 'minimal', label: 'Minimal', desc: 'Single-line copyright.' },
+            { id: 'columns', label: 'Columns', desc: 'Multi-column grouped links.' },
+        ],
+        default: 'default',
+    },
+    about: {
+        label: 'About Page',
+        variants: [
+            { id: 'default', label: 'Default', desc: 'Full content with features, steps, CTA.' },
+            { id: 'minimal', label: 'Minimal', desc: 'Concise single-section.' },
+            { id: 'detailed', label: 'Detailed', desc: 'Card-based with tech-stack badges.' },
+        ],
+        default: 'default',
+    },
+};
+
+/** Returns the default variant selection for all slots. */
+export function getDefaultVariantBySlot(): Record<string, string> {
+    const d: Record<string, string> = {};
+    for (const [k, v] of Object.entries(SLOT_CONFIG)) {
+        d[k] = v.default;
+    }
+    return d;
+}
diff --git a/apps/ottabase-template-app-tanstack/src/pages/admin/homepage/index.ts b/apps/ottabase-template-app-tanstack/src/pages/admin/homepage/index.ts
index 7c3d4dbdf..44755840d 100644
--- a/apps/ottabase-template-app-tanstack/src/pages/admin/homepage/index.ts
+++ b/apps/ottabase-template-app-tanstack/src/pages/admin/homepage/index.ts
@@ -2,3 +2,4 @@ export { AdminHomepageDisplayPage } from './AdminHomepageDisplayPage';
 export { AdminHomepageSectionEditorPage } from './AdminHomepageSectionEditorPage';
 export { AdminHomepageSectionsPage } from './AdminHomepageSectionsPage';
 export { HomepageAdminNav } from './HomepageAdminNav';
+export { ACTION_VARIANTS, SLOT_CONFIG, SLOT_LABELS, SLOT_NAMES } from './homepage-constants';

From 0cb155f1c09fcb2878a3782425aed7b9c487aecd Mon Sep 17 00:00:00 2001
From: "copilot-swe-agent[bot]" <198982749+Copilot@users.noreply.github.com>
Date: Mon, 30 Mar 2026 21:36:44 +0000
Subject: [PATCH 09/19] =?UTF-8?q?feat:=20enhance=20homepage=20system=20?=
 =?UTF-8?q?=E2=80=94=20add=20enabled/icon/metadata/cssClasses=20to=20secti?=
 =?UTF-8?q?ons,=20icon/imageUrl/href=20to=20features,=20icon=20to=20action?=
 =?UTF-8?q?s,=20customCss/seo=20to=20display=20settings;=20rewrite=20admin?=
 =?UTF-8?q?=20UI=20with=20Tabs=20nav,=20enable/disable=20toggles,=20sort?=
 =?UTF-8?q?=20controls,=20collapsible=20children,=20new=20Pages=20tab?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Agent-Logs-Url: https://github.com/thinkdj/ottabase/sessions/ae722b66-1678-4b6e-9ba2-78d05e83ba45

Co-authored-by: thinkdj <688055+thinkdj@users.noreply.github.com>
---
 .../app/layout-shell.tsx                      |  14 +-
 .../lib/api.ts                                |  16 +-
 .../ottabase/models/HomepageAction.schema.ts  |   2 +
 .../ottabase/models/HomepageAction.ts         |  12 +-
 .../models/HomepageDisplaySettings.schema.ts  |   8 +
 .../models/HomepageDisplaySettings.ts         |  28 +-
 .../ottabase/models/HomepageFeature.schema.ts |   6 +
 .../ottabase/models/HomepageFeature.ts        |  26 +-
 .../ottabase/models/HomepageSection.schema.ts |   8 +
 .../ottabase/models/HomepageSection.ts        |  41 +-
 .../src/hooks/homepageHooks.ts                |  11 +
 .../homepage/AdminHomepageDisplayPage.tsx     | 232 +++++--
 .../admin/homepage/AdminHomepagePagesPage.tsx | 195 ++++++
 .../AdminHomepageSectionEditorPage.tsx        | 568 ++++++++++++++----
 .../homepage/AdminHomepageSectionsPage.tsx    | 293 +++++++--
 .../pages/admin/homepage/HomepageAdminNav.tsx |  58 +-
 .../admin/homepage/homepage-constants.ts      |  43 +-
 .../src/pages/admin/homepage/index.ts         |  12 +-
 .../src/router.tsx                            |  11 +
 .../worker/routes/homepage.ts                 |  33 +-
 20 files changed, 1322 insertions(+), 295 deletions(-)
 create mode 100644 apps/ottabase-template-app-tanstack/src/pages/admin/homepage/AdminHomepagePagesPage.tsx

diff --git a/apps/ottabase-template-app-nextjs-homepage/app/layout-shell.tsx b/apps/ottabase-template-app-nextjs-homepage/app/layout-shell.tsx
index 01a2cf710..f3d7d5a5c 100644
--- a/apps/ottabase-template-app-nextjs-homepage/app/layout-shell.tsx
+++ b/apps/ottabase-template-app-nextjs-homepage/app/layout-shell.tsx
@@ -44,10 +44,14 @@ export function mergeNavLinks(baseLinks: NavLink[], exposedPages: { slug: string
 /**
  * Build slot data overrides from the homepage API sections.
  * Maps section data to the SlotRenderer data contracts.
+ * Only includes enabled sections.
  */
 function buildSlotDataFromSections(sections: HomepageDataPayload['sections']) {
     const dataBySlot: Record<string, Record<string, unknown>> = {};
     for (const section of sections) {
+        // Skip disabled sections
+        if (section.enabled === false) continue;
+
         const slot = section.slot;
         if (slot === 'hero') {
             dataBySlot[slot] = {
@@ -58,13 +62,20 @@ function buildSlotDataFromSections(sections: HomepageDataPayload['sections']) {
                     label: a.label,
                     href: a.href,
                     variant: a.variant ?? 'default',
+                    icon: a.icon ?? undefined,
                     external: a.external,
                 })),
             };
         } else if (slot === 'features') {
             dataBySlot[slot] = {
                 title: section.title ?? undefined,
-                features: section.features,
+                features: section.features.map((f) => ({
+                    title: f.title,
+                    description: f.description,
+                    icon: f.icon ?? undefined,
+                    imageUrl: f.imageUrl ?? undefined,
+                    href: f.href ?? undefined,
+                })),
             };
         } else if (slot === 'cta') {
             dataBySlot[slot] = {
@@ -74,6 +85,7 @@ function buildSlotDataFromSections(sections: HomepageDataPayload['sections']) {
                     label: a.label,
                     href: a.href,
                     variant: a.variant ?? 'default',
+                    icon: a.icon ?? undefined,
                     external: a.external,
                 })),
             };
diff --git a/apps/ottabase-template-app-nextjs-homepage/lib/api.ts b/apps/ottabase-template-app-nextjs-homepage/lib/api.ts
index cc9b8cd7e..1ccb2477a 100644
--- a/apps/ottabase-template-app-nextjs-homepage/lib/api.ts
+++ b/apps/ottabase-template-app-nextjs-homepage/lib/api.ts
@@ -56,12 +56,23 @@ export interface HomepageSectionPayload {
     subtitle: string | null;
     body: string | null;
     githubUrl: string | null;
+    icon: string | null;
+    enabled: boolean;
+    cssClasses: string | null;
+    metadata: Record<string, unknown> | null;
     sortOrder: number;
-    features: Array<{ title: string; description: string }>;
+    features: Array<{
+        title: string;
+        description: string;
+        icon: string | null;
+        imageUrl: string | null;
+        href: string | null;
+    }>;
     actions: Array<{
         label: string;
         href: string;
         variant: string | null;
+        icon: string | null;
         external: boolean;
     }>;
 }
@@ -71,6 +82,9 @@ export interface HomepageDisplayPayload {
     variantBySlot: Record<string, string> | null;
     themePreset: string | null;
     fallbackThemePresetId: string | null;
+    customCss: string | null;
+    seoTitle: string | null;
+    seoDescription: string | null;
 }
 
 /** Full homepage data payload from GET /api/homepage/data */
diff --git a/apps/ottabase-template-app-tanstack/ottabase/models/HomepageAction.schema.ts b/apps/ottabase-template-app-tanstack/ottabase/models/HomepageAction.schema.ts
index e7a6cd572..b68ebb924 100644
--- a/apps/ottabase-template-app-tanstack/ottabase/models/HomepageAction.schema.ts
+++ b/apps/ottabase-template-app-tanstack/ottabase/models/HomepageAction.schema.ts
@@ -17,6 +17,8 @@ export const homepageActionsTable = sqliteTable('homepage_actions', {
     href: text('href').notNull(),
     /** Button style variant: default, secondary, outline, ghost */
     variant: text('variant').default('default'),
+    /** Lucide icon name for the button (e.g. 'ArrowRight', 'Github') */
+    icon: text('icon'),
     /** Whether the link opens in a new tab */
     external: integer('external', { mode: 'boolean' }).default(false),
     /** Display order */
diff --git a/apps/ottabase-template-app-tanstack/ottabase/models/HomepageAction.ts b/apps/ottabase-template-app-tanstack/ottabase/models/HomepageAction.ts
index d310e8080..a9cf5d481 100644
--- a/apps/ottabase-template-app-tanstack/ottabase/models/HomepageAction.ts
+++ b/apps/ottabase-template-app-tanstack/ottabase/models/HomepageAction.ts
@@ -9,6 +9,7 @@ export { homepageActionsTable, type HomepageActionRow, type NewHomepageActionRow
 
 /**
  * A call-to-action button belonging to a homepage section (hero, cta, about, etc.).
+ * Supports icon, variant styling, and external link configuration.
  */
 export class HomepageAction extends BaseModel {
     static entity = 'homepage_actions';
@@ -25,8 +26,8 @@ export class HomepageAction extends BaseModel {
     };
 
     static writable = {
-        create: ['sectionId', 'label', 'href', 'variant', 'external', 'sortOrder'],
-        update: ['sectionId', 'label', 'href', 'variant', 'external', 'sortOrder'],
+        create: ['sectionId', 'label', 'href', 'variant', 'icon', 'external', 'sortOrder'],
+        update: ['sectionId', 'label', 'href', 'variant', 'icon', 'external', 'sortOrder'],
     };
 
     protected static fields: ModelFields = {
@@ -65,6 +66,13 @@ export class HomepageAction extends BaseModel {
             formConfig: { visible: true, fieldType: 'select' },
             tableConfig: { visible: true, colWidth: 120 },
         },
+        icon: {
+            type: 'string',
+            editable: true,
+            uiConfig: { label: 'Icon', description: 'Lucide icon name (e.g. ArrowRight, Github)' },
+            formConfig: { visible: true, fieldType: 'input' },
+            tableConfig: { visible: false },
+        },
         external: {
             type: 'boolean',
             editable: true,
diff --git a/apps/ottabase-template-app-tanstack/ottabase/models/HomepageDisplaySettings.schema.ts b/apps/ottabase-template-app-tanstack/ottabase/models/HomepageDisplaySettings.schema.ts
index 4daef09b4..908953ab7 100644
--- a/apps/ottabase-template-app-tanstack/ottabase/models/HomepageDisplaySettings.schema.ts
+++ b/apps/ottabase-template-app-tanstack/ottabase/models/HomepageDisplaySettings.schema.ts
@@ -9,6 +9,8 @@ import { integer, sqliteTable, text } from 'drizzle-orm/sqlite-core';
  * - Variant selections per slot (JSON matching HomepageConfig)
  * - Active theme preset name
  * - Fallback theme preset ID
+ * - Custom CSS
+ * - SEO metadata
  */
 export const homepageDisplaySettingsTable = sqliteTable('homepage_display_settings', {
     id: text('id')
@@ -23,6 +25,12 @@ export const homepageDisplaySettingsTable = sqliteTable('homepage_display_settin
     themePreset: text('theme_preset').default('default'),
     /** Fallback theme preset ID for SSR */
     fallbackThemePresetId: text('fallback_theme_preset_id'),
+    /** Custom CSS injected into the homepage */
+    customCss: text('custom_css'),
+    /** SEO page title for the homepage */
+    seoTitle: text('seo_title'),
+    /** SEO meta description for the homepage */
+    seoDescription: text('seo_description'),
     /** Multi-app identifier */
     appId: text('app_id'),
     createdAt: integer('created_at')
diff --git a/apps/ottabase-template-app-tanstack/ottabase/models/HomepageDisplaySettings.ts b/apps/ottabase-template-app-tanstack/ottabase/models/HomepageDisplaySettings.ts
index 3c6522449..1a350eae7 100644
--- a/apps/ottabase-template-app-tanstack/ottabase/models/HomepageDisplaySettings.ts
+++ b/apps/ottabase-template-app-tanstack/ottabase/models/HomepageDisplaySettings.ts
@@ -13,7 +13,8 @@ export {
 
 /**
  * Single-row settings model for the homepage display state.
- * Stores variant selections per slot and the active theme preset.
+ * Stores variant selections per slot, the active theme preset,
+ * custom CSS, and SEO metadata.
  */
 export class HomepageDisplaySettings extends BaseModel {
     static entity = 'homepage_display_settings';
@@ -29,8 +30,8 @@ export class HomepageDisplaySettings extends BaseModel {
     };
 
     static writable = {
-        create: ['id', 'variantBySlotJson', 'themePreset', 'fallbackThemePresetId', 'appId'],
-        update: ['variantBySlotJson', 'themePreset', 'fallbackThemePresetId', 'appId'],
+        create: ['id', 'variantBySlotJson', 'themePreset', 'fallbackThemePresetId', 'customCss', 'seoTitle', 'seoDescription', 'appId'],
+        update: ['variantBySlotJson', 'themePreset', 'fallbackThemePresetId', 'customCss', 'seoTitle', 'seoDescription', 'appId'],
     };
 
     protected static defaults = {
@@ -63,6 +64,27 @@ export class HomepageDisplaySettings extends BaseModel {
             formConfig: { visible: true, fieldType: 'input' },
             tableConfig: { visible: false },
         },
+        customCss: {
+            type: 'string',
+            editable: true,
+            uiConfig: { label: 'Custom CSS', description: 'Injected into the homepage <style> tag' },
+            formConfig: { visible: true, fieldType: 'textarea' },
+            tableConfig: { visible: false },
+        },
+        seoTitle: {
+            type: 'string',
+            editable: true,
+            uiConfig: { label: 'SEO Title', description: 'Page title for search engines' },
+            formConfig: { visible: true, fieldType: 'input' },
+            tableConfig: { visible: false },
+        },
+        seoDescription: {
+            type: 'string',
+            editable: true,
+            uiConfig: { label: 'SEO Description', description: 'Meta description for search engines' },
+            formConfig: { visible: true, fieldType: 'textarea' },
+            tableConfig: { visible: false },
+        },
         appId: {
             type: 'string',
             editable: true,
diff --git a/apps/ottabase-template-app-tanstack/ottabase/models/HomepageFeature.schema.ts b/apps/ottabase-template-app-tanstack/ottabase/models/HomepageFeature.schema.ts
index 64a4acf25..df4192e20 100644
--- a/apps/ottabase-template-app-tanstack/ottabase/models/HomepageFeature.schema.ts
+++ b/apps/ottabase-template-app-tanstack/ottabase/models/HomepageFeature.schema.ts
@@ -15,6 +15,12 @@ export const homepageFeaturesTable = sqliteTable('homepage_features', {
         .references(() => homepageSectionsTable.id, { onDelete: 'cascade' }),
     title: text('title').notNull(),
     description: text('description').notNull(),
+    /** Lucide icon name (e.g. 'Zap', 'Shield', 'Globe') */
+    icon: text('icon'),
+    /** Optional image URL for visual features */
+    imageUrl: text('image_url'),
+    /** Optional link destination */
+    href: text('href'),
     /** Display order */
     sortOrder: integer('sort_order').notNull().default(0),
     createdAt: integer('created_at')
diff --git a/apps/ottabase-template-app-tanstack/ottabase/models/HomepageFeature.ts b/apps/ottabase-template-app-tanstack/ottabase/models/HomepageFeature.ts
index 61545a227..395a73146 100644
--- a/apps/ottabase-template-app-tanstack/ottabase/models/HomepageFeature.ts
+++ b/apps/ottabase-template-app-tanstack/ottabase/models/HomepageFeature.ts
@@ -9,6 +9,7 @@ export { homepageFeaturesTable, type HomepageFeatureRow, type NewHomepageFeature
 
 /**
  * A feature item belonging to a homepage section (typically the "features" slot).
+ * Supports icon, image, and optional link for rich feature displays.
  */
 export class HomepageFeature extends BaseModel {
     static entity = 'homepage_features';
@@ -24,8 +25,8 @@ export class HomepageFeature extends BaseModel {
     };
 
     static writable = {
-        create: ['sectionId', 'title', 'description', 'sortOrder'],
-        update: ['sectionId', 'title', 'description', 'sortOrder'],
+        create: ['sectionId', 'title', 'description', 'icon', 'imageUrl', 'href', 'sortOrder'],
+        update: ['sectionId', 'title', 'description', 'icon', 'imageUrl', 'href', 'sortOrder'],
     };
 
     protected static fields: ModelFields = {
@@ -56,6 +57,27 @@ export class HomepageFeature extends BaseModel {
             tableConfig: { visible: true, colWidth: 'auto' },
             validation: { rules: 'required', messages: { required: 'Description is required' } },
         },
+        icon: {
+            type: 'string',
+            editable: true,
+            uiConfig: { label: 'Icon', description: 'Lucide icon name (e.g. Zap, Shield, Globe)' },
+            formConfig: { visible: true, fieldType: 'input' },
+            tableConfig: { visible: false },
+        },
+        imageUrl: {
+            type: 'string',
+            editable: true,
+            uiConfig: { label: 'Image URL', description: 'Optional image for this feature' },
+            formConfig: { visible: true, fieldType: 'input' },
+            tableConfig: { visible: false },
+        },
+        href: {
+            type: 'string',
+            editable: true,
+            uiConfig: { label: 'Link', description: 'Optional destination URL' },
+            formConfig: { visible: true, fieldType: 'input' },
+            tableConfig: { visible: false },
+        },
         sortOrder: {
             type: 'number',
             editable: true,
diff --git a/apps/ottabase-template-app-tanstack/ottabase/models/HomepageSection.schema.ts b/apps/ottabase-template-app-tanstack/ottabase/models/HomepageSection.schema.ts
index f6d8b367e..af0e69f4b 100644
--- a/apps/ottabase-template-app-tanstack/ottabase/models/HomepageSection.schema.ts
+++ b/apps/ottabase-template-app-tanstack/ottabase/models/HomepageSection.schema.ts
@@ -17,6 +17,14 @@ export const homepageSectionsTable = sqliteTable(
         body: text('body'),
         /** Optional GitHub URL (used by navbar/about slots) */
         githubUrl: text('github_url'),
+        /** Lucide icon name for this section (e.g. 'Sparkles', 'Shield') */
+        icon: text('icon'),
+        /** Whether this section is visible on the homepage */
+        enabled: integer('enabled', { mode: 'boolean' }).notNull().default(true),
+        /** Custom Tailwind CSS classes applied to the section wrapper */
+        cssClasses: text('css_classes'),
+        /** Arbitrary JSON metadata for extensibility */
+        metadata: text('metadata', { mode: 'json' }).$type<Record<string, unknown>>(),
         /** Display order for listing */
         sortOrder: integer('sort_order').notNull().default(0),
         /** Multi-app identifier */
diff --git a/apps/ottabase-template-app-tanstack/ottabase/models/HomepageSection.ts b/apps/ottabase-template-app-tanstack/ottabase/models/HomepageSection.ts
index 9e66b7b69..8fa4b6aee 100644
--- a/apps/ottabase-template-app-tanstack/ottabase/models/HomepageSection.ts
+++ b/apps/ottabase-template-app-tanstack/ottabase/models/HomepageSection.ts
@@ -9,7 +9,7 @@ export { homepageSectionsTable, type HomepageSectionRow, type NewHomepageSection
 
 /**
  * A homepage section maps to a SlotRenderer slot (navbar, hero, features, cta, footer, about).
- * Contains the title/subtitle/body for that slot.
+ * Contains the title/subtitle/body for that slot plus display options (icon, enabled, cssClasses, metadata).
  * Features and actions are stored in child tables (HomepageFeature, HomepageAction).
  */
 export class HomepageSection extends BaseModel {
@@ -20,14 +20,20 @@ export class HomepageSection extends BaseModel {
     static packageType: PackageType = 'app';
 
     static casts = {
+        enabled: 'boolean' as const,
+        metadata: 'json' as const,
         sortOrder: 'number' as const,
         createdAt: 'date' as const,
         updatedAt: 'date' as const,
     };
 
     static writable = {
-        create: ['slot', 'title', 'subtitle', 'body', 'githubUrl', 'sortOrder', 'appId'],
-        update: ['slot', 'title', 'subtitle', 'body', 'githubUrl', 'sortOrder', 'appId'],
+        create: ['slot', 'title', 'subtitle', 'body', 'githubUrl', 'icon', 'enabled', 'cssClasses', 'metadata', 'sortOrder', 'appId'],
+        update: ['slot', 'title', 'subtitle', 'body', 'githubUrl', 'icon', 'enabled', 'cssClasses', 'metadata', 'sortOrder', 'appId'],
+    };
+
+    protected static defaults = {
+        enabled: true,
     };
 
     protected static fields: ModelFields = {
@@ -71,6 +77,35 @@ export class HomepageSection extends BaseModel {
             formConfig: { visible: true, fieldType: 'input' },
             tableConfig: { visible: false },
         },
+        icon: {
+            type: 'string',
+            editable: true,
+            uiConfig: { label: 'Icon', description: 'Lucide icon name (e.g. Sparkles, Shield, Zap)' },
+            formConfig: { visible: true, fieldType: 'input' },
+            tableConfig: { visible: false },
+        },
+        enabled: {
+            type: 'boolean',
+            editable: true,
+            filterable: true,
+            uiConfig: { label: 'Enabled', description: 'Show this section on the homepage' },
+            formConfig: { visible: true, fieldType: 'checkbox' },
+            tableConfig: { visible: true, colWidth: 80 },
+        },
+        cssClasses: {
+            type: 'string',
+            editable: true,
+            uiConfig: { label: 'CSS Classes', description: 'Custom Tailwind CSS classes' },
+            formConfig: { visible: true, fieldType: 'input' },
+            tableConfig: { visible: false },
+        },
+        metadata: {
+            type: 'json',
+            editable: true,
+            uiConfig: { label: 'Metadata', description: 'Arbitrary JSON key-value data' },
+            formConfig: { visible: true, fieldType: 'textarea' },
+            tableConfig: { visible: false },
+        },
         sortOrder: {
             type: 'number',
             editable: true,
diff --git a/apps/ottabase-template-app-tanstack/src/hooks/homepageHooks.ts b/apps/ottabase-template-app-tanstack/src/hooks/homepageHooks.ts
index 043a0c5c4..d44d942ae 100644
--- a/apps/ottabase-template-app-tanstack/src/hooks/homepageHooks.ts
+++ b/apps/ottabase-template-app-tanstack/src/hooks/homepageHooks.ts
@@ -15,6 +15,10 @@ export interface HomepageSectionRow {
     subtitle: string | null;
     body: string | null;
     githubUrl: string | null;
+    icon: string | null;
+    enabled: boolean;
+    cssClasses: string | null;
+    metadata: Record<string, unknown> | null;
     sortOrder: number;
     appId: string | null;
     createdAt: string;
@@ -26,6 +30,9 @@ export interface HomepageFeatureRow {
     sectionId: string;
     title: string;
     description: string;
+    icon: string | null;
+    imageUrl: string | null;
+    href: string | null;
     sortOrder: number;
     createdAt: string;
     updatedAt: string;
@@ -37,6 +44,7 @@ export interface HomepageActionRow {
     label: string;
     href: string;
     variant: string | null;
+    icon: string | null;
     external: boolean;
     sortOrder: number;
     createdAt: string;
@@ -48,6 +56,9 @@ export interface HomepageDisplaySettingsRow {
     variantBySlotJson: Record<string, string> | null;
     themePreset: string | null;
     fallbackThemePresetId: string | null;
+    customCss: string | null;
+    seoTitle: string | null;
+    seoDescription: string | null;
     appId: string | null;
     createdAt: string;
     updatedAt: string;
diff --git a/apps/ottabase-template-app-tanstack/src/pages/admin/homepage/AdminHomepageDisplayPage.tsx b/apps/ottabase-template-app-tanstack/src/pages/admin/homepage/AdminHomepageDisplayPage.tsx
index c9ca46f12..37285e9ba 100644
--- a/apps/ottabase-template-app-tanstack/src/pages/admin/homepage/AdminHomepageDisplayPage.tsx
+++ b/apps/ottabase-template-app-tanstack/src/pages/admin/homepage/AdminHomepageDisplayPage.tsx
@@ -1,12 +1,10 @@
 /**
  * Admin Homepage Display Settings
  *
- * Manages the homepage display state:
- * - Variant selection per slot (maps to SLOT_REGISTRY on the Next.js side)
- * - Theme preset
+ * Manages the homepage display state: variant selection per slot,
+ * theme preset, custom CSS, and SEO metadata.
  *
- * Single-row settings model (id = 'default'). Uses upsert semantics via
- * getOrCreateDefault on the API side.
+ * Single-row settings model (id = 'default'). Uses upsert semantics.
  */
 import { ADMIN_LIST_QUERY_CONFIG } from '@/config/queryConfig';
 import { homepageDisplaySettingsHooks, type HomepageDisplaySettingsRow } from '@/hooks/homepageHooks';
@@ -20,11 +18,13 @@ import {
     CardTitle,
     Input,
     Label,
+    Separator,
+    Textarea,
 } from '@ottabase/ui-shadcn';
-import { Check, Monitor, Save } from 'lucide-react';
+import { Check, Code, Globe, Monitor, Palette, RotateCcw, Save, Search } from 'lucide-react';
 import { useCallback, useEffect, useState } from 'react';
 import { HomepageAdminNav } from './HomepageAdminNav';
-import { getDefaultVariantBySlot, SLOT_CONFIG, SLOT_NAMES, type SlotName } from './homepage-constants';
+import { getDefaultVariantBySlot, SLOT_CONFIG, SLOT_NAMES, THEME_PRESETS, type SlotName } from './homepage-constants';
 
 export function AdminHomepageDisplayPage() {
     const { data, isLoading } = homepageDisplaySettingsHooks.useList({}, ADMIN_LIST_QUERY_CONFIG);
@@ -37,6 +37,9 @@ export function AdminHomepageDisplayPage() {
 
     const [variantBySlot, setVariantBySlot] = useState<Record<string, string>>(getDefaultVariantBySlot());
     const [themePreset, setThemePreset] = useState('default');
+    const [customCss, setCustomCss] = useState('');
+    const [seoTitle, setSeoTitle] = useState('');
+    const [seoDescription, setSeoDescription] = useState('');
     const [initialized, setInitialized] = useState(false);
 
     // Populate from DB when data loads
@@ -44,6 +47,9 @@ export function AdminHomepageDisplayPage() {
         if (existing && !initialized) {
             setVariantBySlot({ ...getDefaultVariantBySlot(), ...(existing.variantBySlotJson ?? {}) });
             setThemePreset(existing.themePreset ?? 'default');
+            setCustomCss(existing.customCss ?? '');
+            setSeoTitle(existing.seoTitle ?? '');
+            setSeoDescription(existing.seoDescription ?? '');
             setInitialized(true);
         } else if (!isLoading && !existing && !initialized) {
             // No row yet — use defaults
@@ -55,19 +61,25 @@ export function AdminHomepageDisplayPage() {
         initialized &&
         (JSON.stringify(variantBySlot) !==
             JSON.stringify({ ...getDefaultVariantBySlot(), ...(existing?.variantBySlotJson ?? {}) }) ||
-            themePreset !== (existing?.themePreset ?? 'default'));
+            themePreset !== (existing?.themePreset ?? 'default') ||
+            customCss !== (existing?.customCss ?? '') ||
+            seoTitle !== (existing?.seoTitle ?? '') ||
+            seoDescription !== (existing?.seoDescription ?? ''));
 
     const handleSave = useCallback(async () => {
         const payload = {
             variantBySlotJson: variantBySlot,
             themePreset,
+            customCss: customCss || undefined,
+            seoTitle: seoTitle || undefined,
+            seoDescription: seoDescription || undefined,
         };
         if (existing) {
             await updateSettings.mutateAsync({ id: 'default', data: payload });
         } else {
             await createSettings.mutateAsync({ id: 'default', ...payload });
         }
-    }, [existing, variantBySlot, themePreset, updateSettings, createSettings]);
+    }, [existing, variantBySlot, themePreset, customCss, seoTitle, seoDescription, updateSettings, createSettings]);
 
     const handleVariantChange = (slot: SlotName, variantId: string) => {
         setVariantBySlot((prev) => ({ ...prev, [slot]: variantId }));
@@ -76,6 +88,9 @@ export function AdminHomepageDisplayPage() {
     const handleResetDefaults = () => {
         setVariantBySlot(getDefaultVariantBySlot());
         setThemePreset('default');
+        setCustomCss('');
+        setSeoTitle('');
+        setSeoDescription('');
     };
 
     if (isLoading) {
@@ -100,12 +115,13 @@ export function AdminHomepageDisplayPage() {
                 <div>
                     <h1 className="text-3xl font-bold tracking-tight">Display Settings</h1>
                     <p className="text-muted-foreground mt-1">
-                        Choose which variant to display for each slot, and set the active theme preset.
+                        Configure layout variants, theme, SEO, and custom styling for the homepage.
                     </p>
                 </div>
                 <div className="flex gap-2">
                     <Button variant="outline" onClick={handleResetDefaults}>
-                        Reset Defaults
+                        <RotateCcw className="mr-2 h-4 w-4" />
+                        Reset
                     </Button>
                     <Button
                         onClick={handleSave}
@@ -121,18 +137,44 @@ export function AdminHomepageDisplayPage() {
             <Card>
                 <CardHeader>
                     <CardTitle className="text-base flex items-center gap-2">
-                        <Monitor className="h-4 w-4" />
+                        <Palette className="h-4 w-4" />
                         Theme Preset
                     </CardTitle>
-                    <CardDescription>The theme preset name used for SSR and initial page load.</CardDescription>
+                    <CardDescription>Select the visual theme for the homepage.</CardDescription>
                 </CardHeader>
                 <CardContent>
+                    <div className="grid gap-3 sm:grid-cols-2 md:grid-cols-4">
+                        {THEME_PRESETS.map((preset) => {
+                            const isActive = themePreset === preset.id;
+                            return (
+                                <button
+                                    key={preset.id}
+                                    type="button"
+                                    onClick={() => setThemePreset(preset.id)}
+                                    className={`relative rounded-lg border-2 p-3 text-left transition-all ${
+                                        isActive
+                                            ? 'border-primary bg-primary/5 ring-1 ring-primary/20'
+                                            : 'border-border hover:border-muted-foreground/30 hover:bg-muted/50'
+                                    }`}
+                                >
+                                    {isActive && (
+                                        <div className="absolute top-2 right-2 rounded-full bg-primary p-0.5">
+                                            <Check className="h-3 w-3 text-primary-foreground" />
+                                        </div>
+                                    )}
+                                    <p className="font-medium text-sm">{preset.label}</p>
+                                    <p className="mt-0.5 text-xs text-muted-foreground">{preset.description}</p>
+                                </button>
+                            );
+                        })}
+                    </div>
+                    <Separator className="my-4" />
                     <div className="flex items-center gap-3">
-                        <Label htmlFor="theme-preset" className="shrink-0">
-                            Preset name:
+                        <Label htmlFor="theme-preset-custom" className="shrink-0 text-sm">
+                            Custom preset:
                         </Label>
                         <Input
-                            id="theme-preset"
+                            id="theme-preset-custom"
                             value={themePreset}
                             onChange={(e) => setThemePreset(e.target.value)}
                             placeholder="default"
@@ -143,52 +185,120 @@ export function AdminHomepageDisplayPage() {
             </Card>
 
             {/* Slot Variant Pickers */}
-            {SLOT_NAMES.map((slot) => {
-                const config = SLOT_CONFIG[slot];
-                const selected = variantBySlot[slot] ?? config.default;
-
-                return (
-                    <Card key={slot}>
-                        <CardHeader className="pb-3">
-                            <CardTitle className="text-base">{config.label}</CardTitle>
-                            <CardDescription>
-                                Select which variant to use for the{' '}
-                                <Badge variant="outline" className="font-mono text-xs">
-                                    {slot}
-                                </Badge>{' '}
-                                slot.
-                            </CardDescription>
-                        </CardHeader>
-                        <CardContent>
-                            <div className="grid gap-3 sm:grid-cols-3">
-                                {config.variants.map((v) => {
-                                    const isActive = selected === v.id;
-                                    return (
-                                        <button
-                                            key={v.id}
-                                            type="button"
-                                            onClick={() => handleVariantChange(slot, v.id)}
-                                            className={`relative rounded-lg border-2 p-4 text-left transition-all ${
-                                                isActive
-                                                    ? 'border-primary bg-primary/5 ring-1 ring-primary/20'
-                                                    : 'border-border hover:border-muted-foreground/30 hover:bg-muted/50'
-                                            }`}
-                                        >
-                                            {isActive && (
-                                                <div className="absolute top-2 right-2 rounded-full bg-primary p-0.5">
-                                                    <Check className="h-3 w-3 text-primary-foreground" />
-                                                </div>
-                                            )}
-                                            <p className="font-medium text-sm">{v.label}</p>
-                                            <p className="mt-1 text-xs text-muted-foreground">{v.desc}</p>
-                                        </button>
-                                    );
-                                })}
+            <Card>
+                <CardHeader>
+                    <CardTitle className="text-base flex items-center gap-2">
+                        <Monitor className="h-4 w-4" />
+                        Layout Variants
+                    </CardTitle>
+                    <CardDescription>Choose the display variant for each homepage slot.</CardDescription>
+                </CardHeader>
+                <CardContent className="space-y-6">
+                    {SLOT_NAMES.map((slot) => {
+                        const config = SLOT_CONFIG[slot];
+                        const selected = variantBySlot[slot] ?? config.default;
+
+                        return (
+                            <div key={slot}>
+                                <div className="flex items-center gap-2 mb-3">
+                                    <p className="text-sm font-medium">{config.label}</p>
+                                    <Badge variant="outline" className="font-mono text-[10px]">
+                                        {slot}
+                                    </Badge>
+                                </div>
+                                <div className="grid gap-2 sm:grid-cols-3">
+                                    {config.variants.map((v) => {
+                                        const isActive = selected === v.id;
+                                        return (
+                                            <button
+                                                key={v.id}
+                                                type="button"
+                                                onClick={() => handleVariantChange(slot, v.id)}
+                                                className={`relative rounded-lg border-2 p-3 text-left transition-all ${
+                                                    isActive
+                                                        ? 'border-primary bg-primary/5 ring-1 ring-primary/20'
+                                                        : 'border-border hover:border-muted-foreground/30 hover:bg-muted/50'
+                                                }`}
+                                            >
+                                                {isActive && (
+                                                    <div className="absolute top-2 right-2 rounded-full bg-primary p-0.5">
+                                                        <Check className="h-3 w-3 text-primary-foreground" />
+                                                    </div>
+                                                )}
+                                                <p className="font-medium text-sm">{v.label}</p>
+                                                <p className="mt-0.5 text-xs text-muted-foreground">{v.desc}</p>
+                                            </button>
+                                        );
+                                    })}
+                                </div>
+                                {slot !== SLOT_NAMES[SLOT_NAMES.length - 1] && <Separator className="mt-4" />}
                             </div>
-                        </CardContent>
-                    </Card>
-                );
-            })}
+                        );
+                    })}
+                </CardContent>
+            </Card>
+
+            {/* SEO Settings */}
+            <Card>
+                <CardHeader>
+                    <CardTitle className="text-base flex items-center gap-2">
+                        <Search className="h-4 w-4" />
+                        SEO
+                    </CardTitle>
+                    <CardDescription>Search engine optimization for the homepage.</CardDescription>
+                </CardHeader>
+                <CardContent className="space-y-4">
+                    <div className="space-y-2">
+                        <Label htmlFor="seo-title">Page Title</Label>
+                        <Input
+                            id="seo-title"
+                            value={seoTitle}
+                            onChange={(e) => setSeoTitle(e.target.value)}
+                            placeholder="My Awesome Product — Tagline"
+                            className="max-w-lg"
+                        />
+                        <p className="text-xs text-muted-foreground">
+                            Appears in browser tab and search results. Recommended: 50–60 characters.
+                        </p>
+                    </div>
+                    <div className="space-y-2">
+                        <Label htmlFor="seo-description">Meta Description</Label>
+                        <Textarea
+                            id="seo-description"
+                            value={seoDescription}
+                            onChange={(e) => setSeoDescription(e.target.value)}
+                            placeholder="A brief description of your product or service for search engines."
+                            rows={3}
+                            className="max-w-lg"
+                        />
+                        <p className="text-xs text-muted-foreground">
+                            Shown in search result snippets. Recommended: 150–160 characters.
+                        </p>
+                    </div>
+                </CardContent>
+            </Card>
+
+            {/* Custom CSS */}
+            <Card>
+                <CardHeader>
+                    <CardTitle className="text-base flex items-center gap-2">
+                        <Code className="h-4 w-4" />
+                        Custom CSS
+                    </CardTitle>
+                    <CardDescription>
+                        Inject custom CSS into the homepage. Use with care — overrides may break layout.
+                    </CardDescription>
+                </CardHeader>
+                <CardContent>
+                    <Textarea
+                        value={customCss}
+                        onChange={(e) => setCustomCss(e.target.value)}
+                        placeholder={`.hero-section {\n  background: linear-gradient(135deg, #667eea 0%, #764ba2 100%);\n}`}
+                        rows={8}
+                        className="font-mono text-sm"
+                    />
+                </CardContent>
+            </Card>
         </div>
     );
 }
diff --git a/apps/ottabase-template-app-tanstack/src/pages/admin/homepage/AdminHomepagePagesPage.tsx b/apps/ottabase-template-app-tanstack/src/pages/admin/homepage/AdminHomepagePagesPage.tsx
new file mode 100644
index 000000000..39c4c3e06
--- /dev/null
+++ b/apps/ottabase-template-app-tanstack/src/pages/admin/homepage/AdminHomepagePagesPage.tsx
@@ -0,0 +1,195 @@
+/**
+ * Admin Homepage Pages Management
+ *
+ * Lists CMS pages (contentType = 'page') and manages their expose-to-homepage flag.
+ * Provides direct links to the blog editor for full page editing.
+ */
+import { ADMIN_LIST_QUERY_CONFIG } from '@/config/queryConfig';
+import { createModelHooks } from '@ottabase/ottaorm/client';
+import {
+    Badge,
+    Button,
+    Card,
+    CardContent,
+    CardDescription,
+    CardHeader,
+    CardTitle,
+    Switch,
+} from '@ottabase/ui-shadcn';
+import { Link } from '@tanstack/react-router';
+import { Edit, ExternalLink, Eye, EyeOff, FileText, Globe, Plus } from 'lucide-react';
+import { HomepageAdminNav } from './HomepageAdminNav';
+
+interface BlogPostRow {
+    id: string;
+    title: string;
+    slug: string;
+    excerpt: string | null;
+    contentType: string;
+    status: string;
+    exposeToHomepage: boolean;
+    publishedAt: string | null;
+    updatedAt: string;
+}
+
+const postHooks = createModelHooks<BlogPostRow>({ entityName: 'posts' });
+
+export function AdminHomepagePagesPage() {
+    const { data, isLoading } = postHooks.useList(
+        { where: { contentType: 'page' }, orderBy: 'updatedAt', orderDirection: 'desc' },
+        ADMIN_LIST_QUERY_CONFIG,
+    );
+    const updatePost = postHooks.useUpdate();
+
+    const pages = (Array.isArray(data) ? data : []) as BlogPostRow[];
+    const publishedPages = pages.filter((p) => p.status === 'published');
+    const exposedCount = pages.filter((p) => p.exposeToHomepage).length;
+
+    const handleToggleExpose = async (page: BlogPostRow) => {
+        await updatePost.mutateAsync({
+            id: page.id,
+            data: { exposeToHomepage: !page.exposeToHomepage },
+        });
+    };
+
+    return (
+        <div className="space-y-6">
+            <HomepageAdminNav />
+
+            {/* Header */}
+            <div className="flex flex-col gap-4 sm:flex-row sm:items-center sm:justify-between">
+                <div>
+                    <h1 className="text-3xl font-bold tracking-tight">CMS Pages</h1>
+                    <p className="text-muted-foreground mt-1">
+                        Manage CMS-powered pages and control which appear in the homepage navbar.
+                    </p>
+                </div>
+                <div className="flex items-center gap-3">
+                    <Badge variant="secondary" className="text-xs">
+                        {exposedCount} exposed to navbar
+                    </Badge>
+                    <Button asChild>
+                        <Link to="/admin/blog/new">
+                            <Plus className="mr-1.5 h-4 w-4" />
+                            New Page
+                        </Link>
+                    </Button>
+                </div>
+            </div>
+
+            {/* Loading */}
+            {isLoading && (
+                <Card>
+                    <CardContent className="py-12 text-center">
+                        <p className="text-muted-foreground">Loading pages…</p>
+                    </CardContent>
+                </Card>
+            )}
+
+            {/* Empty state */}
+            {!isLoading && pages.length === 0 && (
+                <Card>
+                    <CardContent className="py-12 text-center">
+                        <FileText className="mx-auto h-12 w-12 text-muted-foreground/50" />
+                        <h3 className="mt-4 text-lg font-semibold">No pages yet</h3>
+                        <p className="mt-2 text-muted-foreground">
+                            Create a page in the Blog Editor with content type &quot;Page&quot; to manage it here.
+                        </p>
+                        <Button variant="outline" className="mt-4" asChild>
+                            <Link to="/admin/blog/new">
+                                <Plus className="mr-1.5 h-4 w-4" />
+                                Create Page
+                            </Link>
+                        </Button>
+                    </CardContent>
+                </Card>
+            )}
+
+            {/* Pages list */}
+            {pages.length > 0 && (
+                <Card>
+                    <CardHeader className="pb-3">
+                        <CardTitle className="text-base">All Pages</CardTitle>
+                        <CardDescription>
+                            Toggle &quot;Expose to Homepage&quot; to add pages to the navbar. Pages must be published to appear.
+                        </CardDescription>
+                    </CardHeader>
+                    <CardContent>
+                        <div className="divide-y">
+                            {pages.map((page) => (
+                                <div key={page.id} className="flex items-center gap-4 py-3">
+                                    <div className="min-w-0 flex-1">
+                                        <div className="flex items-center gap-2">
+                                            <p className="font-medium text-sm truncate">{page.title || '(untitled)'}</p>
+                                            <Badge
+                                                variant={page.status === 'published' ? 'default' : 'secondary'}
+                                                className="text-[10px] shrink-0"
+                                            >
+                                                {page.status}
+                                            </Badge>
+                                        </div>
+                                        <p className="text-xs text-muted-foreground mt-0.5">
+                                            /page/{page.slug}
+                                            {page.excerpt && ` — ${page.excerpt}`}
+                                        </p>
+                                    </div>
+
+                                    {/* Expose toggle */}
+                                    <div className="flex items-center gap-2 shrink-0">
+                                        <Switch
+                                            id={`expose-${page.id}`}
+                                            checked={page.exposeToHomepage}
+                                            onCheckedChange={() => handleToggleExpose(page)}
+                                            disabled={updatePost.isPending}
+                                        />
+                                        <label
+                                            htmlFor={`expose-${page.id}`}
+                                            className="text-xs text-muted-foreground cursor-pointer flex items-center gap-1"
+                                        >
+                                            {page.exposeToHomepage ? (
+                                                <>
+                                                    <Globe className="h-3 w-3 text-primary" />
+                                                    In navbar
+                                                </>
+                                            ) : (
+                                                <>
+                                                    <EyeOff className="h-3 w-3" />
+                                                    Hidden
+                                                </>
+                                            )}
+                                        </label>
+                                    </div>
+
+                                    {/* Edit link */}
+                                    <Button variant="ghost" size="icon" className="h-8 w-8 shrink-0" asChild>
+                                        <Link to="/admin/blog/$postId" params={{ postId: page.id }}>
+                                            <Edit className="h-4 w-4" />
+                                        </Link>
+                                    </Button>
+                                </div>
+                            ))}
+                        </div>
+                    </CardContent>
+                </Card>
+            )}
+
+            {/* Info card */}
+            <Card>
+                <CardContent className="py-4">
+                    <div className="flex items-start gap-3">
+                        <Globe className="h-5 w-5 text-primary shrink-0 mt-0.5" />
+                        <div className="text-sm text-muted-foreground">
+                            <p className="font-medium text-foreground">How pages work</p>
+                            <p className="mt-1">
+                                Pages are CMS content with type &quot;Page&quot; created in the Blog Editor.
+                                When exposed to the homepage, they appear as links in the navigation bar.
+                                Each page renders at <code className="text-xs bg-muted px-1 py-0.5 rounded">/page/slug</code> on
+                                the Next.js homepage.
+                            </p>
+                        </div>
+                    </div>
+                </CardContent>
+            </Card>
+        </div>
+    );
+}
diff --git a/apps/ottabase-template-app-tanstack/src/pages/admin/homepage/AdminHomepageSectionEditorPage.tsx b/apps/ottabase-template-app-tanstack/src/pages/admin/homepage/AdminHomepageSectionEditorPage.tsx
index a4389fbc7..c8815730f 100644
--- a/apps/ottabase-template-app-tanstack/src/pages/admin/homepage/AdminHomepageSectionEditorPage.tsx
+++ b/apps/ottabase-template-app-tanstack/src/pages/admin/homepage/AdminHomepageSectionEditorPage.tsx
@@ -1,10 +1,9 @@
 /**
  * Admin Homepage Section Editor
  *
- * Full CRUD editor for a single homepage section. Includes inline editing of
- * child features and actions. Auto-saves on blur or button click.
- *
- * Pattern: follows AdminChangelogEditorPage (single-entity form with nested items).
+ * Full CRUD editor for a single homepage section with all configurable fields.
+ * Includes inline editing of child features and actions with icon, imageUrl, href support.
+ * Auto-saves on blur or button click.
  */
 import { ADMIN_LIST_QUERY_CONFIG } from '@/config/queryConfig';
 import {
@@ -32,57 +31,166 @@ import {
     CardTitle,
     Input,
     Label,
+    Separator,
     Switch,
     Textarea,
+    Tooltip,
+    TooltipContent,
+    TooltipProvider,
+    TooltipTrigger,
 } from '@ottabase/ui-shadcn';
 import { useNavigate, useParams } from '@tanstack/react-router';
-import { ArrowLeft, ExternalLink, GripVertical, Plus, Save, Trash2 } from 'lucide-react';
+import {
+    ArrowDown,
+    ArrowLeft,
+    ArrowUp,
+    ExternalLink,
+    GripVertical,
+    Image,
+    Link2,
+    Plus,
+    Save,
+    Trash2,
+} from 'lucide-react';
 import { useCallback, useEffect, useRef, useState } from 'react';
 import { HomepageAdminNav } from './HomepageAdminNav';
-import { ACTION_VARIANTS, SLOT_LABELS } from './homepage-constants';
+import { ACTION_VARIANTS, ICON_SUGGESTIONS, SLOT_LABELS } from './homepage-constants';
 
 // ── Feature row editor ──────────────────────────────────────────────────────
 
-function FeatureEditor({ feature, onDelete }: { feature: HomepageFeatureRow; onDelete: (id: string) => void }) {
+function FeatureEditor({
+    feature,
+    onDelete,
+    onMove,
+    isFirst,
+    isLast,
+}: {
+    feature: HomepageFeatureRow;
+    onDelete: (id: string) => void;
+    onMove: (id: string, direction: 'up' | 'down') => void;
+    isFirst: boolean;
+    isLast: boolean;
+}) {
     const updateFeature = homepageFeatureHooks.useUpdate();
     const [title, setTitle] = useState(feature.title);
     const [description, setDescription] = useState(feature.description);
-    const dirty = title !== feature.title || description !== feature.description;
+    const [icon, setIcon] = useState(feature.icon ?? '');
+    const [imageUrl, setImageUrl] = useState(feature.imageUrl ?? '');
+    const [href, setHref] = useState(feature.href ?? '');
+
+    const dirty =
+        title !== feature.title ||
+        description !== feature.description ||
+        icon !== (feature.icon ?? '') ||
+        imageUrl !== (feature.imageUrl ?? '') ||
+        href !== (feature.href ?? '');
 
     const handleSave = useCallback(() => {
         if (!dirty) return;
-        updateFeature.mutate({ id: feature.id, data: { title, description } });
-    }, [dirty, feature.id, title, description, updateFeature]);
+        updateFeature.mutate({
+            id: feature.id,
+            data: {
+                title,
+                description,
+                icon: icon || undefined,
+                imageUrl: imageUrl || undefined,
+                href: href || undefined,
+            },
+        });
+    }, [dirty, feature.id, title, description, icon, imageUrl, href, updateFeature]);
 
     return (
-        <div className="flex items-start gap-2 rounded-lg border p-3">
-            <GripVertical className="mt-2 h-4 w-4 shrink-0 text-muted-foreground/40 cursor-grab" />
-            <div className="flex-1 space-y-2">
-                <Input
-                    value={title}
-                    onChange={(e) => setTitle(e.target.value)}
-                    onBlur={handleSave}
-                    placeholder="Feature title"
-                    className="h-8 text-sm font-medium"
-                />
-                <Textarea
-                    value={description}
-                    onChange={(e) => setDescription(e.target.value)}
-                    onBlur={handleSave}
-                    placeholder="Short description"
-                    rows={2}
-                    className="text-sm"
-                />
-            </div>
-            <div className="flex flex-col items-center gap-1">
-                {dirty && (
-                    <Button variant="ghost" size="icon" className="h-7 w-7" onClick={handleSave}>
-                        <Save className="h-3.5 w-3.5 text-primary" />
+        <div className="rounded-lg border p-3 space-y-3">
+            <div className="flex items-start gap-2">
+                <GripVertical className="mt-2 h-4 w-4 shrink-0 text-muted-foreground/40 cursor-grab" />
+                <div className="flex-1 space-y-2">
+                    <div className="flex gap-2">
+                        <Input
+                            value={title}
+                            onChange={(e) => setTitle(e.target.value)}
+                            onBlur={handleSave}
+                            placeholder="Feature title"
+                            className="h-8 text-sm font-medium"
+                        />
+                        <Input
+                            value={icon}
+                            onChange={(e) => setIcon(e.target.value)}
+                            onBlur={handleSave}
+                            placeholder="Icon (e.g. Zap)"
+                            className="h-8 text-sm w-32"
+                        />
+                    </div>
+                    <Textarea
+                        value={description}
+                        onChange={(e) => setDescription(e.target.value)}
+                        onBlur={handleSave}
+                        placeholder="Short description"
+                        rows={2}
+                        className="text-sm"
+                    />
+                    <div className="flex gap-2">
+                        <div className="flex-1 flex items-center gap-1.5">
+                            <Image className="h-3.5 w-3.5 text-muted-foreground shrink-0" />
+                            <Input
+                                value={imageUrl}
+                                onChange={(e) => setImageUrl(e.target.value)}
+                                onBlur={handleSave}
+                                placeholder="Image URL (optional)"
+                                className="h-7 text-xs"
+                            />
+                        </div>
+                        <div className="flex-1 flex items-center gap-1.5">
+                            <Link2 className="h-3.5 w-3.5 text-muted-foreground shrink-0" />
+                            <Input
+                                value={href}
+                                onChange={(e) => setHref(e.target.value)}
+                                onBlur={handleSave}
+                                placeholder="Link URL (optional)"
+                                className="h-7 text-xs"
+                            />
+                        </div>
+                    </div>
+                </div>
+                <div className="flex flex-col items-center gap-0.5">
+                    <TooltipProvider>
+                        <Tooltip>
+                            <TooltipTrigger asChild>
+                                <Button
+                                    variant="ghost"
+                                    size="icon"
+                                    className="h-6 w-6"
+                                    onClick={() => onMove(feature.id, 'up')}
+                                    disabled={isFirst}
+                                >
+                                    <ArrowUp className="h-3 w-3" />
+                                </Button>
+                            </TooltipTrigger>
+                            <TooltipContent>Move up</TooltipContent>
+                        </Tooltip>
+                        <Tooltip>
+                            <TooltipTrigger asChild>
+                                <Button
+                                    variant="ghost"
+                                    size="icon"
+                                    className="h-6 w-6"
+                                    onClick={() => onMove(feature.id, 'down')}
+                                    disabled={isLast}
+                                >
+                                    <ArrowDown className="h-3 w-3" />
+                                </Button>
+                            </TooltipTrigger>
+                            <TooltipContent>Move down</TooltipContent>
+                        </Tooltip>
+                    </TooltipProvider>
+                    {dirty && (
+                        <Button variant="ghost" size="icon" className="h-6 w-6" onClick={handleSave}>
+                            <Save className="h-3.5 w-3.5 text-primary" />
+                        </Button>
+                    )}
+                    <Button variant="ghost" size="icon" className="h-6 w-6" onClick={() => onDelete(feature.id)}>
+                        <Trash2 className="h-3.5 w-3.5 text-destructive" />
                     </Button>
-                )}
-                <Button variant="ghost" size="icon" className="h-7 w-7" onClick={() => onDelete(feature.id)}>
-                    <Trash2 className="h-3.5 w-3.5 text-destructive" />
-                </Button>
+                </div>
             </div>
         </div>
     );
@@ -90,11 +198,24 @@ function FeatureEditor({ feature, onDelete }: { feature: HomepageFeatureRow; onD
 
 // ── Action row editor ───────────────────────────────────────────────────────
 
-function ActionEditor({ action, onDelete }: { action: HomepageActionRow; onDelete: (id: string) => void }) {
+function ActionEditor({
+    action,
+    onDelete,
+    onMove,
+    isFirst,
+    isLast,
+}: {
+    action: HomepageActionRow;
+    onDelete: (id: string) => void;
+    onMove: (id: string, direction: 'up' | 'down') => void;
+    isFirst: boolean;
+    isLast: boolean;
+}) {
     const updateAction = homepageActionHooks.useUpdate();
     const [label, setLabel] = useState(action.label);
     const [href, setHref] = useState(action.href);
     const [variant, setVariant] = useState(action.variant ?? 'default');
+    const [icon, setIcon] = useState(action.icon ?? '');
     const [external, setExternal] = useState(action.external);
 
     // Track previous values for useEffect-based auto-save
@@ -105,90 +226,133 @@ function ActionEditor({ action, onDelete }: { action: HomepageActionRow; onDelet
         label !== action.label ||
         href !== action.href ||
         variant !== (action.variant ?? 'default') ||
+        icon !== (action.icon ?? '') ||
         external !== action.external;
 
     const handleSave = useCallback(() => {
         if (!dirty) return;
         updateAction.mutate({
             id: action.id,
-            data: { label, href, variant, external },
+            data: { label, href, variant, icon: icon || undefined, external },
         });
-    }, [dirty, action.id, label, href, variant, external, updateAction]);
+    }, [dirty, action.id, label, href, variant, icon, external, updateAction]);
 
-    // Auto-save when variant or external toggle changes (replaces setTimeout)
+    // Auto-save when variant or external toggle changes
     useEffect(() => {
         if (variant !== prevVariantRef.current || external !== prevExternalRef.current) {
             prevVariantRef.current = variant;
             prevExternalRef.current = external;
-            // Compute dirty inline since the callback may have stale closure
             const isDirty =
                 label !== action.label ||
                 href !== action.href ||
                 variant !== (action.variant ?? 'default') ||
+                icon !== (action.icon ?? '') ||
                 external !== action.external;
             if (isDirty) {
                 updateAction.mutate({
                     id: action.id,
-                    data: { label, href, variant, external },
+                    data: { label, href, variant, icon: icon || undefined, external },
                 });
             }
         }
     }, [variant, external]); // eslint-disable-line react-hooks/exhaustive-deps
 
     return (
-        <div className="flex items-start gap-2 rounded-lg border p-3">
-            <GripVertical className="mt-2 h-4 w-4 shrink-0 text-muted-foreground/40 cursor-grab" />
-            <div className="flex-1 space-y-2">
-                <div className="flex gap-2">
-                    <Input
-                        value={label}
-                        onChange={(e) => setLabel(e.target.value)}
-                        onBlur={handleSave}
-                        placeholder="Button label"
-                        className="h-8 text-sm font-medium"
-                    />
-                    <Input
-                        value={href}
-                        onChange={(e) => setHref(e.target.value)}
-                        onBlur={handleSave}
-                        placeholder="/about or https://..."
-                        className="h-8 text-sm"
-                    />
-                </div>
-                <div className="flex items-center gap-4">
-                    <div className="flex items-center gap-2">
-                        <Label className="text-xs">Style:</Label>
-                        <select
-                            value={variant}
-                            onChange={(e) => setVariant(e.target.value)}
-                            className="h-7 rounded-md border border-input bg-background px-2 text-xs"
-                            aria-label="Button style variant"
-                        >
-                            {ACTION_VARIANTS.map((v) => (
-                                <option key={v.value} value={v.value}>
-                                    {v.label}
-                                </option>
-                            ))}
-                        </select>
+        <div className="rounded-lg border p-3 space-y-2">
+            <div className="flex items-start gap-2">
+                <GripVertical className="mt-2 h-4 w-4 shrink-0 text-muted-foreground/40 cursor-grab" />
+                <div className="flex-1 space-y-2">
+                    <div className="flex gap-2">
+                        <Input
+                            value={label}
+                            onChange={(e) => setLabel(e.target.value)}
+                            onBlur={handleSave}
+                            placeholder="Button label"
+                            className="h-8 text-sm font-medium"
+                        />
+                        <Input
+                            value={href}
+                            onChange={(e) => setHref(e.target.value)}
+                            onBlur={handleSave}
+                            placeholder="/about or https://..."
+                            className="h-8 text-sm"
+                        />
                     </div>
-                    <div className="flex items-center gap-2">
-                        <Switch id={`external-${action.id}`} checked={external} onCheckedChange={setExternal} />
-                        <Label htmlFor={`external-${action.id}`} className="text-xs">
-                            External
-                        </Label>
-                        {external && <ExternalLink className="h-3 w-3 text-muted-foreground" />}
+                    <div className="flex items-center gap-4 flex-wrap">
+                        <div className="flex items-center gap-2">
+                            <Label className="text-xs">Style:</Label>
+                            <select
+                                value={variant}
+                                onChange={(e) => setVariant(e.target.value)}
+                                className="h-7 rounded-md border border-input bg-background px-2 text-xs"
+                                aria-label="Button style variant"
+                            >
+                                {ACTION_VARIANTS.map((v) => (
+                                    <option key={v.value} value={v.value}>
+                                        {v.label}
+                                    </option>
+                                ))}
+                            </select>
+                        </div>
+                        <div className="flex items-center gap-2">
+                            <Label className="text-xs">Icon:</Label>
+                            <Input
+                                value={icon}
+                                onChange={(e) => setIcon(e.target.value)}
+                                onBlur={handleSave}
+                                placeholder="ArrowRight"
+                                className="h-7 text-xs w-28"
+                            />
+                        </div>
+                        <div className="flex items-center gap-2">
+                            <Switch id={`external-${action.id}`} checked={external} onCheckedChange={setExternal} />
+                            <Label htmlFor={`external-${action.id}`} className="text-xs">
+                                External
+                            </Label>
+                            {external && <ExternalLink className="h-3 w-3 text-muted-foreground" />}
+                        </div>
                     </div>
                 </div>
-            </div>
-            <div className="flex flex-col items-center gap-1">
-                {dirty && (
-                    <Button variant="ghost" size="icon" className="h-7 w-7" onClick={handleSave}>
-                        <Save className="h-3.5 w-3.5 text-primary" />
+                <div className="flex flex-col items-center gap-0.5">
+                    <TooltipProvider>
+                        <Tooltip>
+                            <TooltipTrigger asChild>
+                                <Button
+                                    variant="ghost"
+                                    size="icon"
+                                    className="h-6 w-6"
+                                    onClick={() => onMove(action.id, 'up')}
+                                    disabled={isFirst}
+                                >
+                                    <ArrowUp className="h-3 w-3" />
+                                </Button>
+                            </TooltipTrigger>
+                            <TooltipContent>Move up</TooltipContent>
+                        </Tooltip>
+                        <Tooltip>
+                            <TooltipTrigger asChild>
+                                <Button
+                                    variant="ghost"
+                                    size="icon"
+                                    className="h-6 w-6"
+                                    onClick={() => onMove(action.id, 'down')}
+                                    disabled={isLast}
+                                >
+                                    <ArrowDown className="h-3 w-3" />
+                                </Button>
+                            </TooltipTrigger>
+                            <TooltipContent>Move down</TooltipContent>
+                        </Tooltip>
+                    </TooltipProvider>
+                    {dirty && (
+                        <Button variant="ghost" size="icon" className="h-6 w-6" onClick={handleSave}>
+                            <Save className="h-3.5 w-3.5 text-primary" />
+                        </Button>
+                    )}
+                    <Button variant="ghost" size="icon" className="h-6 w-6" onClick={() => onDelete(action.id)}>
+                        <Trash2 className="h-3.5 w-3.5 text-destructive" />
                     </Button>
-                )}
-                <Button variant="ghost" size="icon" className="h-7 w-7" onClick={() => onDelete(action.id)}>
-                    <Trash2 className="h-3.5 w-3.5 text-destructive" />
-                </Button>
+                </div>
             </div>
         </div>
     );
@@ -218,8 +382,10 @@ export function AdminHomepageSectionEditorPage() {
 
     const createFeature = homepageFeatureHooks.useCreate();
     const deleteFeature = homepageFeatureHooks.useDelete();
+    const updateFeature = homepageFeatureHooks.useUpdate();
     const createAction = homepageActionHooks.useCreate();
     const deleteAction = homepageActionHooks.useDelete();
+    const updateAction = homepageActionHooks.useUpdate();
 
     const features = (Array.isArray(featuresData) ? featuresData : []) as HomepageFeatureRow[];
     const actions = (Array.isArray(actionsData) ? actionsData : []) as HomepageActionRow[];
@@ -230,6 +396,10 @@ export function AdminHomepageSectionEditorPage() {
     const [subtitle, setSubtitle] = useState('');
     const [body, setBody] = useState('');
     const [githubUrl, setGithubUrl] = useState('');
+    const [icon, setIcon] = useState('');
+    const [enabled, setEnabled] = useState(true);
+    const [cssClasses, setCssClasses] = useState('');
+    const [metadataStr, setMetadataStr] = useState('');
     const [initialized, setInitialized] = useState(false);
 
     // Populate form when section data loads
@@ -239,10 +409,26 @@ export function AdminHomepageSectionEditorPage() {
             setSubtitle((section.subtitle as string) ?? '');
             setBody((section.body as string) ?? '');
             setGithubUrl((section.githubUrl as string) ?? '');
+            setIcon((section.icon as string) ?? '');
+            setEnabled((section.enabled as boolean) ?? true);
+            setCssClasses((section.cssClasses as string) ?? '');
+            const meta = section.metadata as Record<string, unknown> | null;
+            setMetadataStr(meta ? JSON.stringify(meta, null, 2) : '');
             setInitialized(true);
         }
     }, [section, initialized]);
 
+    // Track previous enabled value for auto-save
+    const prevEnabledRef = useRef(enabled);
+    useEffect(() => {
+        if (initialized && enabled !== prevEnabledRef.current) {
+            prevEnabledRef.current = enabled;
+            if (sectionId) {
+                updateSection.mutate({ id: sectionId, data: { enabled } });
+            }
+        }
+    }, [enabled]); // eslint-disable-line react-hooks/exhaustive-deps
+
     const [deleteDialog, setDeleteDialog] = useState<{ type: 'feature' | 'action'; id: string } | null>(null);
 
     const slot = (section?.slot as string) ?? '';
@@ -251,12 +437,34 @@ export function AdminHomepageSectionEditorPage() {
         (title !== ((section?.title as string) ?? '') ||
             subtitle !== ((section?.subtitle as string) ?? '') ||
             body !== ((section?.body as string) ?? '') ||
-            githubUrl !== ((section?.githubUrl as string) ?? ''));
+            githubUrl !== ((section?.githubUrl as string) ?? '') ||
+            icon !== ((section?.icon as string) ?? '') ||
+            cssClasses !== ((section?.cssClasses as string) ?? '') ||
+            metadataStr !== (section?.metadata ? JSON.stringify(section.metadata as Record<string, unknown>, null, 2) : ''));
 
     const handleSaveSection = useCallback(async () => {
         if (!sectionId || !dirty) return;
-        await updateSection.mutateAsync({ id: sectionId, data: { title, subtitle, body, githubUrl } });
-    }, [sectionId, dirty, title, subtitle, body, githubUrl, updateSection]);
+        let metadata: Record<string, unknown> | undefined;
+        if (metadataStr.trim()) {
+            try {
+                metadata = JSON.parse(metadataStr);
+            } catch {
+                // Invalid JSON — skip metadata update
+            }
+        }
+        await updateSection.mutateAsync({
+            id: sectionId,
+            data: {
+                title,
+                subtitle,
+                body,
+                githubUrl,
+                icon: icon || undefined,
+                cssClasses: cssClasses || undefined,
+                ...(metadata !== undefined ? { metadata } : {}),
+            },
+        });
+    }, [sectionId, dirty, title, subtitle, body, githubUrl, icon, cssClasses, metadataStr, updateSection]);
 
     const handleAddFeature = useCallback(async () => {
         if (!sectionId) return;
@@ -280,6 +488,32 @@ export function AdminHomepageSectionEditorPage() {
         });
     }, [sectionId, createAction, actions.length]);
 
+    const handleMoveFeature = useCallback(
+        async (id: string, direction: 'up' | 'down') => {
+            const idx = features.findIndex((f) => f.id === id);
+            const swapIdx = direction === 'up' ? idx - 1 : idx + 1;
+            if (swapIdx < 0 || swapIdx >= features.length) return;
+            const other = features[swapIdx];
+            const current = features[idx];
+            await updateFeature.mutateAsync({ id: current.id, data: { sortOrder: other.sortOrder } });
+            await updateFeature.mutateAsync({ id: other.id, data: { sortOrder: current.sortOrder } });
+        },
+        [features, updateFeature],
+    );
+
+    const handleMoveAction = useCallback(
+        async (id: string, direction: 'up' | 'down') => {
+            const idx = actions.findIndex((a) => a.id === id);
+            const swapIdx = direction === 'up' ? idx - 1 : idx + 1;
+            if (swapIdx < 0 || swapIdx >= actions.length) return;
+            const other = actions[swapIdx];
+            const current = actions[idx];
+            await updateAction.mutateAsync({ id: current.id, data: { sortOrder: other.sortOrder } });
+            await updateAction.mutateAsync({ id: other.id, data: { sortOrder: current.sortOrder } });
+        },
+        [actions, updateAction],
+    );
+
     const handleConfirmDelete = async () => {
         if (!deleteDialog) return;
         if (deleteDialog.type === 'feature') {
@@ -333,42 +567,57 @@ export function AdminHomepageSectionEditorPage() {
                         <Badge variant="outline" className="font-mono text-xs">
                             {slot}
                         </Badge>
+                        {icon && (
+                            <Badge variant="secondary" className="text-xs font-mono">
+                                {icon}
+                            </Badge>
+                        )}
                         <h1 className="text-2xl font-bold tracking-tight">{SLOT_LABELS[slot] ?? slot}</h1>
                     </div>
                     <p className="text-muted-foreground text-sm mt-0.5">
-                        Edit section content, features, and action buttons.
+                        Edit section content, features, actions, and display options.
                     </p>
                 </div>
-                <Button onClick={handleSaveSection} disabled={!dirty || updateSection.isPending}>
-                    <Save className="mr-2 h-4 w-4" />
-                    {updateSection.isPending ? 'Saving…' : 'Save'}
-                </Button>
+                <div className="flex items-center gap-3">
+                    <div className="flex items-center gap-2">
+                        <Switch id="section-enabled" checked={enabled} onCheckedChange={setEnabled} />
+                        <Label htmlFor="section-enabled" className="text-sm">
+                            {enabled ? 'Visible' : 'Hidden'}
+                        </Label>
+                    </div>
+                    <Button onClick={handleSaveSection} disabled={!dirty || updateSection.isPending}>
+                        <Save className="mr-2 h-4 w-4" />
+                        {updateSection.isPending ? 'Saving…' : 'Save'}
+                    </Button>
+                </div>
             </div>
 
-            {/* Section fields */}
+            {/* Section Content */}
             <Card>
                 <CardHeader>
-                    <CardTitle className="text-base">Section Content</CardTitle>
+                    <CardTitle className="text-base">Content</CardTitle>
                     <CardDescription>Title, subtitle, and body text for this slot.</CardDescription>
                 </CardHeader>
                 <CardContent className="space-y-4">
-                    <div className="space-y-2">
-                        <Label htmlFor="section-title">Title</Label>
-                        <Input
-                            id="section-title"
-                            value={title}
-                            onChange={(e) => setTitle(e.target.value)}
-                            placeholder="Section heading"
-                        />
-                    </div>
-                    <div className="space-y-2">
-                        <Label htmlFor="section-subtitle">Subtitle</Label>
-                        <Input
-                            id="section-subtitle"
-                            value={subtitle}
-                            onChange={(e) => setSubtitle(e.target.value)}
-                            placeholder="Optional subtitle or tagline"
-                        />
+                    <div className="grid gap-4 md:grid-cols-2">
+                        <div className="space-y-2">
+                            <Label htmlFor="section-title">Title</Label>
+                            <Input
+                                id="section-title"
+                                value={title}
+                                onChange={(e) => setTitle(e.target.value)}
+                                placeholder="Section heading"
+                            />
+                        </div>
+                        <div className="space-y-2">
+                            <Label htmlFor="section-subtitle">Subtitle</Label>
+                            <Input
+                                id="section-subtitle"
+                                value={subtitle}
+                                onChange={(e) => setSubtitle(e.target.value)}
+                                placeholder="Optional subtitle or tagline"
+                            />
+                        </div>
                     </div>
                     <div className="space-y-2">
                         <Label htmlFor="section-body">Body</Label>
@@ -380,15 +629,62 @@ export function AdminHomepageSectionEditorPage() {
                             rows={4}
                         />
                     </div>
+                </CardContent>
+            </Card>
+
+            {/* Display Options */}
+            <Card>
+                <CardHeader>
+                    <CardTitle className="text-base">Display Options</CardTitle>
+                    <CardDescription>Icon, GitHub URL, CSS classes, and metadata.</CardDescription>
+                </CardHeader>
+                <CardContent className="space-y-4">
+                    <div className="grid gap-4 md:grid-cols-2">
+                        <div className="space-y-2">
+                            <Label htmlFor="section-icon">Icon</Label>
+                            <Input
+                                id="section-icon"
+                                value={icon}
+                                onChange={(e) => setIcon(e.target.value)}
+                                placeholder="Lucide icon name (e.g. Sparkles)"
+                            />
+                            <p className="text-xs text-muted-foreground">
+                                Suggestions: {ICON_SUGGESTIONS.slice(0, 8).join(', ')}
+                            </p>
+                        </div>
+                        <div className="space-y-2">
+                            <Label htmlFor="section-github">GitHub URL</Label>
+                            <Input
+                                id="section-github"
+                                value={githubUrl}
+                                onChange={(e) => setGithubUrl(e.target.value)}
+                                placeholder="https://github.com/..."
+                            />
+                        </div>
+                    </div>
                     <div className="space-y-2">
-                        <Label htmlFor="section-github">GitHub URL</Label>
+                        <Label htmlFor="section-css">CSS Classes</Label>
                         <Input
-                            id="section-github"
-                            value={githubUrl}
-                            onChange={(e) => setGithubUrl(e.target.value)}
-                            placeholder="https://github.com/..."
+                            id="section-css"
+                            value={cssClasses}
+                            onChange={(e) => setCssClasses(e.target.value)}
+                            placeholder="Custom Tailwind classes (e.g. bg-gradient-to-r from-blue-500)"
                         />
                     </div>
+                    <div className="space-y-2">
+                        <Label htmlFor="section-metadata">Metadata (JSON)</Label>
+                        <Textarea
+                            id="section-metadata"
+                            value={metadataStr}
+                            onChange={(e) => setMetadataStr(e.target.value)}
+                            placeholder='{"key": "value"}'
+                            rows={3}
+                            className="font-mono text-sm"
+                        />
+                        <p className="text-xs text-muted-foreground">
+                            Arbitrary key-value data passed through to the frontend for custom rendering.
+                        </p>
+                    </div>
                 </CardContent>
             </Card>
 
@@ -397,8 +693,10 @@ export function AdminHomepageSectionEditorPage() {
                 <CardHeader className="pb-3">
                     <div className="flex items-center justify-between">
                         <div>
-                            <CardTitle className="text-base">Features</CardTitle>
-                            <CardDescription>Feature items displayed in this section.</CardDescription>
+                            <CardTitle className="text-base">Features ({features.length})</CardTitle>
+                            <CardDescription>
+                                Feature items with icon, image, and link support.
+                            </CardDescription>
                         </div>
                         <Button
                             variant="outline"
@@ -418,11 +716,14 @@ export function AdminHomepageSectionEditorPage() {
                         </p>
                     ) : (
                         <div className="space-y-2">
-                            {features.map((f) => (
+                            {features.map((f, idx) => (
                                 <FeatureEditor
                                     key={f.id}
                                     feature={f}
                                     onDelete={(id) => setDeleteDialog({ type: 'feature', id })}
+                                    onMove={handleMoveFeature}
+                                    isFirst={idx === 0}
+                                    isLast={idx === features.length - 1}
                                 />
                             ))}
                         </div>
@@ -435,8 +736,10 @@ export function AdminHomepageSectionEditorPage() {
                 <CardHeader className="pb-3">
                     <div className="flex items-center justify-between">
                         <div>
-                            <CardTitle className="text-base">Action Buttons</CardTitle>
-                            <CardDescription>Call-to-action buttons for this section.</CardDescription>
+                            <CardTitle className="text-base">Action Buttons ({actions.length})</CardTitle>
+                            <CardDescription>
+                                Call-to-action buttons with icon, style variant, and external link support.
+                            </CardDescription>
                         </div>
                         <Button variant="outline" size="sm" onClick={handleAddAction} disabled={createAction.isPending}>
                             <Plus className="mr-1.5 h-3.5 w-3.5" />
@@ -447,15 +750,18 @@ export function AdminHomepageSectionEditorPage() {
                 <CardContent>
                     {actions.length === 0 ? (
                         <p className="text-sm text-muted-foreground py-4 text-center">
-                            No actions yet. Add buttons like "Get Started" or "Learn More".
+                            No actions yet. Add buttons like &quot;Get Started&quot; or &quot;Learn More&quot;.
                         </p>
                     ) : (
                         <div className="space-y-2">
-                            {actions.map((a) => (
+                            {actions.map((a, idx) => (
                                 <ActionEditor
                                     key={a.id}
                                     action={a}
                                     onDelete={(id) => setDeleteDialog({ type: 'action', id })}
+                                    onMove={handleMoveAction}
+                                    isFirst={idx === 0}
+                                    isLast={idx === actions.length - 1}
                                 />
                             ))}
                         </div>
diff --git a/apps/ottabase-template-app-tanstack/src/pages/admin/homepage/AdminHomepageSectionsPage.tsx b/apps/ottabase-template-app-tanstack/src/pages/admin/homepage/AdminHomepageSectionsPage.tsx
index 5706f60cf..3801ecc5d 100644
--- a/apps/ottabase-template-app-tanstack/src/pages/admin/homepage/AdminHomepageSectionsPage.tsx
+++ b/apps/ottabase-template-app-tanstack/src/pages/admin/homepage/AdminHomepageSectionsPage.tsx
@@ -1,8 +1,8 @@
 /**
  * Admin Homepage Sections List
  *
- * Lists all homepage sections (one per slot) with CRUD operations.
- * Pattern: follows AdminBlogListPage.tsx / AdminChangelogListPage.tsx.
+ * Visual slot-based overview of all homepage sections with inline CRUD,
+ * enable/disable toggles, sort controls, and nested feature/action editors.
  */
 import { ADMIN_LIST_QUERY_CONFIG } from '@/config/queryConfig';
 import {
@@ -29,15 +29,35 @@ import {
     CardDescription,
     CardHeader,
     CardTitle,
+    Collapsible,
+    CollapsibleContent,
+    CollapsibleTrigger,
     Input,
     Label,
+    Switch,
     Textarea,
+    Tooltip,
+    TooltipContent,
+    TooltipProvider,
+    TooltipTrigger,
 } from '@ottabase/ui-shadcn';
 import { Link } from '@tanstack/react-router';
-import { Edit, ExternalLink, GripVertical, Layout, Plus, Trash2 } from 'lucide-react';
+import {
+    ArrowDown,
+    ArrowUp,
+    ChevronDown,
+    Edit,
+    ExternalLink,
+    Eye,
+    EyeOff,
+    GripVertical,
+    Layout,
+    Plus,
+    Trash2,
+} from 'lucide-react';
 import { useCallback, useState } from 'react';
 import { HomepageAdminNav } from './HomepageAdminNav';
-import { ACTION_VARIANTS, SLOT_LABELS, SLOT_NAMES } from './homepage-constants';
+import { ACTION_VARIANTS, SLOT_DESCRIPTIONS, SLOT_LABELS, SLOT_NAMES, type SlotName } from './homepage-constants';
 
 // ── Inline mini-editors ─────────────────────────────────────────────────────
 
@@ -52,6 +72,7 @@ function SectionFeatures({ sectionId }: { sectionId: string }) {
     const [adding, setAdding] = useState(false);
     const [newTitle, setNewTitle] = useState('');
     const [newDesc, setNewDesc] = useState('');
+    const [newIcon, setNewIcon] = useState('');
 
     const features = (Array.isArray(data) ? data : []) as HomepageFeatureRow[];
 
@@ -61,12 +82,14 @@ function SectionFeatures({ sectionId }: { sectionId: string }) {
             sectionId,
             title: newTitle.trim(),
             description: newDesc.trim(),
+            icon: newIcon.trim() || undefined,
             sortOrder: features.length,
         });
         setNewTitle('');
         setNewDesc('');
+        setNewIcon('');
         setAdding(false);
-    }, [createFeature, sectionId, newTitle, newDesc, features.length]);
+    }, [createFeature, sectionId, newTitle, newDesc, newIcon, features.length]);
 
     if (isLoading) return <p className="text-xs text-muted-foreground">Loading features…</p>;
 
@@ -84,6 +107,11 @@ function SectionFeatures({ sectionId }: { sectionId: string }) {
             {features.map((f) => (
                 <div key={f.id} className="flex items-start gap-2 rounded border p-2 text-sm">
                     <GripVertical className="mt-0.5 h-3.5 w-3.5 shrink-0 text-muted-foreground/50" />
+                    {f.icon && (
+                        <Badge variant="outline" className="shrink-0 text-[10px] font-mono">
+                            {f.icon}
+                        </Badge>
+                    )}
                     <div className="min-w-0 flex-1">
                         <p className="font-medium">{f.title}</p>
                         <p className="text-xs text-muted-foreground line-clamp-1">{f.description}</p>
@@ -95,12 +123,20 @@ function SectionFeatures({ sectionId }: { sectionId: string }) {
             ))}
             {adding && (
                 <div className="space-y-2 rounded border border-dashed p-2">
-                    <Input
-                        placeholder="Feature title"
-                        value={newTitle}
-                        onChange={(e) => setNewTitle(e.target.value)}
-                        className="h-8 text-sm"
-                    />
+                    <div className="flex gap-2">
+                        <Input
+                            placeholder="Feature title"
+                            value={newTitle}
+                            onChange={(e) => setNewTitle(e.target.value)}
+                            className="h-8 text-sm"
+                        />
+                        <Input
+                            placeholder="Icon (e.g. Zap)"
+                            value={newIcon}
+                            onChange={(e) => setNewIcon(e.target.value)}
+                            className="h-8 text-sm w-32"
+                        />
+                    </div>
                     <Textarea
                         placeholder="Short description"
                         value={newDesc}
@@ -125,6 +161,7 @@ function SectionFeatures({ sectionId }: { sectionId: string }) {
                                 setAdding(false);
                                 setNewTitle('');
                                 setNewDesc('');
+                                setNewIcon('');
                             }}
                         >
                             Cancel
@@ -148,6 +185,7 @@ function SectionActions({ sectionId }: { sectionId: string }) {
     const [newLabel, setNewLabel] = useState('');
     const [newHref, setNewHref] = useState('');
     const [newVariant, setNewVariant] = useState('default');
+    const [newIcon, setNewIcon] = useState('');
 
     const actions = (Array.isArray(data) ? data : []) as HomepageActionRow[];
 
@@ -158,14 +196,16 @@ function SectionActions({ sectionId }: { sectionId: string }) {
             label: newLabel.trim(),
             href: newHref.trim(),
             variant: newVariant,
+            icon: newIcon.trim() || undefined,
             external: newHref.startsWith('http'),
             sortOrder: actions.length,
         });
         setNewLabel('');
         setNewHref('');
         setNewVariant('default');
+        setNewIcon('');
         setAdding(false);
-    }, [createAction, sectionId, newLabel, newHref, newVariant, actions.length]);
+    }, [createAction, sectionId, newLabel, newHref, newVariant, newIcon, actions.length]);
 
     if (isLoading) return <p className="text-xs text-muted-foreground">Loading actions…</p>;
 
@@ -186,6 +226,11 @@ function SectionActions({ sectionId }: { sectionId: string }) {
                     <Badge variant="outline" className="shrink-0 text-[10px]">
                         {a.variant ?? 'default'}
                     </Badge>
+                    {a.icon && (
+                        <Badge variant="secondary" className="shrink-0 text-[10px] font-mono">
+                            {a.icon}
+                        </Badge>
+                    )}
                     <span className="truncate font-medium">{a.label}</span>
                     <span className="ml-auto truncate text-xs text-muted-foreground">{a.href}</span>
                     {a.external && <ExternalLink className="h-3 w-3 shrink-0 text-muted-foreground" />}
@@ -229,6 +274,12 @@ function SectionActions({ sectionId }: { sectionId: string }) {
                                 </option>
                             ))}
                         </select>
+                        <Input
+                            placeholder="Icon (e.g. ArrowRight)"
+                            value={newIcon}
+                            onChange={(e) => setNewIcon(e.target.value)}
+                            className="h-8 text-sm w-40"
+                        />
                     </div>
                     <div className="flex gap-2">
                         <Button size="sm" className="h-7 text-xs" onClick={handleAdd} disabled={createAction.isPending}>
@@ -242,6 +293,7 @@ function SectionActions({ sectionId }: { sectionId: string }) {
                                 setAdding(false);
                                 setNewLabel('');
                                 setNewHref('');
+                                setNewIcon('');
                             }}
                         >
                             Cancel
@@ -261,6 +313,7 @@ export function AdminHomepageSectionsPage() {
         ADMIN_LIST_QUERY_CONFIG,
     );
     const createSection = homepageSectionHooks.useCreate();
+    const updateSection = homepageSectionHooks.useUpdate();
     const deleteSection = homepageSectionHooks.useDelete();
     const [deleteDialog, setDeleteDialog] = useState<{ id: string; slot: string } | null>(null);
 
@@ -271,11 +324,29 @@ export function AdminHomepageSectionsPage() {
     const handleCreateSection = async (slot: string) => {
         await createSection.mutateAsync({
             slot,
-            title: SLOT_LABELS[slot] ?? slot,
+            title: SLOT_LABELS[slot as SlotName] ?? slot,
             sortOrder: sections.length,
+            enabled: true,
         });
     };
 
+    const handleToggleEnabled = async (section: HomepageSectionRow) => {
+        await updateSection.mutateAsync({
+            id: section.id,
+            data: { enabled: !section.enabled },
+        });
+    };
+
+    const handleMoveSection = async (section: HomepageSectionRow, direction: 'up' | 'down') => {
+        const idx = sections.findIndex((s) => s.id === section.id);
+        const swapIdx = direction === 'up' ? idx - 1 : idx + 1;
+        if (swapIdx < 0 || swapIdx >= sections.length) return;
+        const other = sections[swapIdx];
+        // Swap sort orders
+        await updateSection.mutateAsync({ id: section.id, data: { sortOrder: other.sortOrder } });
+        await updateSection.mutateAsync({ id: other.id, data: { sortOrder: section.sortOrder } });
+    };
+
     const handleConfirmDelete = async () => {
         if (!deleteDialog) return;
         try {
@@ -287,19 +358,27 @@ export function AdminHomepageSectionsPage() {
         }
     };
 
+    const enabledCount = sections.filter((s) => s.enabled).length;
+    const totalFeatures = 0; // Could be computed if needed
+    const totalActions = 0;
+
     return (
         <div className="space-y-6">
             <HomepageAdminNav />
 
-            {/* Header */}
+            {/* Header with stats */}
             <div className="flex flex-col gap-4 sm:flex-row sm:items-center sm:justify-between">
                 <div>
                     <h1 className="text-3xl font-bold tracking-tight">Homepage Sections</h1>
                     <p className="text-muted-foreground mt-1">
-                        Manage content for each homepage slot. Each slot drives the corresponding section on the Next.js
-                        homepage.
+                        Manage content for each homepage slot. Toggle sections on/off, reorder, and edit inline.
                     </p>
                 </div>
+                <div className="flex items-center gap-3">
+                    <Badge variant="secondary" className="text-xs">
+                        {enabledCount}/{sections.length} active
+                    </Badge>
+                </div>
             </div>
 
             {/* Quick-add for missing slots */}
@@ -307,21 +386,29 @@ export function AdminHomepageSectionsPage() {
                 <Card>
                     <CardHeader className="pb-3">
                         <CardTitle className="text-base">Add Section</CardTitle>
-                        <CardDescription>Create a section for a slot that doesn't have one yet.</CardDescription>
+                        <CardDescription>
+                            Create a section for a slot that doesn&apos;t have one yet. Each slot maps to a section on the
+                            homepage.
+                        </CardDescription>
                     </CardHeader>
                     <CardContent>
-                        <div className="flex flex-wrap gap-2">
+                        <div className="grid gap-2 sm:grid-cols-2 md:grid-cols-3">
                             {availableSlots.map((slot) => (
-                                <Button
+                                <button
                                     key={slot}
-                                    variant="outline"
-                                    size="sm"
+                                    type="button"
                                     onClick={() => handleCreateSection(slot)}
                                     disabled={createSection.isPending}
+                                    className="flex items-start gap-3 rounded-lg border border-dashed p-3 text-left transition-colors hover:border-primary hover:bg-primary/5 disabled:opacity-50"
                                 >
-                                    <Plus className="mr-1.5 h-3.5 w-3.5" />
-                                    {SLOT_LABELS[slot]}
-                                </Button>
+                                    <Plus className="mt-0.5 h-4 w-4 shrink-0 text-primary" />
+                                    <div className="min-w-0">
+                                        <p className="text-sm font-medium">{SLOT_LABELS[slot]}</p>
+                                        <p className="text-xs text-muted-foreground line-clamp-2">
+                                            {SLOT_DESCRIPTIONS[slot]}
+                                        </p>
+                                    </div>
+                                </button>
                             ))}
                         </div>
                     </CardContent>
@@ -351,47 +438,127 @@ export function AdminHomepageSectionsPage() {
             )}
 
             {/* Section cards */}
-            {sections.map((section) => (
-                <Card key={section.id}>
-                    <CardHeader className="pb-3">
-                        <div className="flex items-start justify-between">
-                            <div>
-                                <div className="flex items-center gap-2">
-                                    <Badge variant="outline" className="font-mono text-xs">
-                                        {section.slot}
-                                    </Badge>
-                                    <CardTitle className="text-lg">{section.title ?? '(untitled)'}</CardTitle>
+            <TooltipProvider>
+                {sections.map((section, idx) => (
+                    <Card
+                        key={section.id}
+                        className={`transition-opacity ${!section.enabled ? 'opacity-60' : ''}`}
+                    >
+                        <CardHeader className="pb-3">
+                            <div className="flex items-start justify-between gap-2">
+                                <div className="flex items-start gap-3 min-w-0">
+                                    {/* Enable/disable toggle */}
+                                    <Tooltip>
+                                        <TooltipTrigger asChild>
+                                            <button
+                                                type="button"
+                                                onClick={() => handleToggleEnabled(section)}
+                                                className="mt-0.5 shrink-0"
+                                                aria-label={section.enabled ? 'Disable section' : 'Enable section'}
+                                            >
+                                                {section.enabled ? (
+                                                    <Eye className="h-4 w-4 text-primary" />
+                                                ) : (
+                                                    <EyeOff className="h-4 w-4 text-muted-foreground" />
+                                                )}
+                                            </button>
+                                        </TooltipTrigger>
+                                        <TooltipContent>
+                                            {section.enabled ? 'Click to hide this section' : 'Click to show this section'}
+                                        </TooltipContent>
+                                    </Tooltip>
+                                    <div className="min-w-0">
+                                        <div className="flex flex-wrap items-center gap-2">
+                                            <Badge variant="outline" className="font-mono text-xs shrink-0">
+                                                {section.slot}
+                                            </Badge>
+                                            {section.icon && (
+                                                <Badge variant="secondary" className="text-[10px] font-mono shrink-0">
+                                                    {section.icon}
+                                                </Badge>
+                                            )}
+                                            <CardTitle className="text-lg">
+                                                {section.title ?? '(untitled)'}
+                                            </CardTitle>
+                                        </div>
+                                        {section.subtitle && (
+                                            <CardDescription className="mt-1">{section.subtitle}</CardDescription>
+                                        )}
+                                    </div>
+                                </div>
+                                <div className="flex items-center gap-1 shrink-0">
+                                    {/* Sort controls */}
+                                    <Tooltip>
+                                        <TooltipTrigger asChild>
+                                            <Button
+                                                variant="ghost"
+                                                size="icon"
+                                                className="h-8 w-8"
+                                                onClick={() => handleMoveSection(section, 'up')}
+                                                disabled={idx === 0 || updateSection.isPending}
+                                            >
+                                                <ArrowUp className="h-3.5 w-3.5" />
+                                            </Button>
+                                        </TooltipTrigger>
+                                        <TooltipContent>Move up</TooltipContent>
+                                    </Tooltip>
+                                    <Tooltip>
+                                        <TooltipTrigger asChild>
+                                            <Button
+                                                variant="ghost"
+                                                size="icon"
+                                                className="h-8 w-8"
+                                                onClick={() => handleMoveSection(section, 'down')}
+                                                disabled={idx === sections.length - 1 || updateSection.isPending}
+                                            >
+                                                <ArrowDown className="h-3.5 w-3.5" />
+                                            </Button>
+                                        </TooltipTrigger>
+                                        <TooltipContent>Move down</TooltipContent>
+                                    </Tooltip>
+                                    <Button variant="ghost" size="icon" className="h-8 w-8" asChild>
+                                        <Link to="/admin/homepage/$sectionId/edit" params={{ sectionId: section.id }}>
+                                            <Edit className="h-4 w-4" />
+                                        </Link>
+                                    </Button>
+                                    <Button
+                                        variant="ghost"
+                                        size="icon"
+                                        className="h-8 w-8"
+                                        onClick={() => setDeleteDialog({ id: section.id, slot: section.slot })}
+                                    >
+                                        <Trash2 className="h-4 w-4 text-destructive" />
+                                    </Button>
                                 </div>
-                                {section.subtitle && (
-                                    <CardDescription className="mt-1">{section.subtitle}</CardDescription>
-                                )}
-                            </div>
-                            <div className="flex gap-1">
-                                <Button variant="ghost" size="icon" asChild>
-                                    <Link to="/admin/homepage/$sectionId/edit" params={{ sectionId: section.id }}>
-                                        <Edit className="h-4 w-4" />
-                                    </Link>
-                                </Button>
-                                <Button
-                                    variant="ghost"
-                                    size="icon"
-                                    onClick={() => setDeleteDialog({ id: section.id, slot: section.slot })}
-                                >
-                                    <Trash2 className="h-4 w-4 text-destructive" />
-                                </Button>
                             </div>
-                        </div>
-                    </CardHeader>
-                    <CardContent className="space-y-4">
-                        {section.body && <p className="text-sm text-muted-foreground line-clamp-2">{section.body}</p>}
+                        </CardHeader>
+                        <CardContent className="space-y-3">
+                            {section.body && <p className="text-sm text-muted-foreground line-clamp-2">{section.body}</p>}
+                            {section.cssClasses && (
+                                <p className="text-xs font-mono text-muted-foreground">
+                                    CSS: {section.cssClasses}
+                                </p>
+                            )}
 
-                        <div className="grid gap-4 md:grid-cols-2">
-                            <SectionFeatures sectionId={section.id} />
-                            <SectionActions sectionId={section.id} />
-                        </div>
-                    </CardContent>
-                </Card>
-            ))}
+                            {/* Collapsible children */}
+                            <Collapsible>
+                                <CollapsibleTrigger asChild>
+                                    <Button variant="ghost" size="sm" className="h-7 gap-1.5 text-xs w-full justify-start">
+                                        <ChevronDown className="h-3 w-3" />
+                                        Features &amp; Actions
+                                    </Button>
+                                </CollapsibleTrigger>
+                                <CollapsibleContent>
+                                    <div className="grid gap-4 md:grid-cols-2 pt-2">
+                                        <SectionFeatures sectionId={section.id} />
+                                        <SectionActions sectionId={section.id} />
+                                    </div>
+                                </CollapsibleContent>
+                            </Collapsible>
+                        </CardContent>
+                    </Card>
+                ))}
+            </TooltipProvider>
 
             {/* Delete confirmation */}
             <AlertDialog open={deleteDialog !== null} onOpenChange={(open) => !open && setDeleteDialog(null)}>
@@ -399,7 +566,7 @@ export function AdminHomepageSectionsPage() {
                     <AlertDialogHeader>
                         <AlertDialogTitle>Delete Section?</AlertDialogTitle>
                         <AlertDialogDescription>
-                            This will permanently remove the "{deleteDialog?.slot}" section and all its features and
+                            This will permanently remove the &quot;{deleteDialog?.slot}&quot; section and all its features and
                             actions. This cannot be undone.
                         </AlertDialogDescription>
                     </AlertDialogHeader>
diff --git a/apps/ottabase-template-app-tanstack/src/pages/admin/homepage/HomepageAdminNav.tsx b/apps/ottabase-template-app-tanstack/src/pages/admin/homepage/HomepageAdminNav.tsx
index ad2aade63..60cc8bfe6 100644
--- a/apps/ottabase-template-app-tanstack/src/pages/admin/homepage/HomepageAdminNav.tsx
+++ b/apps/ottabase-template-app-tanstack/src/pages/admin/homepage/HomepageAdminNav.tsx
@@ -2,37 +2,51 @@
  * Homepage Admin Navigation
  *
  * Tab navigation for the homepage management section.
- * Pattern: follows BlogAdminNav.tsx.
+ * Uses shadcn Tabs for a polished, consistent admin experience.
  */
-import { Link, useRouterState } from '@tanstack/react-router';
+import { Link, useNavigate, useRouterState } from '@tanstack/react-router';
+import { Home, Layout, Monitor, FileText } from 'lucide-react';
+import { Tabs, TabsList, TabsTrigger } from '@ottabase/ui-shadcn';
 
 const TABS = [
-    { href: '/admin/homepage', label: 'Sections', exact: true },
-    { href: '/admin/homepage/display', label: 'Display Settings' },
+    { href: '/admin/homepage', label: 'Sections', icon: Layout, exact: true },
+    { href: '/admin/homepage/display', label: 'Display', icon: Monitor },
+    { href: '/admin/homepage/pages', label: 'Pages', icon: FileText },
 ] as const;
 
 export function HomepageAdminNav() {
     const { location } = useRouterState();
+    const navigate = useNavigate();
     const pathname = location.pathname;
 
+    // Determine the active tab value from the current path
+    const activeTab =
+        TABS.find((tab) => ('exact' in tab && tab.exact ? pathname === tab.href : pathname.startsWith(tab.href)))
+            ?.href ?? TABS[0].href;
+
     return (
-        <nav className="flex gap-1 border-b pb-2" aria-label="Homepage admin navigation">
-            {TABS.map(({ href, label, exact }) => {
-                const isActive = exact ? pathname === href : pathname.startsWith(href);
-                return (
-                    <Link
-                        key={href}
-                        to={href}
-                        className={`rounded-md px-3 py-1.5 text-sm font-medium transition-colors ${
-                            isActive
-                                ? 'bg-primary text-primary-foreground'
-                                : 'text-muted-foreground hover:bg-muted hover:text-foreground'
-                        }`}
-                    >
-                        {label}
-                    </Link>
-                );
-            })}
-        </nav>
+        <div className="space-y-4">
+            <div className="flex items-center gap-3">
+                <div className="flex items-center gap-2 rounded-lg bg-primary/10 p-2">
+                    <Home className="h-5 w-5 text-primary" />
+                </div>
+                <div>
+                    <h2 className="text-lg font-semibold tracking-tight">Homepage Manager</h2>
+                    <p className="text-xs text-muted-foreground">Configure sections, display settings, and CMS pages</p>
+                </div>
+            </div>
+            <Tabs value={activeTab} onValueChange={(v) => navigate({ to: v })}>
+                <TabsList className="w-full justify-start">
+                    {TABS.map(({ href, label, icon: Icon }) => (
+                        <TabsTrigger key={href} value={href} className="gap-1.5" asChild>
+                            <Link to={href}>
+                                <Icon className="h-3.5 w-3.5" />
+                                {label}
+                            </Link>
+                        </TabsTrigger>
+                    ))}
+                </TabsList>
+            </Tabs>
+        </div>
     );
 }
diff --git a/apps/ottabase-template-app-tanstack/src/pages/admin/homepage/homepage-constants.ts b/apps/ottabase-template-app-tanstack/src/pages/admin/homepage/homepage-constants.ts
index b51340b09..287211118 100644
--- a/apps/ottabase-template-app-tanstack/src/pages/admin/homepage/homepage-constants.ts
+++ b/apps/ottabase-template-app-tanstack/src/pages/admin/homepage/homepage-constants.ts
@@ -2,7 +2,7 @@
  * Homepage Admin Constants
  *
  * Single source of truth for slot names, labels, variant metadata,
- * and action button variants used across all homepage admin pages.
+ * action button variants, and theme presets used across all homepage admin pages.
  *
  * Mirrors SLOT_NAMES and SLOT_REGISTRY from the Next.js homepage-config.ts.
  */
@@ -21,6 +21,26 @@ export const SLOT_LABELS: Record<SlotName, string> = {
     about: 'About Page',
 };
 
+/** Short descriptions for each slot. */
+export const SLOT_DESCRIPTIONS: Record<SlotName, string> = {
+    navbar: 'Site navigation, logo, and links displayed at the top of every page.',
+    hero: 'Primary headline, subtitle, and call-to-action buttons above the fold.',
+    features: 'Product capabilities displayed as a grid, cards, or list.',
+    cta: 'Conversion-focused section with headline, description, and action buttons.',
+    footer: 'Site-wide footer with branding, links, and copyright.',
+    about: 'Detailed overview page with features, tech stack, and team info.',
+};
+
+/** Lucide icon names for each slot (used in admin UI badges). */
+export const SLOT_ICONS: Record<SlotName, string> = {
+    navbar: 'Navigation',
+    hero: 'Sparkles',
+    features: 'Grid3X3',
+    cta: 'Megaphone',
+    footer: 'Rows3',
+    about: 'FileText',
+};
+
 /** Available button style variants (matches shadcn Button component). */
 export const ACTION_VARIANTS = [
     { value: 'default', label: 'Default' },
@@ -29,6 +49,18 @@ export const ACTION_VARIANTS = [
     { value: 'ghost', label: 'Ghost' },
 ] as const;
 
+/** Available theme presets for the homepage. */
+export const THEME_PRESETS = [
+    { id: 'default', label: 'Default', description: 'Clean and professional' },
+    { id: 'neo', label: 'Neo', description: 'Bold modern aesthetic' },
+    { id: 'crisp', label: 'Crisp', description: 'Sharp minimal look' },
+    { id: 'warm', label: 'Warm', description: 'Friendly earthy tones' },
+    { id: 'midnight', label: 'Midnight', description: 'Dark dramatic style' },
+    { id: 'ocean', label: 'Ocean', description: 'Cool aquatic palette' },
+    { id: 'forest', label: 'Forest', description: 'Natural green hues' },
+    { id: 'sunset', label: 'Sunset', description: 'Warm gradient feel' },
+] as const;
+
 /** Variant option for a slot's display mode. */
 export interface SlotVariantOption {
     id: string;
@@ -113,3 +145,12 @@ export function getDefaultVariantBySlot(): Record<string, string> {
     }
     return d;
 }
+
+/** Common lucide icon suggestions for features and actions. */
+export const ICON_SUGGESTIONS = [
+    'Zap', 'Shield', 'Globe', 'Sparkles', 'Rocket', 'Heart', 'Star',
+    'ArrowRight', 'Github', 'Code', 'Database', 'Cloud', 'Lock', 'Users',
+    'Settings', 'Palette', 'Layout', 'Layers', 'Package', 'Terminal',
+    'BookOpen', 'FileText', 'Image', 'Video', 'Music', 'Mail',
+    'Phone', 'MapPin', 'Calendar', 'Clock', 'CheckCircle', 'AlertCircle',
+] as const;
diff --git a/apps/ottabase-template-app-tanstack/src/pages/admin/homepage/index.ts b/apps/ottabase-template-app-tanstack/src/pages/admin/homepage/index.ts
index 44755840d..1e49e92be 100644
--- a/apps/ottabase-template-app-tanstack/src/pages/admin/homepage/index.ts
+++ b/apps/ottabase-template-app-tanstack/src/pages/admin/homepage/index.ts
@@ -1,5 +1,15 @@
 export { AdminHomepageDisplayPage } from './AdminHomepageDisplayPage';
+export { AdminHomepagePagesPage } from './AdminHomepagePagesPage';
 export { AdminHomepageSectionEditorPage } from './AdminHomepageSectionEditorPage';
 export { AdminHomepageSectionsPage } from './AdminHomepageSectionsPage';
 export { HomepageAdminNav } from './HomepageAdminNav';
-export { ACTION_VARIANTS, SLOT_CONFIG, SLOT_LABELS, SLOT_NAMES } from './homepage-constants';
+export {
+    ACTION_VARIANTS,
+    ICON_SUGGESTIONS,
+    SLOT_CONFIG,
+    SLOT_DESCRIPTIONS,
+    SLOT_ICONS,
+    SLOT_LABELS,
+    SLOT_NAMES,
+    THEME_PRESETS,
+} from './homepage-constants';
diff --git a/apps/ottabase-template-app-tanstack/src/router.tsx b/apps/ottabase-template-app-tanstack/src/router.tsx
index a76a4b371..cdbe982ff 100644
--- a/apps/ottabase-template-app-tanstack/src/router.tsx
+++ b/apps/ottabase-template-app-tanstack/src/router.tsx
@@ -962,6 +962,16 @@ const adminHomepageDisplayRoute = new Route({
     ),
 });
 
+const adminHomepagePagesRoute = new Route({
+    getParentRoute: () => rootRoute,
+    path: '/admin/homepage/pages',
+    component: lazyRouteComponent(() =>
+        import('@/pages/admin/homepage/AdminHomepagePagesPage').then((m) => ({
+            default: () => renderAdminRoute(<m.AdminHomepagePagesPage />),
+        })),
+    ),
+});
+
 // Organizations routes
 const organizationsRoute = new Route({
     getParentRoute: () => rootRoute,
@@ -1196,6 +1206,7 @@ const coreRoutes = [
     adminHomepageRoute,
     adminHomepageSectionEditRoute,
     adminHomepageDisplayRoute,
+    adminHomepagePagesRoute,
     adminDevMailRoute,
     adminQueueRoute,
     adminCronRoute,
diff --git a/apps/ottabase-template-app-tanstack/worker/routes/homepage.ts b/apps/ottabase-template-app-tanstack/worker/routes/homepage.ts
index 19e7b6379..e6fbc5f6b 100644
--- a/apps/ottabase-template-app-tanstack/worker/routes/homepage.ts
+++ b/apps/ottabase-template-app-tanstack/worker/routes/homepage.ts
@@ -41,12 +41,23 @@ interface PublicSection {
     subtitle: string | null;
     body: string | null;
     githubUrl: string | null;
+    icon: string | null;
+    enabled: boolean;
+    cssClasses: string | null;
+    metadata: Record<string, unknown> | null;
     sortOrder: number;
-    features: Array<{ title: string; description: string }>;
+    features: Array<{
+        title: string;
+        description: string;
+        icon: string | null;
+        imageUrl: string | null;
+        href: string | null;
+    }>;
     actions: Array<{
         label: string;
         href: string;
         variant: string | null;
+        icon: string | null;
         external: boolean;
     }>;
 }
@@ -56,6 +67,9 @@ interface PublicDisplay {
     variantBySlot: Record<string, string> | null;
     themePreset: string | null;
     fallbackThemePresetId: string | null;
+    customCss: string | null;
+    seoTitle: string | null;
+    seoDescription: string | null;
 }
 
 /** Shape of the full public payload */
@@ -109,19 +123,22 @@ export async function handleHomepageData(context: HomepageRouteContext): Promise
         }
 
         // Group by sectionId
-        const featuresBySectionId = new Map<string, Array<{ title: string; description: string }>>();
+        const featuresBySectionId = new Map<string, Array<{ title: string; description: string; icon: string | null; imageUrl: string | null; href: string | null }>>();
         for (const f of allFeatures) {
             const sid = f.get('sectionId') as string;
             if (!featuresBySectionId.has(sid)) featuresBySectionId.set(sid, []);
             featuresBySectionId.get(sid)!.push({
                 title: f.get('title') as string,
                 description: f.get('description') as string,
+                icon: (f.get('icon') as string) ?? null,
+                imageUrl: (f.get('imageUrl') as string) ?? null,
+                href: (f.get('href') as string) ?? null,
             });
         }
 
         const actionsBySectionId = new Map<
             string,
-            Array<{ label: string; href: string; variant: string | null; external: boolean }>
+            Array<{ label: string; href: string; variant: string | null; icon: string | null; external: boolean }>
         >();
         for (const a of allActions) {
             const sid = a.get('sectionId') as string;
@@ -130,6 +147,7 @@ export async function handleHomepageData(context: HomepageRouteContext): Promise
                 label: a.get('label') as string,
                 href: a.get('href') as string,
                 variant: (a.get('variant') as string) ?? null,
+                icon: (a.get('icon') as string) ?? null,
                 external: (a.get('external') as boolean) ?? false,
             });
         }
@@ -143,6 +161,10 @@ export async function handleHomepageData(context: HomepageRouteContext): Promise
                 subtitle: (s.get('subtitle') as string) ?? null,
                 body: (s.get('body') as string) ?? null,
                 githubUrl: (s.get('githubUrl') as string) ?? null,
+                icon: (s.get('icon') as string) ?? null,
+                enabled: (s.get('enabled') as boolean) ?? true,
+                cssClasses: (s.get('cssClasses') as string) ?? null,
+                metadata: (s.get('metadata') as Record<string, unknown>) ?? null,
                 sortOrder: (s.get('sortOrder') as number) ?? 0,
                 features: featuresBySectionId.get(id) ?? [],
                 actions: actionsBySectionId.get(id) ?? [],
@@ -155,13 +177,16 @@ export async function handleHomepageData(context: HomepageRouteContext): Promise
     }
 
     // ── 2. Display settings ────────────────────────────────────────────
-    let display: PublicDisplay = { variantBySlot: null, themePreset: null, fallbackThemePresetId: null };
+    let display: PublicDisplay = { variantBySlot: null, themePreset: null, fallbackThemePresetId: null, customCss: null, seoTitle: null, seoDescription: null };
     try {
         const settings = await HomepageDisplaySettings.getOrCreateDefault(appId);
         display = {
             variantBySlot: (settings.get('variantBySlotJson') as Record<string, string>) ?? null,
             themePreset: (settings.get('themePreset') as string) ?? null,
             fallbackThemePresetId: (settings.get('fallbackThemePresetId') as string) ?? null,
+            customCss: (settings.get('customCss') as string) ?? null,
+            seoTitle: (settings.get('seoTitle') as string) ?? null,
+            seoDescription: (settings.get('seoDescription') as string) ?? null,
         };
     } catch (err) {
         // Non-fatal: keep defaults

From 2661bd2c5ffd6a91d79f0a6687f7626c025528f5 Mon Sep 17 00:00:00 2001
From: "copilot-swe-agent[bot]" <198982749+Copilot@users.noreply.github.com>
Date: Mon, 30 Mar 2026 21:43:26 +0000
Subject: [PATCH 10/19] test: update homepage API type tests for new fields
 (enabled, icon, metadata, cssClasses, customCss, seo) + prettier format

Agent-Logs-Url: https://github.com/thinkdj/ottabase/sessions/ae722b66-1678-4b6e-9ba2-78d05e83ba45
---
 .../__tests__/components.test.tsx             | 53 +++++++++++++++++--
 .../models/HomepageDisplaySettings.ts         | 21 +++++++-
 .../ottabase/models/HomepageSection.ts        | 28 +++++++++-
 .../admin/homepage/AdminHomepagePagesPage.tsx | 22 +++-----
 .../AdminHomepageSectionEditorPage.tsx        |  7 ++-
 .../homepage/AdminHomepageSectionsPage.tsx    | 35 ++++++------
 .../admin/homepage/homepage-constants.ts      | 37 +++++++++++--
 .../worker/routes/homepage.ts                 | 20 ++++++-
 8 files changed, 173 insertions(+), 50 deletions(-)

diff --git a/apps/ottabase-template-app-nextjs-homepage/__tests__/components.test.tsx b/apps/ottabase-template-app-nextjs-homepage/__tests__/components.test.tsx
index 30368f36e..343e39189 100644
--- a/apps/ottabase-template-app-nextjs-homepage/__tests__/components.test.tsx
+++ b/apps/ottabase-template-app-nextjs-homepage/__tests__/components.test.tsx
@@ -401,16 +401,63 @@ describe('Homepage API types', () => {
                     subtitle: 'Sub',
                     body: null,
                     githubUrl: null,
+                    icon: null,
+                    enabled: true,
+                    cssClasses: null,
+                    metadata: null,
                     sortOrder: 0,
-                    features: [],
-                    actions: [{ label: 'Go', href: '/go', variant: 'default', external: false }],
+                    features: [{ title: 'Fast', description: 'Very fast', icon: 'Zap', imageUrl: null, href: null }],
+                    actions: [{ label: 'Go', href: '/go', variant: 'default', icon: null, external: false }],
                 },
             ],
-            display: { variantBySlot: { hero: 'centered' }, themePreset: 'neo', fallbackThemePresetId: null },
+            display: {
+                variantBySlot: { hero: 'centered' },
+                themePreset: 'neo',
+                fallbackThemePresetId: null,
+                customCss: null,
+                seoTitle: null,
+                seoDescription: null,
+            },
             exposedPages: [{ slug: 'about', title: 'About' }],
         };
         expect(payload.sections).toHaveLength(1);
+        expect(payload.sections[0].enabled).toBe(true);
+        expect(payload.sections[0].features[0].icon).toBe('Zap');
         expect(payload.display.themePreset).toBe('neo');
         expect(payload.exposedPages[0].slug).toBe('about');
     });
+
+    it('HomepageSectionPayload supports all configurable fields', async () => {
+        const api = await import('../lib/api');
+        const section: api.HomepageSectionPayload = {
+            id: '2',
+            slot: 'features',
+            title: 'Features',
+            subtitle: 'What we offer',
+            body: 'Detailed description',
+            githubUrl: 'https://github.com/test',
+            icon: 'Sparkles',
+            enabled: false,
+            cssClasses: 'bg-gradient-to-r from-blue-500',
+            metadata: { custom: 'value', count: 42 },
+            sortOrder: 1,
+            features: [
+                {
+                    title: 'Feature 1',
+                    description: 'Desc 1',
+                    icon: 'Shield',
+                    imageUrl: 'https://img.test/1.png',
+                    href: '/features/1',
+                },
+            ],
+            actions: [{ label: 'Learn More', href: '/learn', variant: 'outline', icon: 'ArrowRight', external: false }],
+        };
+        expect(section.icon).toBe('Sparkles');
+        expect(section.enabled).toBe(false);
+        expect(section.cssClasses).toContain('bg-gradient');
+        expect(section.metadata).toHaveProperty('custom', 'value');
+        expect(section.features[0].icon).toBe('Shield');
+        expect(section.features[0].imageUrl).toBeTruthy();
+        expect(section.actions[0].icon).toBe('ArrowRight');
+    });
 });
diff --git a/apps/ottabase-template-app-tanstack/ottabase/models/HomepageDisplaySettings.ts b/apps/ottabase-template-app-tanstack/ottabase/models/HomepageDisplaySettings.ts
index 1a350eae7..ec0202588 100644
--- a/apps/ottabase-template-app-tanstack/ottabase/models/HomepageDisplaySettings.ts
+++ b/apps/ottabase-template-app-tanstack/ottabase/models/HomepageDisplaySettings.ts
@@ -30,8 +30,25 @@ export class HomepageDisplaySettings extends BaseModel {
     };
 
     static writable = {
-        create: ['id', 'variantBySlotJson', 'themePreset', 'fallbackThemePresetId', 'customCss', 'seoTitle', 'seoDescription', 'appId'],
-        update: ['variantBySlotJson', 'themePreset', 'fallbackThemePresetId', 'customCss', 'seoTitle', 'seoDescription', 'appId'],
+        create: [
+            'id',
+            'variantBySlotJson',
+            'themePreset',
+            'fallbackThemePresetId',
+            'customCss',
+            'seoTitle',
+            'seoDescription',
+            'appId',
+        ],
+        update: [
+            'variantBySlotJson',
+            'themePreset',
+            'fallbackThemePresetId',
+            'customCss',
+            'seoTitle',
+            'seoDescription',
+            'appId',
+        ],
     };
 
     protected static defaults = {
diff --git a/apps/ottabase-template-app-tanstack/ottabase/models/HomepageSection.ts b/apps/ottabase-template-app-tanstack/ottabase/models/HomepageSection.ts
index 8fa4b6aee..3d7bf75ca 100644
--- a/apps/ottabase-template-app-tanstack/ottabase/models/HomepageSection.ts
+++ b/apps/ottabase-template-app-tanstack/ottabase/models/HomepageSection.ts
@@ -28,8 +28,32 @@ export class HomepageSection extends BaseModel {
     };
 
     static writable = {
-        create: ['slot', 'title', 'subtitle', 'body', 'githubUrl', 'icon', 'enabled', 'cssClasses', 'metadata', 'sortOrder', 'appId'],
-        update: ['slot', 'title', 'subtitle', 'body', 'githubUrl', 'icon', 'enabled', 'cssClasses', 'metadata', 'sortOrder', 'appId'],
+        create: [
+            'slot',
+            'title',
+            'subtitle',
+            'body',
+            'githubUrl',
+            'icon',
+            'enabled',
+            'cssClasses',
+            'metadata',
+            'sortOrder',
+            'appId',
+        ],
+        update: [
+            'slot',
+            'title',
+            'subtitle',
+            'body',
+            'githubUrl',
+            'icon',
+            'enabled',
+            'cssClasses',
+            'metadata',
+            'sortOrder',
+            'appId',
+        ],
     };
 
     protected static defaults = {
diff --git a/apps/ottabase-template-app-tanstack/src/pages/admin/homepage/AdminHomepagePagesPage.tsx b/apps/ottabase-template-app-tanstack/src/pages/admin/homepage/AdminHomepagePagesPage.tsx
index 39c4c3e06..cdda0dac4 100644
--- a/apps/ottabase-template-app-tanstack/src/pages/admin/homepage/AdminHomepagePagesPage.tsx
+++ b/apps/ottabase-template-app-tanstack/src/pages/admin/homepage/AdminHomepagePagesPage.tsx
@@ -6,16 +6,7 @@
  */
 import { ADMIN_LIST_QUERY_CONFIG } from '@/config/queryConfig';
 import { createModelHooks } from '@ottabase/ottaorm/client';
-import {
-    Badge,
-    Button,
-    Card,
-    CardContent,
-    CardDescription,
-    CardHeader,
-    CardTitle,
-    Switch,
-} from '@ottabase/ui-shadcn';
+import { Badge, Button, Card, CardContent, CardDescription, CardHeader, CardTitle, Switch } from '@ottabase/ui-shadcn';
 import { Link } from '@tanstack/react-router';
 import { Edit, ExternalLink, Eye, EyeOff, FileText, Globe, Plus } from 'lucide-react';
 import { HomepageAdminNav } from './HomepageAdminNav';
@@ -111,7 +102,8 @@ export function AdminHomepagePagesPage() {
                     <CardHeader className="pb-3">
                         <CardTitle className="text-base">All Pages</CardTitle>
                         <CardDescription>
-                            Toggle &quot;Expose to Homepage&quot; to add pages to the navbar. Pages must be published to appear.
+                            Toggle &quot;Expose to Homepage&quot; to add pages to the navbar. Pages must be published to
+                            appear.
                         </CardDescription>
                     </CardHeader>
                     <CardContent>
@@ -181,10 +173,10 @@ export function AdminHomepagePagesPage() {
                         <div className="text-sm text-muted-foreground">
                             <p className="font-medium text-foreground">How pages work</p>
                             <p className="mt-1">
-                                Pages are CMS content with type &quot;Page&quot; created in the Blog Editor.
-                                When exposed to the homepage, they appear as links in the navigation bar.
-                                Each page renders at <code className="text-xs bg-muted px-1 py-0.5 rounded">/page/slug</code> on
-                                the Next.js homepage.
+                                Pages are CMS content with type &quot;Page&quot; created in the Blog Editor. When
+                                exposed to the homepage, they appear as links in the navigation bar. Each page renders
+                                at <code className="text-xs bg-muted px-1 py-0.5 rounded">/page/slug</code> on the
+                                Next.js homepage.
                             </p>
                         </div>
                     </div>
diff --git a/apps/ottabase-template-app-tanstack/src/pages/admin/homepage/AdminHomepageSectionEditorPage.tsx b/apps/ottabase-template-app-tanstack/src/pages/admin/homepage/AdminHomepageSectionEditorPage.tsx
index c8815730f..68afd32d8 100644
--- a/apps/ottabase-template-app-tanstack/src/pages/admin/homepage/AdminHomepageSectionEditorPage.tsx
+++ b/apps/ottabase-template-app-tanstack/src/pages/admin/homepage/AdminHomepageSectionEditorPage.tsx
@@ -440,7 +440,8 @@ export function AdminHomepageSectionEditorPage() {
             githubUrl !== ((section?.githubUrl as string) ?? '') ||
             icon !== ((section?.icon as string) ?? '') ||
             cssClasses !== ((section?.cssClasses as string) ?? '') ||
-            metadataStr !== (section?.metadata ? JSON.stringify(section.metadata as Record<string, unknown>, null, 2) : ''));
+            metadataStr !==
+                (section?.metadata ? JSON.stringify(section.metadata as Record<string, unknown>, null, 2) : ''));
 
     const handleSaveSection = useCallback(async () => {
         if (!sectionId || !dirty) return;
@@ -694,9 +695,7 @@ export function AdminHomepageSectionEditorPage() {
                     <div className="flex items-center justify-between">
                         <div>
                             <CardTitle className="text-base">Features ({features.length})</CardTitle>
-                            <CardDescription>
-                                Feature items with icon, image, and link support.
-                            </CardDescription>
+                            <CardDescription>Feature items with icon, image, and link support.</CardDescription>
                         </div>
                         <Button
                             variant="outline"
diff --git a/apps/ottabase-template-app-tanstack/src/pages/admin/homepage/AdminHomepageSectionsPage.tsx b/apps/ottabase-template-app-tanstack/src/pages/admin/homepage/AdminHomepageSectionsPage.tsx
index 3801ecc5d..fca728619 100644
--- a/apps/ottabase-template-app-tanstack/src/pages/admin/homepage/AdminHomepageSectionsPage.tsx
+++ b/apps/ottabase-template-app-tanstack/src/pages/admin/homepage/AdminHomepageSectionsPage.tsx
@@ -387,8 +387,8 @@ export function AdminHomepageSectionsPage() {
                     <CardHeader className="pb-3">
                         <CardTitle className="text-base">Add Section</CardTitle>
                         <CardDescription>
-                            Create a section for a slot that doesn&apos;t have one yet. Each slot maps to a section on the
-                            homepage.
+                            Create a section for a slot that doesn&apos;t have one yet. Each slot maps to a section on
+                            the homepage.
                         </CardDescription>
                     </CardHeader>
                     <CardContent>
@@ -440,10 +440,7 @@ export function AdminHomepageSectionsPage() {
             {/* Section cards */}
             <TooltipProvider>
                 {sections.map((section, idx) => (
-                    <Card
-                        key={section.id}
-                        className={`transition-opacity ${!section.enabled ? 'opacity-60' : ''}`}
-                    >
+                    <Card key={section.id} className={`transition-opacity ${!section.enabled ? 'opacity-60' : ''}`}>
                         <CardHeader className="pb-3">
                             <div className="flex items-start justify-between gap-2">
                                 <div className="flex items-start gap-3 min-w-0">
@@ -464,7 +461,9 @@ export function AdminHomepageSectionsPage() {
                                             </button>
                                         </TooltipTrigger>
                                         <TooltipContent>
-                                            {section.enabled ? 'Click to hide this section' : 'Click to show this section'}
+                                            {section.enabled
+                                                ? 'Click to hide this section'
+                                                : 'Click to show this section'}
                                         </TooltipContent>
                                     </Tooltip>
                                     <div className="min-w-0">
@@ -477,9 +476,7 @@ export function AdminHomepageSectionsPage() {
                                                     {section.icon}
                                                 </Badge>
                                             )}
-                                            <CardTitle className="text-lg">
-                                                {section.title ?? '(untitled)'}
-                                            </CardTitle>
+                                            <CardTitle className="text-lg">{section.title ?? '(untitled)'}</CardTitle>
                                         </div>
                                         {section.subtitle && (
                                             <CardDescription className="mt-1">{section.subtitle}</CardDescription>
@@ -533,17 +530,21 @@ export function AdminHomepageSectionsPage() {
                             </div>
                         </CardHeader>
                         <CardContent className="space-y-3">
-                            {section.body && <p className="text-sm text-muted-foreground line-clamp-2">{section.body}</p>}
+                            {section.body && (
+                                <p className="text-sm text-muted-foreground line-clamp-2">{section.body}</p>
+                            )}
                             {section.cssClasses && (
-                                <p className="text-xs font-mono text-muted-foreground">
-                                    CSS: {section.cssClasses}
-                                </p>
+                                <p className="text-xs font-mono text-muted-foreground">CSS: {section.cssClasses}</p>
                             )}
 
                             {/* Collapsible children */}
                             <Collapsible>
                                 <CollapsibleTrigger asChild>
-                                    <Button variant="ghost" size="sm" className="h-7 gap-1.5 text-xs w-full justify-start">
+                                    <Button
+                                        variant="ghost"
+                                        size="sm"
+                                        className="h-7 gap-1.5 text-xs w-full justify-start"
+                                    >
                                         <ChevronDown className="h-3 w-3" />
                                         Features &amp; Actions
                                     </Button>
@@ -566,8 +567,8 @@ export function AdminHomepageSectionsPage() {
                     <AlertDialogHeader>
                         <AlertDialogTitle>Delete Section?</AlertDialogTitle>
                         <AlertDialogDescription>
-                            This will permanently remove the &quot;{deleteDialog?.slot}&quot; section and all its features and
-                            actions. This cannot be undone.
+                            This will permanently remove the &quot;{deleteDialog?.slot}&quot; section and all its
+                            features and actions. This cannot be undone.
                         </AlertDialogDescription>
                     </AlertDialogHeader>
                     <AlertDialogFooter>
diff --git a/apps/ottabase-template-app-tanstack/src/pages/admin/homepage/homepage-constants.ts b/apps/ottabase-template-app-tanstack/src/pages/admin/homepage/homepage-constants.ts
index 287211118..fb93f1d3d 100644
--- a/apps/ottabase-template-app-tanstack/src/pages/admin/homepage/homepage-constants.ts
+++ b/apps/ottabase-template-app-tanstack/src/pages/admin/homepage/homepage-constants.ts
@@ -148,9 +148,36 @@ export function getDefaultVariantBySlot(): Record<string, string> {
 
 /** Common lucide icon suggestions for features and actions. */
 export const ICON_SUGGESTIONS = [
-    'Zap', 'Shield', 'Globe', 'Sparkles', 'Rocket', 'Heart', 'Star',
-    'ArrowRight', 'Github', 'Code', 'Database', 'Cloud', 'Lock', 'Users',
-    'Settings', 'Palette', 'Layout', 'Layers', 'Package', 'Terminal',
-    'BookOpen', 'FileText', 'Image', 'Video', 'Music', 'Mail',
-    'Phone', 'MapPin', 'Calendar', 'Clock', 'CheckCircle', 'AlertCircle',
+    'Zap',
+    'Shield',
+    'Globe',
+    'Sparkles',
+    'Rocket',
+    'Heart',
+    'Star',
+    'ArrowRight',
+    'Github',
+    'Code',
+    'Database',
+    'Cloud',
+    'Lock',
+    'Users',
+    'Settings',
+    'Palette',
+    'Layout',
+    'Layers',
+    'Package',
+    'Terminal',
+    'BookOpen',
+    'FileText',
+    'Image',
+    'Video',
+    'Music',
+    'Mail',
+    'Phone',
+    'MapPin',
+    'Calendar',
+    'Clock',
+    'CheckCircle',
+    'AlertCircle',
 ] as const;
diff --git a/apps/ottabase-template-app-tanstack/worker/routes/homepage.ts b/apps/ottabase-template-app-tanstack/worker/routes/homepage.ts
index e6fbc5f6b..51e79043a 100644
--- a/apps/ottabase-template-app-tanstack/worker/routes/homepage.ts
+++ b/apps/ottabase-template-app-tanstack/worker/routes/homepage.ts
@@ -123,7 +123,16 @@ export async function handleHomepageData(context: HomepageRouteContext): Promise
         }
 
         // Group by sectionId
-        const featuresBySectionId = new Map<string, Array<{ title: string; description: string; icon: string | null; imageUrl: string | null; href: string | null }>>();
+        const featuresBySectionId = new Map<
+            string,
+            Array<{
+                title: string;
+                description: string;
+                icon: string | null;
+                imageUrl: string | null;
+                href: string | null;
+            }>
+        >();
         for (const f of allFeatures) {
             const sid = f.get('sectionId') as string;
             if (!featuresBySectionId.has(sid)) featuresBySectionId.set(sid, []);
@@ -177,7 +186,14 @@ export async function handleHomepageData(context: HomepageRouteContext): Promise
     }
 
     // ── 2. Display settings ────────────────────────────────────────────
-    let display: PublicDisplay = { variantBySlot: null, themePreset: null, fallbackThemePresetId: null, customCss: null, seoTitle: null, seoDescription: null };
+    let display: PublicDisplay = {
+        variantBySlot: null,
+        themePreset: null,
+        fallbackThemePresetId: null,
+        customCss: null,
+        seoTitle: null,
+        seoDescription: null,
+    };
     try {
         const settings = await HomepageDisplaySettings.getOrCreateDefault(appId);
         display = {

From 00a4fc61bff14bfdae7feb186d5472b73e2f45a0 Mon Sep 17 00:00:00 2001
From: "copilot-swe-agent[bot]" <198982749+Copilot@users.noreply.github.com>
Date: Mon, 30 Mar 2026 21:48:41 +0000
Subject: [PATCH 11/19] fix: replace HTML entities with JSX expressions in
 admin homepage pages

Agent-Logs-Url: https://github.com/thinkdj/ottabase/sessions/ae722b66-1678-4b6e-9ba2-78d05e83ba45
---
 .../pages/admin/homepage/AdminHomepagePagesPage.tsx  | 12 ++++++------
 .../homepage/AdminHomepageSectionEditorPage.tsx      |  2 +-
 .../admin/homepage/AdminHomepageSectionsPage.tsx     |  9 +++++----
 3 files changed, 12 insertions(+), 11 deletions(-)

diff --git a/apps/ottabase-template-app-tanstack/src/pages/admin/homepage/AdminHomepagePagesPage.tsx b/apps/ottabase-template-app-tanstack/src/pages/admin/homepage/AdminHomepagePagesPage.tsx
index cdda0dac4..8a87c7699 100644
--- a/apps/ottabase-template-app-tanstack/src/pages/admin/homepage/AdminHomepagePagesPage.tsx
+++ b/apps/ottabase-template-app-tanstack/src/pages/admin/homepage/AdminHomepagePagesPage.tsx
@@ -84,7 +84,7 @@ export function AdminHomepagePagesPage() {
                         <FileText className="mx-auto h-12 w-12 text-muted-foreground/50" />
                         <h3 className="mt-4 text-lg font-semibold">No pages yet</h3>
                         <p className="mt-2 text-muted-foreground">
-                            Create a page in the Blog Editor with content type &quot;Page&quot; to manage it here.
+                            Create a page in the Blog Editor with content type {'"'}Page{'"'} to manage it here.
                         </p>
                         <Button variant="outline" className="mt-4" asChild>
                             <Link to="/admin/blog/new">
@@ -102,7 +102,7 @@ export function AdminHomepagePagesPage() {
                     <CardHeader className="pb-3">
                         <CardTitle className="text-base">All Pages</CardTitle>
                         <CardDescription>
-                            Toggle &quot;Expose to Homepage&quot; to add pages to the navbar. Pages must be published to
+                            Toggle {'"'}Expose to Homepage{'"'} to add pages to the navbar. Pages must be published to
                             appear.
                         </CardDescription>
                     </CardHeader>
@@ -173,10 +173,10 @@ export function AdminHomepagePagesPage() {
                         <div className="text-sm text-muted-foreground">
                             <p className="font-medium text-foreground">How pages work</p>
                             <p className="mt-1">
-                                Pages are CMS content with type &quot;Page&quot; created in the Blog Editor. When
-                                exposed to the homepage, they appear as links in the navigation bar. Each page renders
-                                at <code className="text-xs bg-muted px-1 py-0.5 rounded">/page/slug</code> on the
-                                Next.js homepage.
+                                Pages are CMS content with type {'"'}Page{'"'} created in the Blog Editor. When exposed
+                                to the homepage, they appear as links in the navigation bar. Each page renders at{' '}
+                                <code className="text-xs bg-muted px-1 py-0.5 rounded">/page/slug</code> on the Next.js
+                                homepage.
                             </p>
                         </div>
                     </div>
diff --git a/apps/ottabase-template-app-tanstack/src/pages/admin/homepage/AdminHomepageSectionEditorPage.tsx b/apps/ottabase-template-app-tanstack/src/pages/admin/homepage/AdminHomepageSectionEditorPage.tsx
index 68afd32d8..41a14a99a 100644
--- a/apps/ottabase-template-app-tanstack/src/pages/admin/homepage/AdminHomepageSectionEditorPage.tsx
+++ b/apps/ottabase-template-app-tanstack/src/pages/admin/homepage/AdminHomepageSectionEditorPage.tsx
@@ -749,7 +749,7 @@ export function AdminHomepageSectionEditorPage() {
                 <CardContent>
                     {actions.length === 0 ? (
                         <p className="text-sm text-muted-foreground py-4 text-center">
-                            No actions yet. Add buttons like &quot;Get Started&quot; or &quot;Learn More&quot;.
+                            No actions yet. Add buttons like {'"'}Get Started{'"'} or {'"'}Learn More{'"'}.
                         </p>
                     ) : (
                         <div className="space-y-2">
diff --git a/apps/ottabase-template-app-tanstack/src/pages/admin/homepage/AdminHomepageSectionsPage.tsx b/apps/ottabase-template-app-tanstack/src/pages/admin/homepage/AdminHomepageSectionsPage.tsx
index fca728619..3dde0985d 100644
--- a/apps/ottabase-template-app-tanstack/src/pages/admin/homepage/AdminHomepageSectionsPage.tsx
+++ b/apps/ottabase-template-app-tanstack/src/pages/admin/homepage/AdminHomepageSectionsPage.tsx
@@ -387,7 +387,7 @@ export function AdminHomepageSectionsPage() {
                     <CardHeader className="pb-3">
                         <CardTitle className="text-base">Add Section</CardTitle>
                         <CardDescription>
-                            Create a section for a slot that doesn&apos;t have one yet. Each slot maps to a section on
+                            Create a section for a slot that doesn{"'"}t have one yet. Each slot maps to a section on
                             the homepage.
                         </CardDescription>
                     </CardHeader>
@@ -546,7 +546,7 @@ export function AdminHomepageSectionsPage() {
                                         className="h-7 gap-1.5 text-xs w-full justify-start"
                                     >
                                         <ChevronDown className="h-3 w-3" />
-                                        Features &amp; Actions
+                                        Features & Actions
                                     </Button>
                                 </CollapsibleTrigger>
                                 <CollapsibleContent>
@@ -567,8 +567,9 @@ export function AdminHomepageSectionsPage() {
                     <AlertDialogHeader>
                         <AlertDialogTitle>Delete Section?</AlertDialogTitle>
                         <AlertDialogDescription>
-                            This will permanently remove the &quot;{deleteDialog?.slot}&quot; section and all its
-                            features and actions. This cannot be undone.
+                            This will permanently remove the {'"'}
+                            {deleteDialog?.slot}
+                            {'"'} section and all its features and actions. This cannot be undone.
                         </AlertDialogDescription>
                     </AlertDialogHeader>
                     <AlertDialogFooter>

From f1d3afc233d0b019dcffeef99803f95fed6c2028 Mon Sep 17 00:00:00 2001
From: "copilot-swe-agent[bot]" <198982749+Copilot@users.noreply.github.com>
Date: Tue, 31 Mar 2026 05:57:25 +0000
Subject: [PATCH 12/19] =?UTF-8?q?feat:=20full=20runtime=20homepage=20integ?=
 =?UTF-8?q?ration=20=E2=80=94=20Zod-validated=20API=20pipeline,=20DB-drive?=
 =?UTF-8?q?n=20page=20content,=20variant=20config=20from=20DB,=20homepage?=
 =?UTF-8?q?=20seed=20endpoint,=20provider=20theming=20integration?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Agent-Logs-Url: https://github.com/thinkdj/ottabase/sessions/fa1817dd-2a0e-4aa2-b880-b83c22af8a9a
---
 .../.env.example                              |   5 +-
 .../__tests__/components.test.tsx             |  70 +++++-
 .../app/(site)/page.tsx                       |  98 +++++++-
 .../app/layout-shell.tsx                      |   5 +-
 .../app/layout.tsx                            |  27 +-
 .../app/providers.tsx                         |  36 ++-
 .../components/variants/cta/types.ts          |   2 +
 .../components/variants/features/types.ts     |   6 +
 .../components/variants/hero/types.ts         |   2 +
 .../lib/api.ts                                |   9 +-
 .../lib/get-homepage-data.ts                  | 101 ++++++++
 .../lib/homepage-config-context.tsx           |  70 +++++-
 .../lib/homepage-data-context.tsx             |  32 +++
 .../package.json                              |   3 +-
 .../worker/bootstrap/routes.ts                |  15 ++
 .../worker/routes/homepage.ts                 | 232 ++++++++++++++++++
 .../worker/routes/router.ts                   |   7 +-
 pnpm-lock.yaml                                |   3 +
 18 files changed, 683 insertions(+), 40 deletions(-)
 create mode 100644 apps/ottabase-template-app-nextjs-homepage/lib/get-homepage-data.ts
 create mode 100644 apps/ottabase-template-app-nextjs-homepage/lib/homepage-data-context.tsx

diff --git a/apps/ottabase-template-app-nextjs-homepage/.env.example b/apps/ottabase-template-app-nextjs-homepage/.env.example
index 82309a117..0bd7489fe 100644
--- a/apps/ottabase-template-app-nextjs-homepage/.env.example
+++ b/apps/ottabase-template-app-nextjs-homepage/.env.example
@@ -51,8 +51,9 @@ NODE_ENV="development"
 # Set to "true" to show on production, or leave unset to auto-show in dev only
 # NEXT_PUBLIC_SHOW_CONFIG_PANEL="true"
 
-# Ottabase Worker API URL (for CMS pages, exposed pages)
-# NEXT_PUBLIC_API_URL="http://localhost:3004"
+# Ottabase Worker API URL (for CMS pages, homepage data, exposed pages)
+# Required for runtime data integration — set to your TanStack worker URL
+NEXT_PUBLIC_API_URL="http://localhost:3004"
 
 # ============================================================
 # Database Configuration (Prisma + D1)
diff --git a/apps/ottabase-template-app-nextjs-homepage/__tests__/components.test.tsx b/apps/ottabase-template-app-nextjs-homepage/__tests__/components.test.tsx
index 343e39189..af5a450cc 100644
--- a/apps/ottabase-template-app-nextjs-homepage/__tests__/components.test.tsx
+++ b/apps/ottabase-template-app-nextjs-homepage/__tests__/components.test.tsx
@@ -372,7 +372,14 @@ describe('Homepage API types', () => {
         const result = await fetchHomepageData();
         expect(result).toEqual({
             sections: [],
-            display: { variantBySlot: null, themePreset: null, fallbackThemePresetId: null },
+            display: {
+                variantBySlot: null,
+                themePreset: null,
+                fallbackThemePresetId: null,
+                customCss: null,
+                seoTitle: null,
+                seoDescription: null,
+            },
             exposedPages: [],
         });
     });
@@ -461,3 +468,64 @@ describe('Homepage API types', () => {
         expect(section.actions[0].icon).toBe('ArrowRight');
     });
 });
+
+describe('getHomepageData (Zod validation)', () => {
+    it('returns validated fallback when API_URL is empty', async () => {
+        const { getHomepageData } = await import('../lib/get-homepage-data');
+        const result = await getHomepageData();
+        expect(result.sections).toEqual([]);
+        expect(result.display.variantBySlot).toBeNull();
+        expect(result.exposedPages).toEqual([]);
+    });
+
+    it('HomepageDataSchema validates a correct payload', async () => {
+        const { HomepageDataSchema } = await import('../lib/get-homepage-data');
+        const payload = {
+            sections: [
+                {
+                    id: 'test-1',
+                    slot: 'hero',
+                    title: 'Test',
+                    subtitle: null,
+                    body: null,
+                    githubUrl: null,
+                    icon: 'Sparkles',
+                    enabled: true,
+                    cssClasses: null,
+                    metadata: null,
+                    sortOrder: 0,
+                    features: [],
+                    actions: [{ label: 'Go', href: '/go', variant: 'default', icon: null, external: false }],
+                },
+            ],
+            display: {
+                variantBySlot: { hero: 'centered' },
+                themePreset: 'neo',
+                fallbackThemePresetId: null,
+            },
+            exposedPages: [{ slug: 'about', title: 'About' }],
+        };
+        const result = HomepageDataSchema.safeParse(payload);
+        expect(result.success).toBe(true);
+        if (result.success) {
+            expect(result.data.sections).toHaveLength(1);
+            expect(result.data.sections[0].icon).toBe('Sparkles');
+            expect(result.data.display.themePreset).toBe('neo');
+        }
+    });
+
+    it('HomepageDataSchema rejects invalid payload shape', async () => {
+        const { HomepageDataSchema } = await import('../lib/get-homepage-data');
+        const result = HomepageDataSchema.safeParse({ sections: 'not-an-array' });
+        expect(result.success).toBe(false);
+    });
+});
+
+describe('HomepageConfigProvider with API variants', () => {
+    it('merges API variant-by-slot into default config', async () => {
+        const { SLOT_REGISTRY } = await import('../lib/homepage-config');
+        // Verify the slot registry has valid variants for testing
+        expect(SLOT_REGISTRY.hero.variants.some((v) => v.id === 'split')).toBe(true);
+        expect(SLOT_REGISTRY.features.variants.some((v) => v.id === 'cards')).toBe(true);
+    });
+});
diff --git a/apps/ottabase-template-app-nextjs-homepage/app/(site)/page.tsx b/apps/ottabase-template-app-nextjs-homepage/app/(site)/page.tsx
index e772ba669..2b1de00bc 100644
--- a/apps/ottabase-template-app-nextjs-homepage/app/(site)/page.tsx
+++ b/apps/ottabase-template-app-nextjs-homepage/app/(site)/page.tsx
@@ -2,13 +2,15 @@
 
 import { Github, Palette, Rocket } from 'lucide-react';
 import { SlotRenderer } from '../../components/SlotRenderer';
+import type { HomepageDataPayload } from '../../lib/api';
+import { useHomepageData } from '../../lib/homepage-data-context';
 
 /**
- * Homepage content data — single source of truth.
- * Each section defines its data once; the active variant determines how it renders.
+ * Fallback homepage data — used when the API is unavailable or returns no sections.
+ * These are the built-in template defaults that ensure the homepage always renders.
  */
 
-const HERO_DATA = {
+const FALLBACK_HERO = {
     title: (
         <>
             <span className="text-primary">Ottabase</span>{' '}
@@ -45,7 +47,7 @@ const HERO_DATA = {
     ],
 };
 
-const FEATURES_DATA = {
+const FALLBACK_FEATURES = {
     features: [
         { title: 'Cloudflare Workers', description: 'Edge-deployed via OpenNext. No origin server needed.' },
         { title: 'Brand Engine', description: '8 theme presets with live switching and dark mode.' },
@@ -54,7 +56,7 @@ const FEATURES_DATA = {
     ],
 };
 
-const CTA_DATA = {
+const FALLBACK_CTA = {
     title: 'Ready to Ship?',
     description: 'Clone the template, customize the brand, and deploy to Cloudflare Workers in minutes.',
     actions: [
@@ -71,12 +73,92 @@ const CTA_DATA = {
     ],
 };
 
+/**
+ * Map DB sections to slot-specific data contracts.
+ * Filters to enabled sections only and transforms to the shapes expected by SlotRenderer.
+ */
+function buildPageSlotData(sections: HomepageDataPayload['sections']) {
+    const result: {
+        hero?: Record<string, unknown>;
+        features?: Record<string, unknown>;
+        cta?: Record<string, unknown>;
+        about?: Record<string, unknown>;
+    } = {};
+
+    for (const section of sections) {
+        if (section.enabled === false) continue;
+
+        const slot = section.slot;
+        if (slot === 'hero') {
+            result.hero = {
+                title: section.title ?? '',
+                subtitle: section.subtitle ?? undefined,
+                body: section.body ?? undefined,
+                actions:
+                    section.actions.length > 0
+                        ? section.actions.map((a) => ({
+                              label: a.label,
+                              href: a.href,
+                              variant: (a.variant as 'default' | 'secondary' | 'outline' | 'ghost') ?? 'default',
+                              icon: a.icon ?? undefined,
+                              external: a.external,
+                          }))
+                        : undefined,
+            };
+        } else if (slot === 'features') {
+            result.features = {
+                title: section.title ?? undefined,
+                features: section.features.map((f) => ({
+                    title: f.title,
+                    description: f.description,
+                    icon: f.icon ?? undefined,
+                    imageUrl: f.imageUrl ?? undefined,
+                    href: f.href ?? undefined,
+                })),
+            };
+        } else if (slot === 'cta') {
+            result.cta = {
+                title: section.title ?? '',
+                description: section.subtitle ?? undefined,
+                actions:
+                    section.actions.length > 0
+                        ? section.actions.map((a) => ({
+                              label: a.label,
+                              href: a.href,
+                              variant: (a.variant as 'default' | 'secondary' | 'outline' | 'ghost') ?? 'default',
+                              icon: a.icon ?? undefined,
+                              external: a.external,
+                          }))
+                        : [],
+            };
+        } else if (slot === 'about') {
+            result.about = {
+                title: section.title ?? undefined,
+                description: section.subtitle ?? undefined,
+                githubUrl: section.githubUrl ?? undefined,
+            };
+        }
+    }
+
+    return result;
+}
+
 export default function HomePage() {
+    const homepageData = useHomepageData();
+    const sections = homepageData?.sections ?? [];
+
+    // Build slot data from DB sections, with fallbacks for missing slots
+    const dbSlots = buildPageSlotData(sections);
+    const heroData = dbSlots.hero ?? FALLBACK_HERO;
+    const featuresData = dbSlots.features ?? FALLBACK_FEATURES;
+    const ctaData = dbSlots.cta ?? FALLBACK_CTA;
+
     return (
         <div className="flex flex-col items-center">
-            <SlotRenderer slot="hero" data={HERO_DATA} />
-            <SlotRenderer slot="features" data={FEATURES_DATA} />
-            <SlotRenderer slot="cta" data={CTA_DATA} />
+            <SlotRenderer slot="hero" data={heroData as any} />
+            <SlotRenderer slot="features" data={featuresData as any} />
+            {dbSlots.about && <SlotRenderer slot="about" data={dbSlots.about as any} />}
+            <SlotRenderer slot="cta" data={ctaData as any} />
         </div>
     );
 }
diff --git a/apps/ottabase-template-app-nextjs-homepage/app/layout-shell.tsx b/apps/ottabase-template-app-nextjs-homepage/app/layout-shell.tsx
index f3d7d5a5c..4afacbe2e 100644
--- a/apps/ottabase-template-app-nextjs-homepage/app/layout-shell.tsx
+++ b/apps/ottabase-template-app-nextjs-homepage/app/layout-shell.tsx
@@ -3,6 +3,7 @@
 import { ConfigPanel } from '../components/ConfigPanel';
 import { SlotRenderer } from '../components/SlotRenderer';
 import type { HomepageDataPayload } from '../lib/api';
+import { HomepageDataProvider } from '../lib/homepage-data-context';
 import type { NavLink } from '../components/variants/navbar/types';
 
 const GITHUB_URL = 'https://github.com/thinkdj/ottabase';
@@ -136,11 +137,11 @@ export function LayoutShell({ children, exposedPages = [], homepageData }: Layou
     const footerData = dbSlotData.footer ? { ...FOOTER_DATA, ...dbSlotData.footer } : FOOTER_DATA;
 
     return (
-        <>
+        <HomepageDataProvider data={homepageData ?? null}>
             <SlotRenderer slot="navbar" data={navbarData} />
             <main className="flex-1">{children}</main>
             <SlotRenderer slot="footer" data={footerData} />
             <ConfigPanel />
-        </>
+        </HomepageDataProvider>
     );
 }
diff --git a/apps/ottabase-template-app-nextjs-homepage/app/layout.tsx b/apps/ottabase-template-app-nextjs-homepage/app/layout.tsx
index 7c01d00a5..a95ccef5e 100644
--- a/apps/ottabase-template-app-nextjs-homepage/app/layout.tsx
+++ b/apps/ottabase-template-app-nextjs-homepage/app/layout.tsx
@@ -1,6 +1,6 @@
 import { buildCriticalCSS } from '@ottabase/brand-engine';
 import type { Metadata } from 'next';
-import { fetchHomepageData } from '../lib/api';
+import { getHomepageData } from '../lib/get-homepage-data';
 import { generateBrandConfig } from '../lib/brand-server';
 import './globals.css';
 import { LayoutShell } from './layout-shell';
@@ -23,21 +23,40 @@ export default async function RootLayout({ children }: { children: React.ReactNo
     // Generate critical CSS for SSR (prevents FOUC)
     const criticalCSS = buildCriticalCSS(theme);
 
-    // Fetch full homepage data (sections, display settings, exposed pages) from the worker API
-    const homepageData = await fetchHomepageData();
+    // Fetch and validate full homepage data from the worker API (Zod-validated)
+    const homepageData = await getHomepageData();
+
+    // Extract display settings for Providers
+    const initialHomepageConfig = homepageData.display.variantBySlot ?? null;
+    const themePresetId = homepageData.display.themePreset ?? null;
+
+    // Apply SEO overrides from DB if available
+    const seoTitle = homepageData.display.seoTitle;
+    const seoDescription = homepageData.display.seoDescription;
 
     return (
         <html lang="en" suppressHydrationWarning>
             <head>
+                {/* SEO overrides from admin display settings */}
+                {seoTitle && <title>{seoTitle}</title>}
+                {seoDescription && <meta name="description" content={seoDescription} />}
                 {/* Inject critical CSS for theme variables */}
                 <style id="brand-critical" dangerouslySetInnerHTML={{ __html: criticalCSS }} />
+                {/* Inject custom CSS from display settings */}
+                {homepageData.display.customCss && (
+                    <style id="homepage-custom" dangerouslySetInnerHTML={{ __html: homepageData.display.customCss }} />
+                )}
                 {/* Load fonts - only if URLs are defined */}
                 {theme.typography.heading.url && <link rel="stylesheet" href={theme.typography.heading.url} />}
                 {theme.typography.body.url && <link rel="stylesheet" href={theme.typography.body.url} />}
                 {theme.typography.handwriting.url && <link rel="stylesheet" href={theme.typography.handwriting.url} />}
             </head>
             <body className="flex min-h-screen flex-col bg-background text-foreground">
-                <Providers initialBrandConfig={brandConfig}>
+                <Providers
+                    initialBrandConfig={brandConfig}
+                    initialHomepageConfig={initialHomepageConfig}
+                    themePresetId={themePresetId}
+                >
                     <LayoutShell exposedPages={homepageData.exposedPages} homepageData={homepageData}>
                         {children}
                     </LayoutShell>
diff --git a/apps/ottabase-template-app-nextjs-homepage/app/providers.tsx b/apps/ottabase-template-app-nextjs-homepage/app/providers.tsx
index 372b8a5b8..920c911bc 100644
--- a/apps/ottabase-template-app-nextjs-homepage/app/providers.tsx
+++ b/apps/ottabase-template-app-nextjs-homepage/app/providers.tsx
@@ -9,26 +9,29 @@ import { useEffect } from 'react';
 import { THEME_STORAGE_KEY } from '../components/ThemePresetSwitcher';
 import { HomepageConfigProvider } from '../lib/homepage-config-context';
 
-export function Providers({
-    children,
-    initialBrandConfig,
-}: {
+export interface ProvidersProps {
     children: React.ReactNode;
     initialBrandConfig: FullBrandConfig;
-}) {
+    /** DB-driven variant-by-slot from GET /api/homepage/data display settings */
+    initialHomepageConfig?: Record<string, string> | null;
+    /** DB-driven theme preset ID (e.g. 'neo', 'warm') */
+    themePresetId?: string | null;
+}
+
+export function Providers({ children, initialBrandConfig, initialHomepageConfig, themePresetId }: ProvidersProps) {
     // Handle theme switching for dark/light mode + restore saved preset
     useEffect(() => {
         if (typeof document === 'undefined') return;
 
-        // Check for a saved preset in localStorage
+        // Priority: localStorage saved preset > DB themePresetId > SSR brand config
         const savedPreset = localStorage.getItem(THEME_STORAGE_KEY);
 
         const applyCorrectTheme = () => {
             const isDark = document.documentElement.classList.contains('dark');
             const mode = isDark ? 'dark' : 'light';
 
+            // Try localStorage preset first (user's explicit choice)
             if (savedPreset) {
-                // Apply the saved preset instead of the SSR default
                 registerBuiltInThemes();
                 const base = getThemeByName(savedPreset);
                 if (base) {
@@ -38,6 +41,17 @@ export function Providers({
                 }
             }
 
+            // Try DB-driven theme preset (admin-configured)
+            if (themePresetId) {
+                registerBuiltInThemes();
+                const base = getThemeByName(themePresetId);
+                if (base) {
+                    const resolved = resolveTheme({ base, tenantOverrides: {}, mode });
+                    applyBrandTheme(resolved);
+                    return;
+                }
+            }
+
             // Fall back to the SSR brand config
             const brandKit = (initialBrandConfig as any).brandKitsMap?.default;
             if (brandKit) {
@@ -46,10 +60,8 @@ export function Providers({
             }
         };
 
-        // Apply correct theme on mount
         applyCorrectTheme();
 
-        // Watch for dark mode class changes
         const observer = new MutationObserver((mutations) => {
             for (const mutation of mutations) {
                 if (mutation.type === 'attributes' && mutation.attributeName === 'class') {
@@ -64,13 +76,15 @@ export function Providers({
         });
 
         return () => observer.disconnect();
-    }, [initialBrandConfig]);
+    }, [initialBrandConfig, themePresetId]);
 
     return (
         <ThemeProvider attribute="class" defaultTheme="system" enableSystem>
             <BrandProvider initialConfig={initialBrandConfig}>
                 <ShadcnProviders enableThemeProvider={false} enableToaster>
-                    <HomepageConfigProvider>{children}</HomepageConfigProvider>
+                    <HomepageConfigProvider initialVariantBySlot={initialHomepageConfig}>
+                        {children}
+                    </HomepageConfigProvider>
                 </ShadcnProviders>
             </BrandProvider>
         </ThemeProvider>
diff --git a/apps/ottabase-template-app-nextjs-homepage/components/variants/cta/types.ts b/apps/ottabase-template-app-nextjs-homepage/components/variants/cta/types.ts
index a0a7b9d89..ece9bf813 100644
--- a/apps/ottabase-template-app-nextjs-homepage/components/variants/cta/types.ts
+++ b/apps/ottabase-template-app-nextjs-homepage/components/variants/cta/types.ts
@@ -5,6 +5,8 @@ export type CTAAction = {
     href: string;
     label: ReactNode;
     variant?: 'default' | 'secondary' | 'outline' | 'ghost';
+    /** Lucide icon name (e.g. 'Rocket', 'ArrowRight') */
+    icon?: string;
     external?: boolean;
 };
 
diff --git a/apps/ottabase-template-app-nextjs-homepage/components/variants/features/types.ts b/apps/ottabase-template-app-nextjs-homepage/components/variants/features/types.ts
index fc9520aaa..d341b329d 100644
--- a/apps/ottabase-template-app-nextjs-homepage/components/variants/features/types.ts
+++ b/apps/ottabase-template-app-nextjs-homepage/components/variants/features/types.ts
@@ -2,6 +2,12 @@
 export type FeatureItemData = {
     title: string;
     description: string;
+    /** Lucide icon name (e.g. 'Zap', 'Shield') — rendered by variants that support icons */
+    icon?: string;
+    /** Image URL for visual feature cards */
+    imageUrl?: string;
+    /** Link target for clickable feature items */
+    href?: string;
 };
 
 export type FeaturesData = {
diff --git a/apps/ottabase-template-app-nextjs-homepage/components/variants/hero/types.ts b/apps/ottabase-template-app-nextjs-homepage/components/variants/hero/types.ts
index 426af291a..0c6366bfa 100644
--- a/apps/ottabase-template-app-nextjs-homepage/components/variants/hero/types.ts
+++ b/apps/ottabase-template-app-nextjs-homepage/components/variants/hero/types.ts
@@ -5,6 +5,8 @@ export type HeroAction = {
     href: string;
     label: ReactNode;
     variant?: 'default' | 'secondary' | 'outline' | 'ghost';
+    /** Lucide icon name (e.g. 'Rocket', 'Github') */
+    icon?: string;
     external?: boolean;
 };
 
diff --git a/apps/ottabase-template-app-nextjs-homepage/lib/api.ts b/apps/ottabase-template-app-nextjs-homepage/lib/api.ts
index 1ccb2477a..6047376e3 100644
--- a/apps/ottabase-template-app-nextjs-homepage/lib/api.ts
+++ b/apps/ottabase-template-app-nextjs-homepage/lib/api.ts
@@ -121,7 +121,14 @@ export async function fetchPageBySlug(slug: string): Promise<PageData | null> {
 export async function fetchHomepageData(): Promise<HomepageDataPayload> {
     const fallback: HomepageDataPayload = {
         sections: [],
-        display: { variantBySlot: null, themePreset: null, fallbackThemePresetId: null },
+        display: {
+            variantBySlot: null,
+            themePreset: null,
+            fallbackThemePresetId: null,
+            customCss: null,
+            seoTitle: null,
+            seoDescription: null,
+        },
         exposedPages: [],
     };
     if (!API_URL) return fallback;
diff --git a/apps/ottabase-template-app-nextjs-homepage/lib/get-homepage-data.ts b/apps/ottabase-template-app-nextjs-homepage/lib/get-homepage-data.ts
new file mode 100644
index 000000000..89643277d
--- /dev/null
+++ b/apps/ottabase-template-app-nextjs-homepage/lib/get-homepage-data.ts
@@ -0,0 +1,101 @@
+/**
+ * Homepage data fetcher with Zod validation.
+ *
+ * Wraps the raw `fetchHomepageData()` API call with schema validation
+ * and provides typed, validated payloads for the Next.js consumer.
+ * Falls back to safe defaults when the API is unavailable or returns invalid data.
+ */
+
+import { z } from 'zod';
+import type { HomepageDataPayload } from './api';
+import { fetchHomepageData } from './api';
+
+// ── Zod schemas for API payload validation ──────────────────────────────────
+
+const ExposedPageSchema = z.object({
+    slug: z.string(),
+    title: z.string(),
+});
+
+const FeatureSchema = z.object({
+    title: z.string(),
+    description: z.string(),
+    icon: z.string().nullable().optional(),
+    imageUrl: z.string().nullable().optional(),
+    href: z.string().nullable().optional(),
+});
+
+const ActionSchema = z.object({
+    label: z.string(),
+    href: z.string(),
+    variant: z.string().nullable().optional(),
+    icon: z.string().nullable().optional(),
+    external: z.boolean().optional().default(false),
+});
+
+const SectionSchema = z.object({
+    id: z.string(),
+    slot: z.string(),
+    title: z.string().nullable(),
+    subtitle: z.string().nullable(),
+    body: z.string().nullable(),
+    githubUrl: z.string().nullable(),
+    icon: z.string().nullable(),
+    enabled: z.boolean().default(true),
+    cssClasses: z.string().nullable(),
+    metadata: z.record(z.unknown()).nullable(),
+    sortOrder: z.number().default(0),
+    features: z.array(FeatureSchema).default([]),
+    actions: z.array(ActionSchema).default([]),
+});
+
+const DisplaySchema = z.object({
+    variantBySlot: z.record(z.string()).nullable(),
+    themePreset: z.string().nullable(),
+    fallbackThemePresetId: z.string().nullable().optional(),
+    customCss: z.string().nullable().optional(),
+    seoTitle: z.string().nullable().optional(),
+    seoDescription: z.string().nullable().optional(),
+});
+
+export const HomepageDataSchema = z.object({
+    sections: z.array(SectionSchema).default([]),
+    display: DisplaySchema,
+    exposedPages: z.array(ExposedPageSchema).default([]),
+});
+
+export type ValidatedHomepageData = z.infer<typeof HomepageDataSchema>;
+
+// ── Safe defaults ───────────────────────────────────────────────────────────
+
+const EMPTY_PAYLOAD: HomepageDataPayload = {
+    sections: [],
+    display: {
+        variantBySlot: null,
+        themePreset: null,
+        fallbackThemePresetId: null,
+        customCss: null,
+        seoTitle: null,
+        seoDescription: null,
+    },
+    exposedPages: [],
+};
+
+/**
+ * Fetch and validate homepage data from the worker API.
+ * Returns validated data or safe defaults on failure.
+ */
+export async function getHomepageData(): Promise<ValidatedHomepageData> {
+    try {
+        const raw = await fetchHomepageData();
+        const result = HomepageDataSchema.safeParse(raw);
+        if (result.success) {
+            return result.data;
+        }
+        // Log validation errors but don't hard-fail
+        console.warn('[get-homepage-data] Validation failed:', result.error.issues);
+        return HomepageDataSchema.parse(EMPTY_PAYLOAD);
+    } catch {
+        return HomepageDataSchema.parse(EMPTY_PAYLOAD);
+    }
+}
diff --git a/apps/ottabase-template-app-nextjs-homepage/lib/homepage-config-context.tsx b/apps/ottabase-template-app-nextjs-homepage/lib/homepage-config-context.tsx
index fcf4090db..b545cc84f 100644
--- a/apps/ottabase-template-app-nextjs-homepage/lib/homepage-config-context.tsx
+++ b/apps/ottabase-template-app-nextjs-homepage/lib/homepage-config-context.tsx
@@ -6,11 +6,16 @@
  * Wraps `loadConfig` / `saveConfig` in React state so every consumer
  * re-renders when a slot variant is changed — enabling live preview on the
  * config page and instant updates on the homepage.
+ *
+ * Supports API-driven initial config: when `initialVariantBySlot` is provided
+ * (from GET /api/homepage/data display settings), it overrides the default
+ * config for any slot that has a valid variant set in the DB. localStorage
+ * takes final precedence (user's local customization wins).
  */
 
 import { createContext, useCallback, useContext, useEffect, useState } from 'react';
 import type { HomepageConfig, SlotName } from './homepage-config';
-import { getDefaultConfig, loadConfig, saveConfig } from './homepage-config';
+import { getDefaultConfig, loadConfig, saveConfig, SLOT_NAMES, SLOT_REGISTRY } from './homepage-config';
 
 type HomepageConfigContextValue = {
     config: HomepageConfig;
@@ -20,12 +25,58 @@ type HomepageConfigContextValue = {
 
 const HomepageConfigContext = createContext<HomepageConfigContextValue | null>(null);
 
-export function HomepageConfigProvider({ children }: { children: React.ReactNode }) {
-    const [config, setConfig] = useState<HomepageConfig>(getDefaultConfig);
+export interface HomepageConfigProviderProps {
+    children: React.ReactNode;
+    /** API-driven variant-by-slot from HomepageDisplaySettings (DB source of truth). */
+    initialVariantBySlot?: Record<string, string> | null;
+}
+
+/**
+ * Merge priority: localStorage > API variantBySlot > built-in defaults.
+ * This ensures users can override via the config panel, DB settings provide
+ * a baseline, and defaults are always available.
+ */
+function mergeConfig(apiVariants: Record<string, string> | null | undefined): HomepageConfig {
+    const defaults = getDefaultConfig();
+    const merged = { ...defaults };
+
+    // Layer 1: Apply API-driven variants (if valid)
+    if (apiVariants && typeof apiVariants === 'object') {
+        for (const slot of SLOT_NAMES) {
+            const value = apiVariants[slot];
+            if (typeof value === 'string') {
+                const validIds = SLOT_REGISTRY[slot].variants.map((v) => v.id);
+                if (validIds.includes(value)) {
+                    merged[slot] = value;
+                }
+            }
+        }
+    }
+
+    return merged;
+}
 
-    // Hydrate from localStorage on mount
+export function HomepageConfigProvider({ children, initialVariantBySlot }: HomepageConfigProviderProps) {
+    // Start with API-merged config (or defaults)
+    const [config, setConfig] = useState<HomepageConfig>(() => mergeConfig(initialVariantBySlot));
+
+    // Layer 2: Hydrate from localStorage on mount (takes final precedence)
     useEffect(() => {
-        setConfig(loadConfig());
+        const localConfig = loadConfig();
+        // Merge: localStorage overrides API values where localStorage has valid entries
+        setConfig((current) => {
+            const final = { ...current };
+            for (const slot of SLOT_NAMES) {
+                const localValue = localConfig[slot];
+                const defaultValue = getDefaultConfig()[slot];
+                // Only use localStorage value if it differs from the default
+                // (indicating the user explicitly set it)
+                if (localValue !== defaultValue) {
+                    final[slot] = localValue;
+                }
+            }
+            return final;
+        });
     }, []);
 
     const setVariant = useCallback((slot: SlotName, variantId: string) => {
@@ -37,10 +88,11 @@ export function HomepageConfigProvider({ children }: { children: React.ReactNode
     }, []);
 
     const resetConfig = useCallback(() => {
-        const defaults = getDefaultConfig();
-        setConfig(defaults);
-        saveConfig(defaults);
-    }, []);
+        // Reset to API-merged config (not just defaults)
+        const base = mergeConfig(initialVariantBySlot);
+        setConfig(base);
+        saveConfig(base);
+    }, [initialVariantBySlot]);
 
     return (
         <HomepageConfigContext.Provider value={{ config, setVariant, resetConfig }}>
diff --git a/apps/ottabase-template-app-nextjs-homepage/lib/homepage-data-context.tsx b/apps/ottabase-template-app-nextjs-homepage/lib/homepage-data-context.tsx
new file mode 100644
index 000000000..778afaa93
--- /dev/null
+++ b/apps/ottabase-template-app-nextjs-homepage/lib/homepage-data-context.tsx
@@ -0,0 +1,32 @@
+'use client';
+
+/**
+ * React context for passing homepage API data from LayoutShell to page components.
+ *
+ * This bridges the server-fetched homepage data (from layout.tsx → LayoutShell)
+ * down to client components like (site)/page.tsx, without prop drilling through
+ * Next.js route boundaries.
+ */
+
+import { createContext, useContext } from 'react';
+import type { HomepageDataPayload } from './api';
+
+const HomepageDataContext = createContext<HomepageDataPayload | null>(null);
+
+export function HomepageDataProvider({
+    children,
+    data,
+}: {
+    children: React.ReactNode;
+    data: HomepageDataPayload | null;
+}) {
+    return <HomepageDataContext.Provider value={data}>{children}</HomepageDataContext.Provider>;
+}
+
+/**
+ * Access the homepage data payload from context.
+ * Returns null when data is unavailable (API not configured or failed).
+ */
+export function useHomepageData(): HomepageDataPayload | null {
+    return useContext(HomepageDataContext);
+}
diff --git a/apps/ottabase-template-app-nextjs-homepage/package.json b/apps/ottabase-template-app-nextjs-homepage/package.json
index ea453c28f..2f055983d 100644
--- a/apps/ottabase-template-app-nextjs-homepage/package.json
+++ b/apps/ottabase-template-app-nextjs-homepage/package.json
@@ -35,7 +35,8 @@
         "react": "catalog:",
         "react-dom": "catalog:",
         "sonner": "catalog:",
-        "tailwind-merge": "catalog:"
+        "tailwind-merge": "catalog:",
+        "zod": "catalog:"
     },
     "devDependencies": {
         "@cloudflare/workers-types": "catalog:",
diff --git a/apps/ottabase-template-app-tanstack/worker/bootstrap/routes.ts b/apps/ottabase-template-app-tanstack/worker/bootstrap/routes.ts
index 5fbd40a9b..283d31a9c 100644
--- a/apps/ottabase-template-app-tanstack/worker/bootstrap/routes.ts
+++ b/apps/ottabase-template-app-tanstack/worker/bootstrap/routes.ts
@@ -419,9 +419,24 @@ async function handleSeed(context: BootstrapContext): Promise<Response> {
         const allRolesResult = await env.OBCF_D1.prepare('SELECT name FROM roles').all();
         const existingRoles = (allRolesResult.results || []).map((r: any) => r.name as string);
 
+        // Seed homepage demo content (idempotent — skips if sections exist)
+        let homepageSeeded = false;
+        try {
+            const { handleHomepageSeed } = await import('../routes/homepage');
+            const seedUrl = new URL(request.url);
+            seedUrl.pathname = '/api/homepage/seed';
+            const seedReq = new Request(seedUrl.toString(), { method: 'POST' });
+            const seedRes = await handleHomepageSeed({ request: seedReq, env, url: seedUrl });
+            const seedData = (await seedRes.json()) as { seeded?: boolean };
+            homepageSeeded = seedData.seeded === true;
+        } catch (err: any) {
+            console.error('[bootstrap/seed] Homepage seed failed (non-fatal):', err.message);
+        }
+
         return jsonResp({
             success: true,
             roles: { created: roleNames, existing: existingRoles, normalized: normalizedRoles },
+            homepage: { seeded: homepageSeeded },
             timestamp: Date.now(),
         });
     } catch (error: any) {
diff --git a/apps/ottabase-template-app-tanstack/worker/routes/homepage.ts b/apps/ottabase-template-app-tanstack/worker/routes/homepage.ts
index 51e79043a..d38d415e3 100644
--- a/apps/ottabase-template-app-tanstack/worker/routes/homepage.ts
+++ b/apps/ottabase-template-app-tanstack/worker/routes/homepage.ts
@@ -232,3 +232,235 @@ export async function handleHomepageData(context: HomepageRouteContext): Promise
     const payload: HomepagePublicPayload = { sections, display, exposedPages };
     return jsonResponse(payload);
 }
+
+// ── Default demo content for seeding ────────────────────────────────────────
+
+const SEED_SECTIONS = [
+    {
+        slot: 'navbar',
+        title: 'Ottabase',
+        subtitle: null,
+        body: null,
+        githubUrl: 'https://github.com/thinkdj/ottabase',
+        icon: 'Navigation',
+        enabled: true,
+        sortOrder: 0,
+    },
+    {
+        slot: 'hero',
+        title: 'Ottabase Homepage',
+        subtitle: 'Ship a themed, edge-deployed homepage on Cloudflare Workers in minutes.',
+        body: null,
+        githubUrl: null,
+        icon: 'Sparkles',
+        enabled: true,
+        sortOrder: 1,
+    },
+    {
+        slot: 'features',
+        title: 'Why Ottabase?',
+        subtitle: null,
+        body: null,
+        githubUrl: null,
+        icon: 'Grid3X3',
+        enabled: true,
+        sortOrder: 2,
+    },
+    {
+        slot: 'cta',
+        title: 'Ready to Ship?',
+        subtitle: 'Clone the template, customize the brand, and deploy to Cloudflare Workers in minutes.',
+        body: null,
+        githubUrl: null,
+        icon: 'Megaphone',
+        enabled: true,
+        sortOrder: 3,
+    },
+    {
+        slot: 'about',
+        title: 'About Ottabase',
+        subtitle: 'A modern full-stack framework for edge-first applications.',
+        body: null,
+        githubUrl: 'https://github.com/thinkdj/ottabase',
+        icon: 'FileText',
+        enabled: true,
+        sortOrder: 4,
+    },
+    {
+        slot: 'footer',
+        title: 'Ottabase',
+        subtitle: 'Built with Next.js & Cloudflare Workers',
+        body: null,
+        githubUrl: null,
+        icon: 'Rows3',
+        enabled: true,
+        sortOrder: 5,
+    },
+];
+
+const SEED_FEATURES = [
+    { title: 'Cloudflare Workers', description: 'Edge-deployed via OpenNext. No origin server needed.', icon: 'Globe' },
+    { title: 'Brand Engine', description: '8 theme presets with live switching and dark mode.', icon: 'Palette' },
+    { title: 'Next.js 16', description: 'App Router, RSC, and streaming out of the box.', icon: 'Zap' },
+    {
+        title: 'TypeScript',
+        description: 'End-to-end type safety across client and server.',
+        icon: 'Shield',
+    },
+    {
+        title: 'OttaORM',
+        description: 'Fat model system with auto-migrations, relationships, and CRUD.',
+        icon: 'Database',
+    },
+    {
+        title: 'Admin Dashboard',
+        description: 'Full admin UI for content, users, and settings management.',
+        icon: 'LayoutDashboard',
+    },
+];
+
+const SEED_HERO_ACTIONS = [
+    { label: 'About', href: '/about', variant: 'default', icon: null, external: false, sortOrder: 0 },
+    { label: 'Theme Demo', href: '/theme-demo', variant: 'secondary', icon: 'Palette', external: false, sortOrder: 1 },
+    {
+        label: 'GitHub',
+        href: 'https://github.com/thinkdj/ottabase',
+        variant: 'outline',
+        icon: 'Github',
+        external: true,
+        sortOrder: 2,
+    },
+];
+
+const SEED_CTA_ACTIONS = [
+    {
+        label: 'Get Started',
+        href: 'https://github.com/thinkdj/ottabase',
+        variant: 'default',
+        icon: 'Rocket',
+        external: true,
+        sortOrder: 0,
+    },
+    { label: 'Explore Themes', href: '/theme-demo', variant: 'outline', icon: null, external: false, sortOrder: 1 },
+];
+
+const SEED_DISPLAY = {
+    variantBySlotJson: {
+        navbar: 'default',
+        hero: 'centered',
+        features: 'grid',
+        cta: 'default',
+        footer: 'default',
+        about: 'default',
+    },
+    themePreset: 'neo',
+};
+
+/**
+ * POST /api/homepage/seed
+ *
+ * Seeds default homepage content (sections, features, actions, display settings).
+ * Skips seeding if any sections already exist. Idempotent.
+ */
+export async function handleHomepageSeed(context: HomepageRouteContext): Promise<Response> {
+    const { env, url, request } = context;
+
+    if (request.method !== 'POST') {
+        return errorResponse('Method not allowed', 405);
+    }
+
+    const d1Error = ensureD1(env);
+    if (d1Error) return d1Error;
+    registerConnection('default', createD1Driver(env.OBCF_D1));
+
+    const appId = url.searchParams.get('appId') || null;
+
+    try {
+        // Check if sections already exist — skip if so
+        const sectionWhere: Record<string, unknown> = {};
+        if (appId) sectionWhere.appId = appId;
+        const existing = await HomepageSection.where(sectionWhere);
+        if (existing.length > 0) {
+            return jsonResponse({
+                success: true,
+                seeded: false,
+                message: `Homepage already has ${existing.length} section(s). Skipping seed.`,
+            });
+        }
+
+        // Create sections
+        const sectionMap: Record<string, string> = {}; // slot → id
+        for (const s of SEED_SECTIONS) {
+            const record = await HomepageSection.create({
+                ...s,
+                cssClasses: null,
+                metadata: null,
+                ...(appId ? { appId } : {}),
+            });
+            sectionMap[s.slot] = record.get('id') as string;
+        }
+
+        // Create features for the "features" section
+        const featuresSectionId = sectionMap.features;
+        if (featuresSectionId) {
+            for (let i = 0; i < SEED_FEATURES.length; i++) {
+                await HomepageFeature.create({
+                    sectionId: featuresSectionId,
+                    title: SEED_FEATURES[i].title,
+                    description: SEED_FEATURES[i].description,
+                    icon: SEED_FEATURES[i].icon,
+                    imageUrl: null,
+                    href: null,
+                    sortOrder: i,
+                    ...(appId ? { appId } : {}),
+                });
+            }
+        }
+
+        // Create hero actions
+        const heroSectionId = sectionMap.hero;
+        if (heroSectionId) {
+            for (const a of SEED_HERO_ACTIONS) {
+                await HomepageAction.create({
+                    sectionId: heroSectionId,
+                    ...a,
+                    ...(appId ? { appId } : {}),
+                });
+            }
+        }
+
+        // Create CTA actions
+        const ctaSectionId = sectionMap.cta;
+        if (ctaSectionId) {
+            for (const a of SEED_CTA_ACTIONS) {
+                await HomepageAction.create({
+                    sectionId: ctaSectionId,
+                    ...a,
+                    ...(appId ? { appId } : {}),
+                });
+            }
+        }
+
+        // Create display settings
+        await HomepageDisplaySettings.create({
+            id: 'default',
+            ...SEED_DISPLAY,
+            fallbackThemePresetId: null,
+            customCss: null,
+            seoTitle: null,
+            seoDescription: null,
+            ...(appId ? { appId } : {}),
+        });
+
+        return jsonResponse({
+            success: true,
+            seeded: true,
+            sections: Object.keys(sectionMap).length,
+            features: SEED_FEATURES.length,
+            actions: SEED_HERO_ACTIONS.length + SEED_CTA_ACTIONS.length,
+        });
+    } catch (err: any) {
+        console.error('[homepage/seed] Failed:', err);
+        return errorResponse(err.message ?? 'Seed failed', 500);
+    }
+}
diff --git a/apps/ottabase-template-app-tanstack/worker/routes/router.ts b/apps/ottabase-template-app-tanstack/worker/routes/router.ts
index 1cb3bad2e..68c5cd1d9 100644
--- a/apps/ottabase-template-app-tanstack/worker/routes/router.ts
+++ b/apps/ottabase-template-app-tanstack/worker/routes/router.ts
@@ -68,7 +68,7 @@ import {
 } from './blog';
 import { handleChangelogEntriesList, handleChangelogEntryBySlug } from './changelog';
 import { handleBrandApi } from './brand';
-import { handleHomepageData } from './homepage';
+import { handleHomepageData, handleHomepageSeed } from './homepage';
 import {
     handleAIChat,
     handleAIGatewayChat,
@@ -187,6 +187,11 @@ async function handleGetRoutes(context: ApiRouteContext): Promise<Response | nul
         return handleHomepageData(context);
     }
 
+    // Homepage seed (creates demo content)
+    if (route === '/api/homepage/seed') {
+        return handleHomepageSeed(context);
+    }
+
     if (route === '/api/system/kill-switches') {
         return jsonResponse({
             ...getKillSwitchStatus(context.env),
diff --git a/pnpm-lock.yaml b/pnpm-lock.yaml
index e699ee2ee..a406625f4 100644
--- a/pnpm-lock.yaml
+++ b/pnpm-lock.yaml
@@ -404,6 +404,9 @@ importers:
       tailwind-merge:
         specifier: 'catalog:'
         version: 2.6.0
+      zod:
+        specifier: 'catalog:'
+        version: 3.25.76
     devDependencies:
       '@cloudflare/workers-types':
         specifier: 'catalog:'

From 0aa0310ae7d4eed9c34a59d55738c7647855da18 Mon Sep 17 00:00:00 2001
From: "copilot-swe-agent[bot]" <198982749+Copilot@users.noreply.github.com>
Date: Tue, 31 Mar 2026 05:59:40 +0000
Subject: [PATCH 13/19] =?UTF-8?q?refactor:=20address=20code=20review=20?=
 =?UTF-8?q?=E2=80=94=20improve=20log=20messages,=20rename=20applyThemeWith?=
 =?UTF-8?q?Precedence,=20clarify=20merge=20comments?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Agent-Logs-Url: https://github.com/thinkdj/ottabase/sessions/fa1817dd-2a0e-4aa2-b880-b83c22af8a9a
---
 apps/ottabase-template-app-nextjs-homepage/app/layout.tsx | 2 +-
 .../app/providers.tsx                                     | 6 +++---
 .../lib/get-homepage-data.ts                              | 2 +-
 .../lib/homepage-config-context.tsx                       | 8 +++++---
 4 files changed, 10 insertions(+), 8 deletions(-)

diff --git a/apps/ottabase-template-app-nextjs-homepage/app/layout.tsx b/apps/ottabase-template-app-nextjs-homepage/app/layout.tsx
index a95ccef5e..b99eae388 100644
--- a/apps/ottabase-template-app-nextjs-homepage/app/layout.tsx
+++ b/apps/ottabase-template-app-nextjs-homepage/app/layout.tsx
@@ -37,7 +37,7 @@ export default async function RootLayout({ children }: { children: React.ReactNo
     return (
         <html lang="en" suppressHydrationWarning>
             <head>
-                {/* SEO overrides from admin display settings */}
+                {/* Runtime SEO injection from DB display settings (bypasses Next.js metadata to support admin-driven content) */}
                 {seoTitle && <title>{seoTitle}</title>}
                 {seoDescription && <meta name="description" content={seoDescription} />}
                 {/* Inject critical CSS for theme variables */}
diff --git a/apps/ottabase-template-app-nextjs-homepage/app/providers.tsx b/apps/ottabase-template-app-nextjs-homepage/app/providers.tsx
index 920c911bc..53ad0536e 100644
--- a/apps/ottabase-template-app-nextjs-homepage/app/providers.tsx
+++ b/apps/ottabase-template-app-nextjs-homepage/app/providers.tsx
@@ -26,7 +26,7 @@ export function Providers({ children, initialBrandConfig, initialHomepageConfig,
         // Priority: localStorage saved preset > DB themePresetId > SSR brand config
         const savedPreset = localStorage.getItem(THEME_STORAGE_KEY);
 
-        const applyCorrectTheme = () => {
+        const applyThemeWithPrecedence = () => {
             const isDark = document.documentElement.classList.contains('dark');
             const mode = isDark ? 'dark' : 'light';
 
@@ -60,12 +60,12 @@ export function Providers({ children, initialBrandConfig, initialHomepageConfig,
             }
         };
 
-        applyCorrectTheme();
+        applyThemeWithPrecedence();
 
         const observer = new MutationObserver((mutations) => {
             for (const mutation of mutations) {
                 if (mutation.type === 'attributes' && mutation.attributeName === 'class') {
-                    applyCorrectTheme();
+                    applyThemeWithPrecedence();
                 }
             }
         });
diff --git a/apps/ottabase-template-app-nextjs-homepage/lib/get-homepage-data.ts b/apps/ottabase-template-app-nextjs-homepage/lib/get-homepage-data.ts
index 89643277d..d917a0509 100644
--- a/apps/ottabase-template-app-nextjs-homepage/lib/get-homepage-data.ts
+++ b/apps/ottabase-template-app-nextjs-homepage/lib/get-homepage-data.ts
@@ -93,7 +93,7 @@ export async function getHomepageData(): Promise<ValidatedHomepageData> {
             return result.data;
         }
         // Log validation errors but don't hard-fail
-        console.warn('[get-homepage-data] Validation failed:', result.error.issues);
+        console.warn('[get-homepage-data] API validation failed for /api/homepage/data:', result.error.issues);
         return HomepageDataSchema.parse(EMPTY_PAYLOAD);
     } catch {
         return HomepageDataSchema.parse(EMPTY_PAYLOAD);
diff --git a/apps/ottabase-template-app-nextjs-homepage/lib/homepage-config-context.tsx b/apps/ottabase-template-app-nextjs-homepage/lib/homepage-config-context.tsx
index b545cc84f..a0dca24bd 100644
--- a/apps/ottabase-template-app-nextjs-homepage/lib/homepage-config-context.tsx
+++ b/apps/ottabase-template-app-nextjs-homepage/lib/homepage-config-context.tsx
@@ -32,9 +32,8 @@ export interface HomepageConfigProviderProps {
 }
 
 /**
- * Merge priority: localStorage > API variantBySlot > built-in defaults.
- * This ensures users can override via the config panel, DB settings provide
- * a baseline, and defaults are always available.
+ * Merges API variants with defaults. localStorage precedence is applied
+ * separately in the provider's useEffect hook.
  */
 function mergeConfig(apiVariants: Record<string, string> | null | undefined): HomepageConfig {
     const defaults = getDefaultConfig();
@@ -61,6 +60,9 @@ export function HomepageConfigProvider({ children, initialVariantBySlot }: Homep
     const [config, setConfig] = useState<HomepageConfig>(() => mergeConfig(initialVariantBySlot));
 
     // Layer 2: Hydrate from localStorage on mount (takes final precedence)
+    // Note: We detect user-set values by comparing to defaults. This means if a user
+    // explicitly sets a slot back to its default, it won't be treated as "user-configured".
+    // This is an acceptable trade-off vs. the complexity of tracking explicit modifications.
     useEffect(() => {
         const localConfig = loadConfig();
         // Merge: localStorage overrides API values where localStorage has valid entries

From b6f6c5bebfcb822cbbdec0deb72456974777d92c Mon Sep 17 00:00:00 2001
From: "copilot-swe-agent[bot]" <198982749+Copilot@users.noreply.github.com>
Date: Tue, 31 Mar 2026 06:58:33 +0000
Subject: [PATCH 14/19] feat: add @ottabase/homepage-contract shared package +
 Seed Defaults button on admin homepage

Agent-Logs-Url: https://github.com/thinkdj/ottabase/sessions/334c1a54-ae9a-4059-bed8-5e68ebd4db4b
---
 .../lib/api.ts                                |  68 ++---
 .../lib/get-homepage-data.ts                  |  62 +----
 .../package.json                              |   5 +-
 .../package.json                              |   1 +
 .../homepage/AdminHomepageSectionsPage.tsx    |  59 ++++
 .../worker/routes/homepage.ts                 |  55 +---
 packages/homepage-contract/README.md          |  39 +++
 packages/homepage-contract/package.json       |  48 ++++
 .../src/__tests__/schemas.test.ts             |  78 ++++++
 packages/homepage-contract/src/index.ts       |  37 +++
 packages/homepage-contract/src/schemas.ts     |  68 +++++
 packages/homepage-contract/src/types.ts       |  33 +++
 packages/homepage-contract/tsconfig.json      |  22 ++
 packages/homepage-contract/vitest.config.ts   |  15 ++
 pnpm-lock.yaml                                | 253 ++++++------------
 15 files changed, 510 insertions(+), 333 deletions(-)
 create mode 100644 packages/homepage-contract/README.md
 create mode 100644 packages/homepage-contract/package.json
 create mode 100644 packages/homepage-contract/src/__tests__/schemas.test.ts
 create mode 100644 packages/homepage-contract/src/index.ts
 create mode 100644 packages/homepage-contract/src/schemas.ts
 create mode 100644 packages/homepage-contract/src/types.ts
 create mode 100644 packages/homepage-contract/tsconfig.json
 create mode 100644 packages/homepage-contract/vitest.config.ts

diff --git a/apps/ottabase-template-app-nextjs-homepage/lib/api.ts b/apps/ottabase-template-app-nextjs-homepage/lib/api.ts
index 6047376e3..d0b6a9b7e 100644
--- a/apps/ottabase-template-app-nextjs-homepage/lib/api.ts
+++ b/apps/ottabase-template-app-nextjs-homepage/lib/api.ts
@@ -2,8 +2,24 @@
  * API helpers for fetching data from the Ottabase worker backend.
  *
  * Requires NEXT_PUBLIC_API_URL to be set (e.g. http://localhost:3004).
+ *
+ * Types are re-exported from `@ottabase/homepage-contract` — the shared
+ * Zod-inferred contract package — so Next.js and the TanStack worker
+ * always agree on the payload shape.
  */
 
+import type { HomepageDataPayload } from '@ottabase/homepage-contract';
+
+// Re-export shared contract types so existing imports continue to work
+export type {
+    ExposedPage,
+    HomepageSectionPayload,
+    HomepageDisplayPayload,
+    HomepageDataPayload,
+    HomepageFeaturePayload,
+    HomepageActionPayload,
+} from '@ottabase/homepage-contract';
+
 const API_URL = process.env.NEXT_PUBLIC_API_URL ?? '';
 
 /** EditorJS block data shape */
@@ -42,58 +58,6 @@ export interface PageData {
     updatedAt: string;
 }
 
-/** Exposed page link for homepage navbar */
-export interface ExposedPage {
-    slug: string;
-    title: string;
-}
-
-/** Homepage section from the public API */
-export interface HomepageSectionPayload {
-    id: string;
-    slot: string;
-    title: string | null;
-    subtitle: string | null;
-    body: string | null;
-    githubUrl: string | null;
-    icon: string | null;
-    enabled: boolean;
-    cssClasses: string | null;
-    metadata: Record<string, unknown> | null;
-    sortOrder: number;
-    features: Array<{
-        title: string;
-        description: string;
-        icon: string | null;
-        imageUrl: string | null;
-        href: string | null;
-    }>;
-    actions: Array<{
-        label: string;
-        href: string;
-        variant: string | null;
-        icon: string | null;
-        external: boolean;
-    }>;
-}
-
-/** Homepage display settings from the public API */
-export interface HomepageDisplayPayload {
-    variantBySlot: Record<string, string> | null;
-    themePreset: string | null;
-    fallbackThemePresetId: string | null;
-    customCss: string | null;
-    seoTitle: string | null;
-    seoDescription: string | null;
-}
-
-/** Full homepage data payload from GET /api/homepage/data */
-export interface HomepageDataPayload {
-    sections: HomepageSectionPayload[];
-    display: HomepageDisplayPayload;
-    exposedPages: ExposedPage[];
-}
-
 /**
  * Fetch a published page by slug from the worker API.
  * Returns null if not found or on error.
diff --git a/apps/ottabase-template-app-nextjs-homepage/lib/get-homepage-data.ts b/apps/ottabase-template-app-nextjs-homepage/lib/get-homepage-data.ts
index d917a0509..6ef8fb76e 100644
--- a/apps/ottabase-template-app-nextjs-homepage/lib/get-homepage-data.ts
+++ b/apps/ottabase-template-app-nextjs-homepage/lib/get-homepage-data.ts
@@ -2,69 +2,17 @@
  * Homepage data fetcher with Zod validation.
  *
  * Wraps the raw `fetchHomepageData()` API call with schema validation
- * and provides typed, validated payloads for the Next.js consumer.
+ * using the shared `@ottabase/homepage-contract` schemas.
  * Falls back to safe defaults when the API is unavailable or returns invalid data.
  */
 
-import { z } from 'zod';
-import type { HomepageDataPayload } from './api';
+import { HomepageDataSchema, type HomepageDataPayload } from '@ottabase/homepage-contract';
 import { fetchHomepageData } from './api';
 
-// ── Zod schemas for API payload validation ──────────────────────────────────
+// Re-export for consumers that imported from here (e.g. tests)
+export { HomepageDataSchema };
 
-const ExposedPageSchema = z.object({
-    slug: z.string(),
-    title: z.string(),
-});
-
-const FeatureSchema = z.object({
-    title: z.string(),
-    description: z.string(),
-    icon: z.string().nullable().optional(),
-    imageUrl: z.string().nullable().optional(),
-    href: z.string().nullable().optional(),
-});
-
-const ActionSchema = z.object({
-    label: z.string(),
-    href: z.string(),
-    variant: z.string().nullable().optional(),
-    icon: z.string().nullable().optional(),
-    external: z.boolean().optional().default(false),
-});
-
-const SectionSchema = z.object({
-    id: z.string(),
-    slot: z.string(),
-    title: z.string().nullable(),
-    subtitle: z.string().nullable(),
-    body: z.string().nullable(),
-    githubUrl: z.string().nullable(),
-    icon: z.string().nullable(),
-    enabled: z.boolean().default(true),
-    cssClasses: z.string().nullable(),
-    metadata: z.record(z.unknown()).nullable(),
-    sortOrder: z.number().default(0),
-    features: z.array(FeatureSchema).default([]),
-    actions: z.array(ActionSchema).default([]),
-});
-
-const DisplaySchema = z.object({
-    variantBySlot: z.record(z.string()).nullable(),
-    themePreset: z.string().nullable(),
-    fallbackThemePresetId: z.string().nullable().optional(),
-    customCss: z.string().nullable().optional(),
-    seoTitle: z.string().nullable().optional(),
-    seoDescription: z.string().nullable().optional(),
-});
-
-export const HomepageDataSchema = z.object({
-    sections: z.array(SectionSchema).default([]),
-    display: DisplaySchema,
-    exposedPages: z.array(ExposedPageSchema).default([]),
-});
-
-export type ValidatedHomepageData = z.infer<typeof HomepageDataSchema>;
+export type ValidatedHomepageData = HomepageDataPayload;
 
 // ── Safe defaults ───────────────────────────────────────────────────────────
 
diff --git a/apps/ottabase-template-app-nextjs-homepage/package.json b/apps/ottabase-template-app-nextjs-homepage/package.json
index 2f055983d..e03d439e5 100644
--- a/apps/ottabase-template-app-nextjs-homepage/package.json
+++ b/apps/ottabase-template-app-nextjs-homepage/package.json
@@ -21,6 +21,7 @@
         "@ottabase/brand-engine": "workspace:*",
         "@ottabase/brand-engine-react": "workspace:*",
         "@ottabase/config": "workspace:*",
+        "@ottabase/homepage-contract": "workspace:*",
         "@ottabase/ottalayout": "workspace:*",
         "@ottabase/ottarenderer": "workspace:*",
         "@ottabase/ui-components": "workspace:*",
@@ -50,12 +51,12 @@
         "autoprefixer": "catalog:",
         "eslint": "catalog:",
         "eslint-config-next": "^16.1.1",
+        "localflare": "catalog:",
         "postcss": "catalog:",
         "postcss-preset-env": "catalog:",
         "tailwindcss": "catalog:",
         "tailwindcss-animate": "catalog:",
         "typescript": "catalog:",
-        "wrangler": "catalog:",
-        "localflare": "catalog:"
+        "wrangler": "catalog:"
     }
 }
diff --git a/apps/ottabase-template-app-tanstack/package.json b/apps/ottabase-template-app-tanstack/package.json
index e87809193..0bb797a28 100644
--- a/apps/ottabase-template-app-tanstack/package.json
+++ b/apps/ottabase-template-app-tanstack/package.json
@@ -41,6 +41,7 @@
         "@ottabase/docs": "workspace:*",
         "@ottabase/email": "workspace:*",
         "@ottabase/forms": "workspace:*",
+        "@ottabase/homepage-contract": "workspace:*",
         "@ottabase/i18n": "workspace:*",
         "@ottabase/logger": "workspace:*",
         "@ottabase/medialibrary": "workspace:*",
diff --git a/apps/ottabase-template-app-tanstack/src/pages/admin/homepage/AdminHomepageSectionsPage.tsx b/apps/ottabase-template-app-tanstack/src/pages/admin/homepage/AdminHomepageSectionsPage.tsx
index 3dde0985d..3137238cd 100644
--- a/apps/ottabase-template-app-tanstack/src/pages/admin/homepage/AdminHomepageSectionsPage.tsx
+++ b/apps/ottabase-template-app-tanstack/src/pages/admin/homepage/AdminHomepageSectionsPage.tsx
@@ -41,6 +41,7 @@ import {
     TooltipProvider,
     TooltipTrigger,
 } from '@ottabase/ui-shadcn';
+import { IconDatabaseImport } from '@tabler/icons-react';
 import { Link } from '@tanstack/react-router';
 import {
     ArrowDown,
@@ -316,11 +317,33 @@ export function AdminHomepageSectionsPage() {
     const updateSection = homepageSectionHooks.useUpdate();
     const deleteSection = homepageSectionHooks.useDelete();
     const [deleteDialog, setDeleteDialog] = useState<{ id: string; slot: string } | null>(null);
+    const [seeding, setSeeding] = useState(false);
+    const [seedResult, setSeedResult] = useState<'success' | 'exists' | 'error' | null>(null);
 
     const sections = (Array.isArray(data) ? data : []) as HomepageSectionRow[];
     const usedSlots = new Set(sections.map((s) => s.slot));
     const availableSlots = SLOT_NAMES.filter((s) => !usedSlots.has(s));
 
+    const handleSeedDefaults = useCallback(async () => {
+        setSeeding(true);
+        setSeedResult(null);
+        try {
+            const res = await fetch('/api/homepage/seed', { method: 'POST' });
+            const body = await res.json();
+            if (body.skipped) {
+                setSeedResult('exists');
+            } else {
+                setSeedResult('success');
+                // Refetch sections after seed
+                window.location.reload();
+            }
+        } catch {
+            setSeedResult('error');
+        } finally {
+            setSeeding(false);
+        }
+    }, []);
+
     const handleCreateSection = async (slot: string) => {
         await createSection.mutateAsync({
             slot,
@@ -375,6 +398,42 @@ export function AdminHomepageSectionsPage() {
                     </p>
                 </div>
                 <div className="flex items-center gap-3">
+                    <TooltipProvider>
+                        <Tooltip>
+                            <TooltipTrigger asChild>
+                                <Button
+                                    variant="outline"
+                                    size="sm"
+                                    onClick={handleSeedDefaults}
+                                    disabled={seeding || sections.length > 0}
+                                    className="gap-1.5"
+                                >
+                                    <IconDatabaseImport className="h-4 w-4" />
+                                    {seeding ? 'Seeding…' : 'Seed Defaults'}
+                                </Button>
+                            </TooltipTrigger>
+                            <TooltipContent>
+                                {sections.length > 0
+                                    ? 'Sections already exist — seed is only for empty databases'
+                                    : 'Populate D1 with sample homepage data (sections, features, actions, display settings)'}
+                            </TooltipContent>
+                        </Tooltip>
+                    </TooltipProvider>
+                    {seedResult === 'success' && (
+                        <Badge variant="default" className="text-xs bg-green-600">
+                            Seeded!
+                        </Badge>
+                    )}
+                    {seedResult === 'exists' && (
+                        <Badge variant="secondary" className="text-xs">
+                            Already seeded
+                        </Badge>
+                    )}
+                    {seedResult === 'error' && (
+                        <Badge variant="destructive" className="text-xs">
+                            Seed failed
+                        </Badge>
+                    )}
                     <Badge variant="secondary" className="text-xs">
                         {enabledCount}/{sections.length} active
                     </Badge>
diff --git a/apps/ottabase-template-app-tanstack/worker/routes/homepage.ts b/apps/ottabase-template-app-tanstack/worker/routes/homepage.ts
index d38d415e3..fab4ba986 100644
--- a/apps/ottabase-template-app-tanstack/worker/routes/homepage.ts
+++ b/apps/ottabase-template-app-tanstack/worker/routes/homepage.ts
@@ -9,6 +9,12 @@
 
 import { Post } from '@ottabase/ottablog';
 import { createD1Driver } from '@ottabase/db/drizzle-d1';
+import type {
+    HomepageSectionPayload,
+    HomepageDisplayPayload,
+    HomepageDataPayload,
+    ExposedPage,
+} from '@ottabase/homepage-contract';
 import { registerConnection } from '@ottabase/ottaorm';
 import { errorResponse } from '@ottabase/utils/http-errors';
 import { jsonResponse } from '@ottabase/utils/http-response';
@@ -33,51 +39,12 @@ function ensureD1(env: CloudflareEnv): Response | null {
     return null;
 }
 
-/** Shape of a section in the public payload */
-interface PublicSection {
-    id: string;
-    slot: string;
-    title: string | null;
-    subtitle: string | null;
-    body: string | null;
-    githubUrl: string | null;
-    icon: string | null;
-    enabled: boolean;
-    cssClasses: string | null;
-    metadata: Record<string, unknown> | null;
-    sortOrder: number;
-    features: Array<{
-        title: string;
-        description: string;
-        icon: string | null;
-        imageUrl: string | null;
-        href: string | null;
-    }>;
-    actions: Array<{
-        label: string;
-        href: string;
-        variant: string | null;
-        icon: string | null;
-        external: boolean;
-    }>;
-}
-
-/** Shape of display settings in the public payload */
-interface PublicDisplay {
-    variantBySlot: Record<string, string> | null;
-    themePreset: string | null;
-    fallbackThemePresetId: string | null;
-    customCss: string | null;
-    seoTitle: string | null;
-    seoDescription: string | null;
-}
+// Use shared contract types — no local duplicates
+type PublicSection = HomepageSectionPayload;
+type PublicDisplay = HomepageDisplayPayload;
 
-/** Shape of the full public payload */
-export interface HomepagePublicPayload {
-    sections: PublicSection[];
-    display: PublicDisplay;
-    exposedPages: Array<{ slug: string; title: string }>;
-}
+/** Re-export for convenience */
+export type HomepagePublicPayload = HomepageDataPayload;
 
 /**
  * GET /api/homepage/data
diff --git a/packages/homepage-contract/README.md b/packages/homepage-contract/README.md
new file mode 100644
index 000000000..efcb23e37
--- /dev/null
+++ b/packages/homepage-contract/README.md
@@ -0,0 +1,39 @@
+# @ottabase/homepage-contract
+
+Shared Zod schemas and TypeScript types for the homepage data API contract between the TanStack worker (producer) and
+the Next.js homepage app (consumer).
+
+## Usage
+
+```typescript
+import {
+    HomepageDataSchema,
+    type HomepageDataPayload,
+    type HomepageSectionPayload,
+    type ExposedPage,
+} from '@ottabase/homepage-contract';
+
+// Validate an API response
+const result = HomepageDataSchema.safeParse(apiResponse);
+if (result.success) {
+    const data: HomepageDataPayload = result.data;
+}
+
+// Type-safe section access
+const hero: HomepageSectionPayload | undefined = data.sections.find((s) => s.slot === 'hero');
+```
+
+## Exported Schemas
+
+| Schema               | Description                                           |
+| -------------------- | ----------------------------------------------------- |
+| `ExposedPageSchema`  | `{ slug, title }` for navbar page links               |
+| `FeatureSchema`      | Feature item with icon, imageUrl, href                |
+| `ActionSchema`       | Action button with variant, icon, external            |
+| `SectionSchema`      | Full section with nested features + actions           |
+| `DisplaySchema`      | Variant-by-slot, theme, SEO, custom CSS               |
+| `HomepageDataSchema` | Top-level payload (sections + display + exposedPages) |
+
+## Exported Types
+
+All types are inferred from Zod schemas (`z.infer<typeof Schema>`) — zero drift.
diff --git a/packages/homepage-contract/package.json b/packages/homepage-contract/package.json
new file mode 100644
index 000000000..c414254c3
--- /dev/null
+++ b/packages/homepage-contract/package.json
@@ -0,0 +1,48 @@
+{
+    "name": "@ottabase/homepage-contract",
+    "version": "1.0.0",
+    "description": "Shared Zod schemas and TypeScript types for the homepage data contract between TanStack worker API and Next.js consumer",
+    "main": "dist/index.js",
+    "module": "dist/index.mjs",
+    "types": "dist/index.d.ts",
+    "exports": {
+        ".": {
+            "types": "./dist/index.d.ts",
+            "import": "./dist/index.mjs",
+            "require": "./dist/index.js"
+        }
+    },
+    "files": [
+        "dist",
+        "README.md"
+    ],
+    "scripts": {
+        "build": "tsup src/index.ts --format cjs,esm --dts --clean",
+        "dev": "tsup src/index.ts --format cjs,esm --dts --watch",
+        "clean": "rimraf dist",
+        "lint": "eslint src --ext .ts,.tsx",
+        "type-check": "tsc --noEmit",
+        "test": "vitest",
+        "test:coverage": "vitest --coverage"
+    },
+    "keywords": [
+        "homepage",
+        "contract",
+        "zod",
+        "schema",
+        "types"
+    ],
+    "author": "",
+    "license": "MIT",
+    "dependencies": {
+        "zod": "catalog:"
+    },
+    "devDependencies": {
+        "@types/node": "catalog:",
+        "typescript": "catalog:",
+        "tsup": "catalog:",
+        "rimraf": "catalog:",
+        "eslint": "catalog:",
+        "vitest": "catalog:"
+    }
+}
diff --git a/packages/homepage-contract/src/__tests__/schemas.test.ts b/packages/homepage-contract/src/__tests__/schemas.test.ts
new file mode 100644
index 000000000..e3597739c
--- /dev/null
+++ b/packages/homepage-contract/src/__tests__/schemas.test.ts
@@ -0,0 +1,78 @@
+import { describe, it, expect } from 'vitest';
+import { HomepageDataSchema, ExposedPageSchema, SectionSchema, DisplaySchema } from '../schemas';
+
+describe('@ottabase/homepage-contract schemas', () => {
+    it('validates a complete payload', () => {
+        const payload = {
+            sections: [
+                {
+                    id: 'sec-1',
+                    slot: 'hero',
+                    title: 'Welcome',
+                    subtitle: 'Build fast',
+                    body: null,
+                    githubUrl: null,
+                    icon: 'Sparkles',
+                    enabled: true,
+                    cssClasses: null,
+                    metadata: null,
+                    sortOrder: 0,
+                    features: [],
+                    actions: [{ label: 'Start', href: '/start', variant: 'default', icon: null, external: false }],
+                },
+            ],
+            display: {
+                variantBySlot: { hero: 'centered', features: 'grid' },
+                themePreset: 'neo',
+                fallbackThemePresetId: null,
+            },
+            exposedPages: [{ slug: 'pricing', title: 'Pricing' }],
+        };
+        const result = HomepageDataSchema.safeParse(payload);
+        expect(result.success).toBe(true);
+        if (result.success) {
+            expect(result.data.sections).toHaveLength(1);
+            expect(result.data.sections[0].slot).toBe('hero');
+            expect(result.data.display.themePreset).toBe('neo');
+            expect(result.data.exposedPages[0].slug).toBe('pricing');
+        }
+    });
+
+    it('applies defaults for missing optional fields', () => {
+        const minimal = {
+            sections: [],
+            display: { variantBySlot: null, themePreset: null, fallbackThemePresetId: null },
+            exposedPages: [],
+        };
+        const result = HomepageDataSchema.safeParse(minimal);
+        expect(result.success).toBe(true);
+    });
+
+    it('rejects invalid section (missing id)', () => {
+        const result = SectionSchema.safeParse({ slot: 'hero', title: 'Test' });
+        expect(result.success).toBe(false);
+    });
+
+    it('rejects invalid display (missing variantBySlot)', () => {
+        const result = DisplaySchema.safeParse({ themePreset: 'neo' });
+        expect(result.success).toBe(false);
+    });
+
+    it('validates exposed page', () => {
+        const result = ExposedPageSchema.safeParse({ slug: 'about', title: 'About Us' });
+        expect(result.success).toBe(true);
+    });
+
+    it('infers correct types from schemas', () => {
+        const payload = HomepageDataSchema.parse({
+            sections: [],
+            display: { variantBySlot: null, themePreset: null, fallbackThemePresetId: null },
+            exposedPages: [],
+        });
+        // Type-level check — these properties must exist
+        expect(payload.sections).toBeDefined();
+        expect(payload.display).toBeDefined();
+        expect(payload.exposedPages).toBeDefined();
+        expect(payload.display.variantBySlot).toBeNull();
+    });
+});
diff --git a/packages/homepage-contract/src/index.ts b/packages/homepage-contract/src/index.ts
new file mode 100644
index 000000000..1bf69bdd5
--- /dev/null
+++ b/packages/homepage-contract/src/index.ts
@@ -0,0 +1,37 @@
+/**
+ * @ottabase/homepage-contract
+ *
+ * Shared Zod schemas and TypeScript types for the homepage data contract.
+ * Used by the TanStack worker (producer) and the Next.js app (consumer).
+ *
+ * @example
+ * ```ts
+ * import { HomepageDataSchema, type HomepageDataPayload } from '@ottabase/homepage-contract';
+ *
+ * // Validate API response
+ * const result = HomepageDataSchema.safeParse(raw);
+ *
+ * // Type-safe usage
+ * const payload: HomepageDataPayload = result.data;
+ * ```
+ */
+
+// Zod schemas (runtime validation)
+export {
+    ExposedPageSchema,
+    FeatureSchema,
+    ActionSchema,
+    SectionSchema,
+    DisplaySchema,
+    HomepageDataSchema,
+} from './schemas';
+
+// TypeScript types (inferred from schemas — no drift)
+export type {
+    ExposedPage,
+    HomepageFeaturePayload,
+    HomepageActionPayload,
+    HomepageSectionPayload,
+    HomepageDisplayPayload,
+    HomepageDataPayload,
+} from './types';
diff --git a/packages/homepage-contract/src/schemas.ts b/packages/homepage-contract/src/schemas.ts
new file mode 100644
index 000000000..39b8db3fc
--- /dev/null
+++ b/packages/homepage-contract/src/schemas.ts
@@ -0,0 +1,68 @@
+/**
+ * @ottabase/homepage-contract — Zod schemas
+ *
+ * Single source of truth for the homepage data API contract.
+ * Used by the TanStack worker (producer) and the Next.js app (consumer).
+ */
+
+import { z } from 'zod';
+
+// ── Leaf schemas ────────────────────────────────────────────────────────────
+
+export const ExposedPageSchema = z.object({
+    slug: z.string(),
+    title: z.string(),
+});
+
+export const FeatureSchema = z.object({
+    title: z.string(),
+    description: z.string(),
+    icon: z.string().nullable().optional(),
+    imageUrl: z.string().nullable().optional(),
+    href: z.string().nullable().optional(),
+});
+
+export const ActionSchema = z.object({
+    label: z.string(),
+    href: z.string(),
+    variant: z.string().nullable().optional(),
+    icon: z.string().nullable().optional(),
+    external: z.boolean().optional().default(false),
+});
+
+// ── Section schema ──────────────────────────────────────────────────────────
+
+export const SectionSchema = z.object({
+    id: z.string(),
+    slot: z.string(),
+    title: z.string().nullable(),
+    subtitle: z.string().nullable(),
+    body: z.string().nullable(),
+    githubUrl: z.string().nullable(),
+    icon: z.string().nullable(),
+    enabled: z.boolean().default(true),
+    cssClasses: z.string().nullable(),
+    metadata: z.record(z.unknown()).nullable(),
+    sortOrder: z.number().default(0),
+    features: z.array(FeatureSchema).default([]),
+    actions: z.array(ActionSchema).default([]),
+});
+
+// ── Display settings schema ─────────────────────────────────────────────────
+
+export const DisplaySchema = z.object({
+    variantBySlot: z.record(z.string()).nullable(),
+    themePreset: z.string().nullable(),
+    fallbackThemePresetId: z.string().nullable().optional(),
+    customCss: z.string().nullable().optional(),
+    seoTitle: z.string().nullable().optional(),
+    seoDescription: z.string().nullable().optional(),
+});
+
+// ── Top-level payload schema ────────────────────────────────────────────────
+
+export const HomepageDataSchema = z.object({
+    sections: z.array(SectionSchema).default([]),
+    display: DisplaySchema,
+    exposedPages: z.array(ExposedPageSchema).default([]),
+});
diff --git a/packages/homepage-contract/src/types.ts b/packages/homepage-contract/src/types.ts
new file mode 100644
index 000000000..959fc11e3
--- /dev/null
+++ b/packages/homepage-contract/src/types.ts
@@ -0,0 +1,33 @@
+/**
+ * @ottabase/homepage-contract — TypeScript types
+ *
+ * All types are inferred from the Zod schemas so there is no drift.
+ */
+
+import type { z } from 'zod';
+import type {
+    ExposedPageSchema,
+    FeatureSchema,
+    ActionSchema,
+    SectionSchema,
+    DisplaySchema,
+    HomepageDataSchema,
+} from './schemas';
+
+/** Exposed page link for homepage navbar */
+export type ExposedPage = z.infer<typeof ExposedPageSchema>;
+
+/** Feature item within a homepage section */
+export type HomepageFeaturePayload = z.infer<typeof FeatureSchema>;
+
+/** Action button within a homepage section */
+export type HomepageActionPayload = z.infer<typeof ActionSchema>;
+
+/** Homepage section (with nested features and actions) */
+export type HomepageSectionPayload = z.infer<typeof SectionSchema>;
+
+/** Homepage display settings (variants, theme, SEO, custom CSS) */
+export type HomepageDisplayPayload = z.infer<typeof DisplaySchema>;
+
+/** Full homepage data payload from GET /api/homepage/data */
+export type HomepageDataPayload = z.infer<typeof HomepageDataSchema>;
diff --git a/packages/homepage-contract/tsconfig.json b/packages/homepage-contract/tsconfig.json
new file mode 100644
index 000000000..19dc570a3
--- /dev/null
+++ b/packages/homepage-contract/tsconfig.json
@@ -0,0 +1,22 @@
+{
+    "extends": "../../tsconfig.json",
+    "compilerOptions": {
+        "target": "ES2020",
+        "lib": ["ES6"],
+        "skipLibCheck": true,
+        "strict": true,
+        "forceConsistentCasingInFileNames": true,
+        "noEmit": true,
+        "esModuleInterop": true,
+        "module": "esnext",
+        "moduleResolution": "bundler",
+        "resolveJsonModule": true,
+        "isolatedModules": true,
+        "baseUrl": ".",
+        "paths": {
+            "@/*": ["./src/*"]
+        }
+    },
+    "include": ["src/**/*"],
+    "exclude": ["node_modules", "dist"]
+}
diff --git a/packages/homepage-contract/vitest.config.ts b/packages/homepage-contract/vitest.config.ts
new file mode 100644
index 000000000..aa0cbb780
--- /dev/null
+++ b/packages/homepage-contract/vitest.config.ts
@@ -0,0 +1,15 @@
+import { defineConfig } from 'vitest/config';
+import path from 'path';
+
+export default defineConfig({
+    test: {
+        environment: 'node',
+        globals: true,
+        include: ['src/**/*.{test,spec}.{ts,tsx}'],
+    },
+    resolve: {
+        alias: {
+            '@': path.resolve(__dirname, './src'),
+        },
+    },
+});
diff --git a/pnpm-lock.yaml b/pnpm-lock.yaml
index a406625f4..9570253ec 100644
--- a/pnpm-lock.yaml
+++ b/pnpm-lock.yaml
@@ -256,7 +256,7 @@ importers:
         version: 7.28.5(@babel/core@7.28.6)
       '@storybook/addon-docs':
         specifier: 'catalog:'
-        version: 10.2.3(@types/react@19.2.7)(esbuild@0.27.2)(rollup@4.57.1)(storybook@10.2.3(@testing-library/dom@10.4.1)(prettier@3.7.4)(react-dom@19.2.4(react@19.2.4))(react@19.2.4))(vite@7.3.1(@types/node@25.1.0)(jiti@1.21.7)(lightningcss@1.30.2)(sugarss@5.0.1(postcss@8.5.6))(terser@5.46.0)(tsx@4.21.0)(yaml@2.8.2))(webpack@5.104.1(@swc/core@1.13.5)(esbuild@0.27.2))
+        version: 10.2.3(@types/react@19.2.7)(esbuild@0.27.2)(rollup@4.57.1)(storybook@10.2.3(@testing-library/dom@10.4.1)(prettier@3.7.4)(react-dom@19.2.4(react@19.2.4))(react@19.2.4))(vite@7.3.1(@types/node@25.1.0)(jiti@2.6.1)(lightningcss@1.30.2)(sugarss@5.0.1(postcss@8.5.6))(terser@5.46.0)(tsx@4.21.0)(yaml@2.8.2))(webpack@5.104.1(@swc/core@1.13.5)(esbuild@0.27.2))
       '@storybook/addon-links':
         specifier: 'catalog:'
         version: 10.2.3(react@19.2.4)(storybook@10.2.3(@testing-library/dom@10.4.1)(prettier@3.7.4)(react-dom@19.2.4(react@19.2.4))(react@19.2.4))
@@ -274,13 +274,13 @@ importers:
         version: 16.3.2(@testing-library/dom@10.4.1)(@types/react-dom@19.2.3(@types/react@19.2.7))(@types/react@19.2.7)(react-dom@19.2.4(react@19.2.4))(react@19.2.4)
       '@typescript-eslint/eslint-plugin':
         specifier: 'catalog:'
-        version: 8.54.0(@typescript-eslint/parser@8.54.0(eslint@9.39.2(jiti@1.21.7))(typescript@5.9.3))(eslint@9.39.2(jiti@1.21.7))(typescript@5.9.3)
+        version: 8.54.0(@typescript-eslint/parser@8.54.0(eslint@9.39.2(jiti@2.6.1))(typescript@5.9.3))(eslint@9.39.2(jiti@2.6.1))(typescript@5.9.3)
       '@typescript-eslint/parser':
         specifier: 'catalog:'
-        version: 8.54.0(eslint@9.39.2(jiti@1.21.7))(typescript@5.9.3)
+        version: 8.54.0(eslint@9.39.2(jiti@2.6.1))(typescript@5.9.3)
       '@vitejs/plugin-react':
         specifier: 'catalog:'
-        version: 4.7.0(vite@7.3.1(@types/node@25.1.0)(jiti@1.21.7)(lightningcss@1.30.2)(sugarss@5.0.1(postcss@8.5.6))(terser@5.46.0)(tsx@4.21.0)(yaml@2.8.2))
+        version: 4.7.0(vite@7.3.1(@types/node@25.1.0)(jiti@2.6.1)(lightningcss@1.30.2)(sugarss@5.0.1(postcss@8.5.6))(terser@5.46.0)(tsx@4.21.0)(yaml@2.8.2))
       '@vitest/ui':
         specifier: ^4.0.18
         version: 4.0.18(vitest@4.0.18)
@@ -295,7 +295,7 @@ importers:
         version: 7.1.3(webpack@5.104.1(@swc/core@1.13.5)(esbuild@0.27.2))
       eslint-plugin-storybook:
         specifier: 'catalog:'
-        version: 10.2.3(eslint@9.39.2(jiti@1.21.7))(storybook@10.2.3(@testing-library/dom@10.4.1)(prettier@3.7.4)(react-dom@19.2.4(react@19.2.4))(react@19.2.4))(typescript@5.9.3)
+        version: 10.2.3(eslint@9.39.2(jiti@2.6.1))(storybook@10.2.3(@testing-library/dom@10.4.1)(prettier@3.7.4)(react-dom@19.2.4(react@19.2.4))(react@19.2.4))(typescript@5.9.3)
       happy-dom:
         specifier: ^20.4.0
         version: 20.4.0
@@ -337,13 +337,13 @@ importers:
         version: 1.0.7(tailwindcss@3.4.19(tsx@4.21.0)(yaml@2.8.2))
       tsup:
         specifier: 'catalog:'
-        version: 8.5.1(@swc/core@1.13.5)(jiti@1.21.7)(postcss@8.5.6)(tsx@4.21.0)(typescript@5.9.3)(yaml@2.8.2)
+        version: 8.5.1(@swc/core@1.13.5)(jiti@2.6.1)(postcss@8.5.6)(tsx@4.21.0)(typescript@5.9.3)(yaml@2.8.2)
       turbo:
         specifier: ^2.8.0
         version: 2.8.0
       vitest:
         specifier: 'catalog:'
-        version: 4.0.18(@opentelemetry/api@1.9.0)(@types/node@25.1.0)(@vitest/ui@4.0.18)(happy-dom@20.4.0)(jiti@1.21.7)(jsdom@27.4.0(@noble/hashes@1.8.0))(lightningcss@1.30.2)(sugarss@5.0.1(postcss@8.5.6))(terser@5.46.0)(tsx@4.21.0)(yaml@2.8.2)
+        version: 4.0.18(@opentelemetry/api@1.9.0)(@types/node@25.1.0)(@vitest/ui@4.0.18)(happy-dom@20.4.0)(jiti@2.6.1)(jsdom@27.4.0(@noble/hashes@1.8.0))(lightningcss@1.30.2)(sugarss@5.0.1(postcss@8.5.6))(terser@5.46.0)(tsx@4.21.0)(yaml@2.8.2)
       webpack:
         specifier: ^5.104.1
         version: 5.104.1(@swc/core@1.13.5)(esbuild@0.27.2)
@@ -359,6 +359,9 @@ importers:
       '@ottabase/config':
         specifier: workspace:*
         version: link:../../packages/config
+      '@ottabase/homepage-contract':
+        specifier: workspace:*
+        version: link:../../packages/homepage-contract
       '@ottabase/ottalayout':
         specifier: workspace:*
         version: link:../../packages/ottalayout
@@ -443,7 +446,7 @@ importers:
         version: 16.1.1(@typescript-eslint/parser@8.52.0(eslint@9.39.2(jiti@2.6.1))(typescript@5.9.3))(eslint@9.39.2(jiti@2.6.1))(typescript@5.9.3)
       localflare:
         specifier: 'catalog:'
-        version: 0.1.2(@types/react-dom@19.2.3(@types/react@19.2.7))(@types/react@19.2.7)(vite@7.3.1(@types/node@20.19.28)(jiti@2.6.1)(lightningcss@1.30.2)(sugarss@5.0.1(postcss@8.5.6))(terser@5.46.0)(tsx@4.21.0)(yaml@2.8.2))
+        version: 0.1.2(@types/react-dom@19.2.3(@types/react@19.2.7))(@types/react@19.2.7)(vite@7.3.1(@types/node@25.1.0)(jiti@2.6.1)(lightningcss@1.30.2)(sugarss@5.0.1(postcss@8.5.6))(terser@5.46.0)(tsx@4.21.0)(yaml@2.8.2))
       postcss:
         specifier: 'catalog:'
         version: 8.5.6
@@ -528,6 +531,9 @@ importers:
       '@ottabase/forms':
         specifier: workspace:*
         version: link:../../packages/forms
+      '@ottabase/homepage-contract':
+        specifier: workspace:*
+        version: link:../../packages/homepage-contract
       '@ottabase/i18n':
         specifier: workspace:*
         version: link:../../packages/i18n
@@ -1227,6 +1233,31 @@ importers:
         specifier: 'catalog:'
         version: 5.9.3
 
+  packages/homepage-contract:
+    dependencies:
+      zod:
+        specifier: 'catalog:'
+        version: 3.25.76
+    devDependencies:
+      '@types/node':
+        specifier: 'catalog:'
+        version: 20.19.28
+      eslint:
+        specifier: 'catalog:'
+        version: 9.39.2(jiti@2.6.1)
+      rimraf:
+        specifier: 'catalog:'
+        version: 6.1.2
+      tsup:
+        specifier: 'catalog:'
+        version: 8.5.1(@swc/core@1.13.5)(jiti@2.6.1)(postcss@8.5.6)(tsx@4.21.0)(typescript@5.9.3)(yaml@2.8.2)
+      typescript:
+        specifier: 'catalog:'
+        version: 5.9.3
+      vitest:
+        specifier: 'catalog:'
+        version: 4.0.18(@opentelemetry/api@1.9.0)(@types/node@20.19.28)(@vitest/ui@4.0.18)(happy-dom@20.4.0)(jiti@2.6.1)(jsdom@27.4.0(@noble/hashes@1.8.0))(lightningcss@1.30.2)(sugarss@5.0.1(postcss@8.5.6))(terser@5.46.0)(tsx@4.21.0)(yaml@2.8.2)
+
   packages/i18n:
     dependencies:
       i18next:
@@ -14883,11 +14914,6 @@ snapshots:
   '@esbuild/win32-x64@0.27.2':
     optional: true
 
-  '@eslint-community/eslint-utils@4.9.1(eslint@9.39.2(jiti@1.21.7))':
-    dependencies:
-      eslint: 9.39.2(jiti@1.21.7)
-      eslint-visitor-keys: 3.4.3
-
   '@eslint-community/eslint-utils@4.9.1(eslint@9.39.2(jiti@2.6.1))':
     dependencies:
       eslint: 9.39.2(jiti@2.6.1)
@@ -17082,10 +17108,10 @@ snapshots:
 
   '@standard-schema/spec@1.1.0': {}
 
-  '@storybook/addon-docs@10.2.3(@types/react@19.2.7)(esbuild@0.27.2)(rollup@4.57.1)(storybook@10.2.3(@testing-library/dom@10.4.1)(prettier@3.7.4)(react-dom@19.2.4(react@19.2.4))(react@19.2.4))(vite@7.3.1(@types/node@25.1.0)(jiti@1.21.7)(lightningcss@1.30.2)(sugarss@5.0.1(postcss@8.5.6))(terser@5.46.0)(tsx@4.21.0)(yaml@2.8.2))(webpack@5.104.1(@swc/core@1.13.5)(esbuild@0.27.2))':
+  '@storybook/addon-docs@10.2.3(@types/react@19.2.7)(esbuild@0.27.2)(rollup@4.57.1)(storybook@10.2.3(@testing-library/dom@10.4.1)(prettier@3.7.4)(react-dom@19.2.4(react@19.2.4))(react@19.2.4))(vite@7.3.1(@types/node@25.1.0)(jiti@2.6.1)(lightningcss@1.30.2)(sugarss@5.0.1(postcss@8.5.6))(terser@5.46.0)(tsx@4.21.0)(yaml@2.8.2))(webpack@5.104.1(@swc/core@1.13.5)(esbuild@0.27.2))':
     dependencies:
       '@mdx-js/react': 3.1.1(@types/react@19.2.7)(react@19.2.4)
-      '@storybook/csf-plugin': 10.2.3(esbuild@0.27.2)(rollup@4.57.1)(storybook@10.2.3(@testing-library/dom@10.4.1)(prettier@3.7.4)(react-dom@19.2.4(react@19.2.4))(react@19.2.4))(vite@7.3.1(@types/node@25.1.0)(jiti@1.21.7)(lightningcss@1.30.2)(sugarss@5.0.1(postcss@8.5.6))(terser@5.46.0)(tsx@4.21.0)(yaml@2.8.2))(webpack@5.104.1(@swc/core@1.13.5)(esbuild@0.27.2))
+      '@storybook/csf-plugin': 10.2.3(esbuild@0.27.2)(rollup@4.57.1)(storybook@10.2.3(@testing-library/dom@10.4.1)(prettier@3.7.4)(react-dom@19.2.4(react@19.2.4))(react@19.2.4))(vite@7.3.1(@types/node@25.1.0)(jiti@2.6.1)(lightningcss@1.30.2)(sugarss@5.0.1(postcss@8.5.6))(terser@5.46.0)(tsx@4.21.0)(yaml@2.8.2))(webpack@5.104.1(@swc/core@1.13.5)(esbuild@0.27.2))
       '@storybook/icons': 2.0.1(react-dom@19.2.4(react@19.2.4))(react@19.2.4)
       '@storybook/react-dom-shim': 10.2.3(react-dom@19.2.4(react@19.2.4))(react@19.2.4)(storybook@10.2.3(@testing-library/dom@10.4.1)(prettier@3.7.4)(react-dom@19.2.4(react@19.2.4))(react@19.2.4))
       react: 19.2.4
@@ -17143,14 +17169,14 @@ snapshots:
       storybook: 10.2.3(@testing-library/dom@10.4.1)(prettier@3.7.4)(react-dom@19.2.4(react@19.2.4))(react@19.2.4)
       ts-dedent: 2.2.0
 
-  '@storybook/csf-plugin@10.2.3(esbuild@0.27.2)(rollup@4.57.1)(storybook@10.2.3(@testing-library/dom@10.4.1)(prettier@3.7.4)(react-dom@19.2.4(react@19.2.4))(react@19.2.4))(vite@7.3.1(@types/node@25.1.0)(jiti@1.21.7)(lightningcss@1.30.2)(sugarss@5.0.1(postcss@8.5.6))(terser@5.46.0)(tsx@4.21.0)(yaml@2.8.2))(webpack@5.104.1(@swc/core@1.13.5)(esbuild@0.27.2))':
+  '@storybook/csf-plugin@10.2.3(esbuild@0.27.2)(rollup@4.57.1)(storybook@10.2.3(@testing-library/dom@10.4.1)(prettier@3.7.4)(react-dom@19.2.4(react@19.2.4))(react@19.2.4))(vite@7.3.1(@types/node@25.1.0)(jiti@2.6.1)(lightningcss@1.30.2)(sugarss@5.0.1(postcss@8.5.6))(terser@5.46.0)(tsx@4.21.0)(yaml@2.8.2))(webpack@5.104.1(@swc/core@1.13.5)(esbuild@0.27.2))':
     dependencies:
       storybook: 10.2.3(@testing-library/dom@10.4.1)(prettier@3.7.4)(react-dom@19.2.4(react@19.2.4))(react@19.2.4)
       unplugin: 2.3.11
     optionalDependencies:
       esbuild: 0.27.2
       rollup: 4.57.1
-      vite: 7.3.1(@types/node@25.1.0)(jiti@1.21.7)(lightningcss@1.30.2)(sugarss@5.0.1(postcss@8.5.6))(terser@5.46.0)(tsx@4.21.0)(yaml@2.8.2)
+      vite: 7.3.1(@types/node@25.1.0)(jiti@2.6.1)(lightningcss@1.30.2)(sugarss@5.0.1(postcss@8.5.6))(terser@5.46.0)(tsx@4.21.0)(yaml@2.8.2)
       webpack: 5.104.1(@swc/core@1.13.5)(esbuild@0.27.2)
 
   '@storybook/global@5.0.0': {}
@@ -17378,12 +17404,12 @@ snapshots:
       tailwindcss: 4.1.18
       vite: 5.4.21(@types/node@20.19.28)(lightningcss@1.30.2)(sugarss@5.0.1(postcss@8.5.6))(terser@5.46.0)
 
-  '@tailwindcss/vite@4.1.18(vite@7.3.1(@types/node@20.19.28)(jiti@2.6.1)(lightningcss@1.30.2)(sugarss@5.0.1(postcss@8.5.6))(terser@5.46.0)(tsx@4.21.0)(yaml@2.8.2))':
+  '@tailwindcss/vite@4.1.18(vite@7.3.1(@types/node@25.1.0)(jiti@2.6.1)(lightningcss@1.30.2)(sugarss@5.0.1(postcss@8.5.6))(terser@5.46.0)(tsx@4.21.0)(yaml@2.8.2))':
     dependencies:
       '@tailwindcss/node': 4.1.18
       '@tailwindcss/oxide': 4.1.18
       tailwindcss: 4.1.18
-      vite: 7.3.1(@types/node@20.19.28)(jiti@2.6.1)(lightningcss@1.30.2)(sugarss@5.0.1(postcss@8.5.6))(terser@5.46.0)(tsx@4.21.0)(yaml@2.8.2)
+      vite: 7.3.1(@types/node@25.1.0)(jiti@2.6.1)(lightningcss@1.30.2)(sugarss@5.0.1(postcss@8.5.6))(terser@5.46.0)(tsx@4.21.0)(yaml@2.8.2)
 
   '@tanstack/history@1.145.7': {}
 
@@ -17639,15 +17665,15 @@ snapshots:
     transitivePeerDependencies:
       - supports-color
 
-  '@typescript-eslint/eslint-plugin@8.54.0(@typescript-eslint/parser@8.54.0(eslint@9.39.2(jiti@1.21.7))(typescript@5.9.3))(eslint@9.39.2(jiti@1.21.7))(typescript@5.9.3)':
+  '@typescript-eslint/eslint-plugin@8.54.0(@typescript-eslint/parser@8.54.0(eslint@9.39.2(jiti@2.6.1))(typescript@5.9.3))(eslint@9.39.2(jiti@2.6.1))(typescript@5.9.3)':
     dependencies:
       '@eslint-community/regexpp': 4.12.2
-      '@typescript-eslint/parser': 8.54.0(eslint@9.39.2(jiti@1.21.7))(typescript@5.9.3)
+      '@typescript-eslint/parser': 8.54.0(eslint@9.39.2(jiti@2.6.1))(typescript@5.9.3)
       '@typescript-eslint/scope-manager': 8.54.0
-      '@typescript-eslint/type-utils': 8.54.0(eslint@9.39.2(jiti@1.21.7))(typescript@5.9.3)
-      '@typescript-eslint/utils': 8.54.0(eslint@9.39.2(jiti@1.21.7))(typescript@5.9.3)
+      '@typescript-eslint/type-utils': 8.54.0(eslint@9.39.2(jiti@2.6.1))(typescript@5.9.3)
+      '@typescript-eslint/utils': 8.54.0(eslint@9.39.2(jiti@2.6.1))(typescript@5.9.3)
       '@typescript-eslint/visitor-keys': 8.54.0
-      eslint: 9.39.2(jiti@1.21.7)
+      eslint: 9.39.2(jiti@2.6.1)
       ignore: 7.0.5
       natural-compare: 1.4.0
       ts-api-utils: 2.4.0(typescript@5.9.3)
@@ -17667,14 +17693,14 @@ snapshots:
     transitivePeerDependencies:
       - supports-color
 
-  '@typescript-eslint/parser@8.54.0(eslint@9.39.2(jiti@1.21.7))(typescript@5.9.3)':
+  '@typescript-eslint/parser@8.54.0(eslint@9.39.2(jiti@2.6.1))(typescript@5.9.3)':
     dependencies:
       '@typescript-eslint/scope-manager': 8.54.0
       '@typescript-eslint/types': 8.54.0
       '@typescript-eslint/typescript-estree': 8.54.0(typescript@5.9.3)
       '@typescript-eslint/visitor-keys': 8.54.0
       debug: 4.4.3
-      eslint: 9.39.2(jiti@1.21.7)
+      eslint: 9.39.2(jiti@2.6.1)
       typescript: 5.9.3
     transitivePeerDependencies:
       - supports-color
@@ -17727,13 +17753,13 @@ snapshots:
     transitivePeerDependencies:
       - supports-color
 
-  '@typescript-eslint/type-utils@8.54.0(eslint@9.39.2(jiti@1.21.7))(typescript@5.9.3)':
+  '@typescript-eslint/type-utils@8.54.0(eslint@9.39.2(jiti@2.6.1))(typescript@5.9.3)':
     dependencies:
       '@typescript-eslint/types': 8.54.0
       '@typescript-eslint/typescript-estree': 8.54.0(typescript@5.9.3)
-      '@typescript-eslint/utils': 8.54.0(eslint@9.39.2(jiti@1.21.7))(typescript@5.9.3)
+      '@typescript-eslint/utils': 8.54.0(eslint@9.39.2(jiti@2.6.1))(typescript@5.9.3)
       debug: 4.4.3
-      eslint: 9.39.2(jiti@1.21.7)
+      eslint: 9.39.2(jiti@2.6.1)
       ts-api-utils: 2.4.0(typescript@5.9.3)
       typescript: 5.9.3
     transitivePeerDependencies:
@@ -17784,13 +17810,13 @@ snapshots:
     transitivePeerDependencies:
       - supports-color
 
-  '@typescript-eslint/utils@8.54.0(eslint@9.39.2(jiti@1.21.7))(typescript@5.9.3)':
+  '@typescript-eslint/utils@8.54.0(eslint@9.39.2(jiti@2.6.1))(typescript@5.9.3)':
     dependencies:
-      '@eslint-community/eslint-utils': 4.9.1(eslint@9.39.2(jiti@1.21.7))
+      '@eslint-community/eslint-utils': 4.9.1(eslint@9.39.2(jiti@2.6.1))
       '@typescript-eslint/scope-manager': 8.54.0
       '@typescript-eslint/types': 8.54.0
       '@typescript-eslint/typescript-estree': 8.54.0(typescript@5.9.3)
-      eslint: 9.39.2(jiti@1.21.7)
+      eslint: 9.39.2(jiti@2.6.1)
       typescript: 5.9.3
     transitivePeerDependencies:
       - supports-color
@@ -17888,7 +17914,7 @@ snapshots:
     transitivePeerDependencies:
       - supports-color
 
-  '@vitejs/plugin-react@4.7.0(vite@7.3.1(@types/node@25.1.0)(jiti@1.21.7)(lightningcss@1.30.2)(sugarss@5.0.1(postcss@8.5.6))(terser@5.46.0)(tsx@4.21.0)(yaml@2.8.2))':
+  '@vitejs/plugin-react@4.7.0(vite@7.3.1(@types/node@25.1.0)(jiti@2.6.1)(lightningcss@1.30.2)(sugarss@5.0.1(postcss@8.5.6))(terser@5.46.0)(tsx@4.21.0)(yaml@2.8.2))':
     dependencies:
       '@babel/core': 7.28.6
       '@babel/plugin-transform-react-jsx-self': 7.27.1(@babel/core@7.28.6)
@@ -17896,7 +17922,7 @@ snapshots:
       '@rolldown/pluginutils': 1.0.0-beta.27
       '@types/babel__core': 7.20.5
       react-refresh: 0.17.0
-      vite: 7.3.1(@types/node@25.1.0)(jiti@1.21.7)(lightningcss@1.30.2)(sugarss@5.0.1(postcss@8.5.6))(terser@5.46.0)(tsx@4.21.0)(yaml@2.8.2)
+      vite: 7.3.1(@types/node@25.1.0)(jiti@2.6.1)(lightningcss@1.30.2)(sugarss@5.0.1(postcss@8.5.6))(terser@5.46.0)(tsx@4.21.0)(yaml@2.8.2)
     transitivePeerDependencies:
       - supports-color
 
@@ -17917,13 +17943,13 @@ snapshots:
       chai: 6.2.2
       tinyrainbow: 3.0.3
 
-  '@vitest/mocker@4.0.18(vite@7.3.1(@types/node@25.1.0)(jiti@1.21.7)(lightningcss@1.30.2)(sugarss@5.0.1(postcss@8.5.6))(terser@5.46.0)(tsx@4.21.0)(yaml@2.8.2))':
+  '@vitest/mocker@4.0.18(vite@7.3.1(@types/node@25.1.0)(jiti@2.6.1)(lightningcss@1.30.2)(sugarss@5.0.1(postcss@8.5.6))(terser@5.46.0)(tsx@4.21.0)(yaml@2.8.2))':
     dependencies:
       '@vitest/spy': 4.0.18
       estree-walker: 3.0.3
       magic-string: 0.30.21
     optionalDependencies:
-      vite: 7.3.1(@types/node@25.1.0)(jiti@1.21.7)(lightningcss@1.30.2)(sugarss@5.0.1(postcss@8.5.6))(terser@5.46.0)(tsx@4.21.0)(yaml@2.8.2)
+      vite: 7.3.1(@types/node@25.1.0)(jiti@2.6.1)(lightningcss@1.30.2)(sugarss@5.0.1(postcss@8.5.6))(terser@5.46.0)(tsx@4.21.0)(yaml@2.8.2)
 
   '@vitest/pretty-format@3.2.4':
     dependencies:
@@ -17959,7 +17985,7 @@ snapshots:
       sirv: 3.0.2
       tinyglobby: 0.2.15
       tinyrainbow: 3.0.3
-      vitest: 4.0.18(@opentelemetry/api@1.9.0)(@types/node@25.1.0)(@vitest/ui@4.0.18)(happy-dom@20.4.0)(jiti@1.21.7)(jsdom@27.4.0(@noble/hashes@1.8.0))(lightningcss@1.30.2)(sugarss@5.0.1(postcss@8.5.6))(terser@5.46.0)(tsx@4.21.0)(yaml@2.8.2)
+      vitest: 4.0.18(@opentelemetry/api@1.9.0)(@types/node@25.1.0)(@vitest/ui@4.0.18)(happy-dom@20.4.0)(jiti@2.6.1)(jsdom@27.4.0(@noble/hashes@1.8.0))(lightningcss@1.30.2)(sugarss@5.0.1(postcss@8.5.6))(terser@5.46.0)(tsx@4.21.0)(yaml@2.8.2)
 
   '@vitest/utils@3.2.4':
     dependencies:
@@ -19175,7 +19201,7 @@ snapshots:
       eslint: 9.39.2(jiti@2.6.1)
       eslint-import-resolver-node: 0.3.9
       eslint-import-resolver-typescript: 3.10.1(eslint-plugin-import@2.32.0(@typescript-eslint/parser@8.52.0(eslint@9.39.2(jiti@2.6.1))(typescript@5.9.3))(eslint@9.39.2(jiti@2.6.1)))(eslint@9.39.2(jiti@2.6.1))
-      eslint-plugin-import: 2.32.0(@typescript-eslint/parser@8.52.0(eslint@9.39.2(jiti@2.6.1))(typescript@5.9.3))(eslint-import-resolver-typescript@3.10.1(eslint-plugin-import@2.32.0(@typescript-eslint/parser@8.52.0(eslint@9.39.2(jiti@2.6.1))(typescript@5.9.3))(eslint@9.39.2(jiti@2.6.1)))(eslint@9.39.2(jiti@2.6.1)))(eslint@9.39.2(jiti@2.6.1))
+      eslint-plugin-import: 2.32.0(@typescript-eslint/parser@8.52.0(eslint@9.39.2(jiti@2.6.1))(typescript@5.9.3))(eslint-import-resolver-typescript@3.10.1)(eslint@9.39.2(jiti@2.6.1))
       eslint-plugin-jsx-a11y: 6.10.2(eslint@9.39.2(jiti@2.6.1))
       eslint-plugin-react: 7.37.5(eslint@9.39.2(jiti@2.6.1))
       eslint-plugin-react-hooks: 7.0.1(eslint@9.39.2(jiti@2.6.1))
@@ -19208,7 +19234,7 @@ snapshots:
       tinyglobby: 0.2.15
       unrs-resolver: 1.11.1
     optionalDependencies:
-      eslint-plugin-import: 2.32.0(@typescript-eslint/parser@8.52.0(eslint@9.39.2(jiti@2.6.1))(typescript@5.9.3))(eslint-import-resolver-typescript@3.10.1(eslint-plugin-import@2.32.0(@typescript-eslint/parser@8.52.0(eslint@9.39.2(jiti@2.6.1))(typescript@5.9.3))(eslint@9.39.2(jiti@2.6.1)))(eslint@9.39.2(jiti@2.6.1)))(eslint@9.39.2(jiti@2.6.1))
+      eslint-plugin-import: 2.32.0(@typescript-eslint/parser@8.52.0(eslint@9.39.2(jiti@2.6.1))(typescript@5.9.3))(eslint-import-resolver-typescript@3.10.1)(eslint@9.39.2(jiti@2.6.1))
     transitivePeerDependencies:
       - supports-color
 
@@ -19223,7 +19249,7 @@ snapshots:
     transitivePeerDependencies:
       - supports-color
 
-  eslint-plugin-import@2.32.0(@typescript-eslint/parser@8.52.0(eslint@9.39.2(jiti@2.6.1))(typescript@5.9.3))(eslint-import-resolver-typescript@3.10.1(eslint-plugin-import@2.32.0(@typescript-eslint/parser@8.52.0(eslint@9.39.2(jiti@2.6.1))(typescript@5.9.3))(eslint@9.39.2(jiti@2.6.1)))(eslint@9.39.2(jiti@2.6.1)))(eslint@9.39.2(jiti@2.6.1)):
+  eslint-plugin-import@2.32.0(@typescript-eslint/parser@8.52.0(eslint@9.39.2(jiti@2.6.1))(typescript@5.9.3))(eslint-import-resolver-typescript@3.10.1)(eslint@9.39.2(jiti@2.6.1)):
     dependencies:
       '@rtsao/scc': 1.1.0
       array-includes: 3.1.9
@@ -19304,10 +19330,10 @@ snapshots:
       string.prototype.matchall: 4.0.12
       string.prototype.repeat: 1.0.0
 
-  eslint-plugin-storybook@10.2.3(eslint@9.39.2(jiti@1.21.7))(storybook@10.2.3(@testing-library/dom@10.4.1)(prettier@3.7.4)(react-dom@19.2.4(react@19.2.4))(react@19.2.4))(typescript@5.9.3):
+  eslint-plugin-storybook@10.2.3(eslint@9.39.2(jiti@2.6.1))(storybook@10.2.3(@testing-library/dom@10.4.1)(prettier@3.7.4)(react-dom@19.2.4(react@19.2.4))(react@19.2.4))(typescript@5.9.3):
     dependencies:
-      '@typescript-eslint/utils': 8.54.0(eslint@9.39.2(jiti@1.21.7))(typescript@5.9.3)
-      eslint: 9.39.2(jiti@1.21.7)
+      '@typescript-eslint/utils': 8.54.0(eslint@9.39.2(jiti@2.6.1))(typescript@5.9.3)
+      eslint: 9.39.2(jiti@2.6.1)
       storybook: 10.2.3(@testing-library/dom@10.4.1)(prettier@3.7.4)(react-dom@19.2.4(react@19.2.4))(react@19.2.4)
     transitivePeerDependencies:
       - supports-color
@@ -19327,47 +19353,6 @@ snapshots:
 
   eslint-visitor-keys@4.2.1: {}
 
-  eslint@9.39.2(jiti@1.21.7):
-    dependencies:
-      '@eslint-community/eslint-utils': 4.9.1(eslint@9.39.2(jiti@1.21.7))
-      '@eslint-community/regexpp': 4.12.2
-      '@eslint/config-array': 0.21.1
-      '@eslint/config-helpers': 0.4.2
-      '@eslint/core': 0.17.0
-      '@eslint/eslintrc': 3.3.3
-      '@eslint/js': 9.39.2
-      '@eslint/plugin-kit': 0.4.1
-      '@humanfs/node': 0.16.7
-      '@humanwhocodes/module-importer': 1.0.1
-      '@humanwhocodes/retry': 0.4.3
-      '@types/estree': 1.0.8
-      ajv: 6.12.6
-      chalk: 4.1.2
-      cross-spawn: 7.0.6
-      debug: 4.4.3
-      escape-string-regexp: 4.0.0
-      eslint-scope: 8.4.0
-      eslint-visitor-keys: 4.2.1
-      espree: 10.4.0
-      esquery: 1.7.0
-      esutils: 2.0.3
-      fast-deep-equal: 3.1.3
-      file-entry-cache: 8.0.0
-      find-up: 5.0.0
-      glob-parent: 6.0.2
-      ignore: 5.3.2
-      imurmurhash: 0.1.4
-      is-glob: 4.0.3
-      json-stable-stringify-without-jsonify: 1.0.1
-      lodash.merge: 4.6.2
-      minimatch: 3.1.2
-      natural-compare: 1.4.0
-      optionator: 0.9.4
-    optionalDependencies:
-      jiti: 1.21.7
-    transitivePeerDependencies:
-      - supports-color
-
   eslint@9.39.2(jiti@2.6.1):
     dependencies:
       '@eslint-community/eslint-utils': 4.9.1(eslint@9.39.2(jiti@2.6.1))
@@ -20455,7 +20440,7 @@ snapshots:
       - '@types/react-dom'
       - vite
 
-  localflare-dashboard@0.1.2(@types/react-dom@19.2.3(@types/react@19.2.7))(@types/react@19.2.7)(vite@7.3.1(@types/node@20.19.28)(jiti@2.6.1)(lightningcss@1.30.2)(sugarss@5.0.1(postcss@8.5.6))(terser@5.46.0)(tsx@4.21.0)(yaml@2.8.2)):
+  localflare-dashboard@0.1.2(@types/react-dom@19.2.3(@types/react@19.2.7))(@types/react@19.2.7)(vite@7.3.1(@types/node@25.1.0)(jiti@2.6.1)(lightningcss@1.30.2)(sugarss@5.0.1(postcss@8.5.6))(terser@5.46.0)(tsx@4.21.0)(yaml@2.8.2)):
     dependencies:
       '@base-ui/react': 1.0.0(@types/react@19.2.7)(react-dom@19.2.4(react@19.2.4))(react@19.2.4)
       '@fontsource-variable/figtree': 5.2.10
@@ -20466,7 +20451,7 @@ snapshots:
       '@radix-ui/react-select': 2.2.6(@types/react-dom@19.2.3(@types/react@19.2.7))(@types/react@19.2.7)(react-dom@19.2.4(react@19.2.4))(react@19.2.4)
       '@radix-ui/react-slot': 1.2.3(@types/react@19.2.7)(react@19.2.4)
       '@radix-ui/react-tabs': 1.1.13(@types/react-dom@19.2.3(@types/react@19.2.7))(@types/react@19.2.7)(react-dom@19.2.4(react@19.2.4))(react@19.2.4)
-      '@tailwindcss/vite': 4.1.18(vite@7.3.1(@types/node@20.19.28)(jiti@2.6.1)(lightningcss@1.30.2)(sugarss@5.0.1(postcss@8.5.6))(terser@5.46.0)(tsx@4.21.0)(yaml@2.8.2))
+      '@tailwindcss/vite': 4.1.18(vite@7.3.1(@types/node@25.1.0)(jiti@2.6.1)(lightningcss@1.30.2)(sugarss@5.0.1(postcss@8.5.6))(terser@5.46.0)(tsx@4.21.0)(yaml@2.8.2))
       '@tanstack/react-query': 5.90.16(react@19.2.4)
       '@tanstack/react-table': 8.21.3(react-dom@19.2.4(react@19.2.4))(react@19.2.4)
       class-variance-authority: 0.7.1
@@ -20506,11 +20491,11 @@ snapshots:
       - utf-8-validate
       - vite
 
-  localflare@0.1.2(@types/react-dom@19.2.3(@types/react@19.2.7))(@types/react@19.2.7)(vite@7.3.1(@types/node@20.19.28)(jiti@2.6.1)(lightningcss@1.30.2)(sugarss@5.0.1(postcss@8.5.6))(terser@5.46.0)(tsx@4.21.0)(yaml@2.8.2)):
+  localflare@0.1.2(@types/react-dom@19.2.3(@types/react@19.2.7))(@types/react@19.2.7)(vite@7.3.1(@types/node@25.1.0)(jiti@2.6.1)(lightningcss@1.30.2)(sugarss@5.0.1(postcss@8.5.6))(terser@5.46.0)(tsx@4.21.0)(yaml@2.8.2)):
     dependencies:
       cac: 6.7.14
       localflare-core: 0.1.2
-      localflare-dashboard: 0.1.2(@types/react-dom@19.2.3(@types/react@19.2.7))(@types/react@19.2.7)(vite@7.3.1(@types/node@20.19.28)(jiti@2.6.1)(lightningcss@1.30.2)(sugarss@5.0.1(postcss@8.5.6))(terser@5.46.0)(tsx@4.21.0)(yaml@2.8.2))
+      localflare-dashboard: 0.1.2(@types/react-dom@19.2.3(@types/react@19.2.7))(@types/react@19.2.7)(vite@7.3.1(@types/node@25.1.0)(jiti@2.6.1)(lightningcss@1.30.2)(sugarss@5.0.1(postcss@8.5.6))(terser@5.46.0)(tsx@4.21.0)(yaml@2.8.2))
       localflare-server: 0.1.2
       picocolors: 1.1.1
     transitivePeerDependencies:
@@ -22362,35 +22347,6 @@ snapshots:
 
   tslib@2.8.1: {}
 
-  tsup@8.5.1(@swc/core@1.13.5)(jiti@1.21.7)(postcss@8.5.6)(tsx@4.21.0)(typescript@5.9.3)(yaml@2.8.2):
-    dependencies:
-      bundle-require: 5.1.0(esbuild@0.27.2)
-      cac: 6.7.14
-      chokidar: 4.0.3
-      consola: 3.4.2
-      debug: 4.4.3
-      esbuild: 0.27.2
-      fix-dts-default-cjs-exports: 1.0.1
-      joycon: 3.1.1
-      picocolors: 1.1.1
-      postcss-load-config: 6.0.1(jiti@1.21.7)(postcss@8.5.6)(tsx@4.21.0)(yaml@2.8.2)
-      resolve-from: 5.0.0
-      rollup: 4.57.1
-      source-map: 0.7.6
-      sucrase: 3.35.1
-      tinyexec: 0.3.2
-      tinyglobby: 0.2.15
-      tree-kill: 1.2.2
-    optionalDependencies:
-      '@swc/core': 1.13.5
-      postcss: 8.5.6
-      typescript: 5.9.3
-    transitivePeerDependencies:
-      - jiti
-      - supports-color
-      - tsx
-      - yaml
-
   tsup@8.5.1(@swc/core@1.13.5)(jiti@2.6.1)(postcss@8.5.6)(tsx@4.21.0)(typescript@5.9.3)(yaml@2.8.2):
     dependencies:
       bundle-require: 5.1.0(esbuild@0.27.2)
@@ -22707,24 +22663,6 @@ snapshots:
       tsx: 4.21.0
       yaml: 2.8.2
 
-  vite@7.3.1(@types/node@25.1.0)(jiti@1.21.7)(lightningcss@1.30.2)(sugarss@5.0.1(postcss@8.5.6))(terser@5.46.0)(tsx@4.21.0)(yaml@2.8.2):
-    dependencies:
-      esbuild: 0.27.2
-      fdir: 6.5.0(picomatch@4.0.3)
-      picomatch: 4.0.3
-      postcss: 8.5.6
-      rollup: 4.57.1
-      tinyglobby: 0.2.15
-    optionalDependencies:
-      '@types/node': 25.1.0
-      fsevents: 2.3.3
-      jiti: 1.21.7
-      lightningcss: 1.30.2
-      sugarss: 5.0.1(postcss@8.5.6)
-      terser: 5.46.0
-      tsx: 4.21.0
-      yaml: 2.8.2
-
   vite@7.3.1(@types/node@25.1.0)(jiti@2.6.1)(lightningcss@1.30.2)(sugarss@5.0.1(postcss@8.5.6))(terser@5.46.0)(tsx@4.21.0)(yaml@2.8.2):
     dependencies:
       esbuild: 0.27.2
@@ -22746,7 +22684,7 @@ snapshots:
   vitest@4.0.18(@opentelemetry/api@1.9.0)(@types/node@20.19.28)(@vitest/ui@4.0.18)(happy-dom@20.4.0)(jiti@2.6.1)(jsdom@27.4.0(@noble/hashes@1.8.0))(lightningcss@1.30.2)(sugarss@5.0.1(postcss@8.5.6))(terser@5.46.0)(tsx@4.21.0)(yaml@2.8.2):
     dependencies:
       '@vitest/expect': 4.0.18
-      '@vitest/mocker': 4.0.18(vite@7.3.1(@types/node@25.1.0)(jiti@1.21.7)(lightningcss@1.30.2)(sugarss@5.0.1(postcss@8.5.6))(terser@5.46.0)(tsx@4.21.0)(yaml@2.8.2))
+      '@vitest/mocker': 4.0.18(vite@7.3.1(@types/node@25.1.0)(jiti@2.6.1)(lightningcss@1.30.2)(sugarss@5.0.1(postcss@8.5.6))(terser@5.46.0)(tsx@4.21.0)(yaml@2.8.2))
       '@vitest/pretty-format': 4.0.18
       '@vitest/runner': 4.0.18
       '@vitest/snapshot': 4.0.18
@@ -22784,51 +22722,10 @@ snapshots:
       - tsx
       - yaml
 
-  vitest@4.0.18(@opentelemetry/api@1.9.0)(@types/node@25.1.0)(@vitest/ui@4.0.18)(happy-dom@20.4.0)(jiti@1.21.7)(jsdom@27.4.0(@noble/hashes@1.8.0))(lightningcss@1.30.2)(sugarss@5.0.1(postcss@8.5.6))(terser@5.46.0)(tsx@4.21.0)(yaml@2.8.2):
-    dependencies:
-      '@vitest/expect': 4.0.18
-      '@vitest/mocker': 4.0.18(vite@7.3.1(@types/node@25.1.0)(jiti@1.21.7)(lightningcss@1.30.2)(sugarss@5.0.1(postcss@8.5.6))(terser@5.46.0)(tsx@4.21.0)(yaml@2.8.2))
-      '@vitest/pretty-format': 4.0.18
-      '@vitest/runner': 4.0.18
-      '@vitest/snapshot': 4.0.18
-      '@vitest/spy': 4.0.18
-      '@vitest/utils': 4.0.18
-      es-module-lexer: 1.7.0
-      expect-type: 1.3.0
-      magic-string: 0.30.21
-      obug: 2.1.1
-      pathe: 2.0.3
-      picomatch: 4.0.3
-      std-env: 3.10.0
-      tinybench: 2.9.0
-      tinyexec: 1.0.2
-      tinyglobby: 0.2.15
-      tinyrainbow: 3.0.3
-      vite: 7.3.1(@types/node@25.1.0)(jiti@1.21.7)(lightningcss@1.30.2)(sugarss@5.0.1(postcss@8.5.6))(terser@5.46.0)(tsx@4.21.0)(yaml@2.8.2)
-      why-is-node-running: 2.3.0
-    optionalDependencies:
-      '@opentelemetry/api': 1.9.0
-      '@types/node': 25.1.0
-      '@vitest/ui': 4.0.18(vitest@4.0.18)
-      happy-dom: 20.4.0
-      jsdom: 27.4.0(@noble/hashes@1.8.0)
-    transitivePeerDependencies:
-      - jiti
-      - less
-      - lightningcss
-      - msw
-      - sass
-      - sass-embedded
-      - stylus
-      - sugarss
-      - terser
-      - tsx
-      - yaml
-
   vitest@4.0.18(@opentelemetry/api@1.9.0)(@types/node@25.1.0)(@vitest/ui@4.0.18)(happy-dom@20.4.0)(jiti@2.6.1)(jsdom@27.4.0(@noble/hashes@1.8.0))(lightningcss@1.30.2)(sugarss@5.0.1(postcss@8.5.6))(terser@5.46.0)(tsx@4.21.0)(yaml@2.8.2):
     dependencies:
       '@vitest/expect': 4.0.18
-      '@vitest/mocker': 4.0.18(vite@7.3.1(@types/node@25.1.0)(jiti@1.21.7)(lightningcss@1.30.2)(sugarss@5.0.1(postcss@8.5.6))(terser@5.46.0)(tsx@4.21.0)(yaml@2.8.2))
+      '@vitest/mocker': 4.0.18(vite@7.3.1(@types/node@25.1.0)(jiti@2.6.1)(lightningcss@1.30.2)(sugarss@5.0.1(postcss@8.5.6))(terser@5.46.0)(tsx@4.21.0)(yaml@2.8.2))
       '@vitest/pretty-format': 4.0.18
       '@vitest/runner': 4.0.18
       '@vitest/snapshot': 4.0.18

From bf5b208d5d4072e994ecd644c7a7fb589d58f338 Mon Sep 17 00:00:00 2001
From: "copilot-swe-agent[bot]" <198982749+Copilot@users.noreply.github.com>
Date: Tue, 31 Mar 2026 07:00:12 +0000
Subject: [PATCH 15/19] refactor: replace window.location.reload with
 queryClient.invalidateQueries, add error logging to seed handler

Agent-Logs-Url: https://github.com/thinkdj/ottabase/sessions/334c1a54-ae9a-4059-bed8-5e68ebd4db4b
---
 .../admin/homepage/AdminHomepageSectionsPage.tsx   | 14 ++++++++++----
 1 file changed, 10 insertions(+), 4 deletions(-)

diff --git a/apps/ottabase-template-app-tanstack/src/pages/admin/homepage/AdminHomepageSectionsPage.tsx b/apps/ottabase-template-app-tanstack/src/pages/admin/homepage/AdminHomepageSectionsPage.tsx
index 3137238cd..8fa1ca6e0 100644
--- a/apps/ottabase-template-app-tanstack/src/pages/admin/homepage/AdminHomepageSectionsPage.tsx
+++ b/apps/ottabase-template-app-tanstack/src/pages/admin/homepage/AdminHomepageSectionsPage.tsx
@@ -56,6 +56,7 @@ import {
     Plus,
     Trash2,
 } from 'lucide-react';
+import { useQueryClient } from '@tanstack/react-query';
 import { useCallback, useState } from 'react';
 import { HomepageAdminNav } from './HomepageAdminNav';
 import { ACTION_VARIANTS, SLOT_DESCRIPTIONS, SLOT_LABELS, SLOT_NAMES, type SlotName } from './homepage-constants';
@@ -309,6 +310,7 @@ function SectionActions({ sectionId }: { sectionId: string }) {
 // ── Main page ───────────────────────────────────────────────────────────────
 
 export function AdminHomepageSectionsPage() {
+    const queryClient = useQueryClient();
     const { data, isLoading } = homepageSectionHooks.useList(
         { orderBy: 'sortOrder', orderDirection: 'asc' },
         ADMIN_LIST_QUERY_CONFIG,
@@ -334,15 +336,19 @@ export function AdminHomepageSectionsPage() {
                 setSeedResult('exists');
             } else {
                 setSeedResult('success');
-                // Refetch sections after seed
-                window.location.reload();
+                // Invalidate all homepage queries to refetch fresh data
+                queryClient.invalidateQueries({ queryKey: ['homepage_sections'] });
+                queryClient.invalidateQueries({ queryKey: ['homepage_features'] });
+                queryClient.invalidateQueries({ queryKey: ['homepage_actions'] });
+                queryClient.invalidateQueries({ queryKey: ['homepage_display_settings'] });
             }
-        } catch {
+        } catch (err) {
+            console.error('[AdminHomepage] Seed failed:', err);
             setSeedResult('error');
         } finally {
             setSeeding(false);
         }
-    }, []);
+    }, [queryClient]);
 
     const handleCreateSection = async (slot: string) => {
         await createSection.mutateAsync({

From 5363681fb98bc3014ca47d439a5992ea763a6a41 Mon Sep 17 00:00:00 2001
From: Deepak Thomas <think.dj@gmail.com>
Date: Tue, 31 Mar 2026 13:44:32 +0530
Subject: [PATCH 16/19] Add homepage RLS policies and fix contentType filters

Introduce Row-Level Security configs for homepage models (sections, features, actions, display settings) and register them in DB init so homepage models are scoped and auditable. Provide defaults for optional EditorJS fields (time, version) when rendering Blocks to satisfy the expected data shape. Export ExposedPage type from the homepage contract. Simplify blog route queries to use BLOG_FEED_CONTENT_TYPES directly for where.contentType (remove the {$in: ...} wrapper) to match the expected query shape.
---
 .../app/page/[slug]/page-content.tsx          |  7 +++-
 .../lib/api.ts                                |  2 +-
 .../ottabase/models/homepagePolicy.ts         | 35 +++++++++++++++++++
 .../worker/lib/db-utils.ts                    | 10 ++++++
 .../worker/routes/blog.ts                     |  6 ++--
 5 files changed, 55 insertions(+), 5 deletions(-)
 create mode 100644 apps/ottabase-template-app-tanstack/ottabase/models/homepagePolicy.ts

diff --git a/apps/ottabase-template-app-nextjs-homepage/app/page/[slug]/page-content.tsx b/apps/ottabase-template-app-nextjs-homepage/app/page/[slug]/page-content.tsx
index 8d16b50f8..328ea62a3 100644
--- a/apps/ottabase-template-app-nextjs-homepage/app/page/[slug]/page-content.tsx
+++ b/apps/ottabase-template-app-nextjs-homepage/app/page/[slug]/page-content.tsx
@@ -29,7 +29,12 @@ export function PageContent({ page }: { page: PageData }) {
 
             {hasContent && (
                 <div className="prose prose-slate dark:prose-invert max-w-none">
-                    <Blocks data={page.content!} renderers={customRenderers} config={defaultEJSRConfigs} />
+                    {/* Provide defaults for optional EditorJS fields (time, version) required by DataProp */}
+                    <Blocks
+                        data={{ ...page.content!, time: page.content!.time ?? 0, version: page.content!.version ?? '' }}
+                        renderers={customRenderers}
+                        config={defaultEJSRConfigs}
+                    />
                 </div>
             )}
         </article>
diff --git a/apps/ottabase-template-app-nextjs-homepage/lib/api.ts b/apps/ottabase-template-app-nextjs-homepage/lib/api.ts
index d0b6a9b7e..131ab63bb 100644
--- a/apps/ottabase-template-app-nextjs-homepage/lib/api.ts
+++ b/apps/ottabase-template-app-nextjs-homepage/lib/api.ts
@@ -8,7 +8,7 @@
  * always agree on the payload shape.
  */
 
-import type { HomepageDataPayload } from '@ottabase/homepage-contract';
+import type { HomepageDataPayload, ExposedPage } from '@ottabase/homepage-contract';
 
 // Re-export shared contract types so existing imports continue to work
 export type {
diff --git a/apps/ottabase-template-app-tanstack/ottabase/models/homepagePolicy.ts b/apps/ottabase-template-app-tanstack/ottabase/models/homepagePolicy.ts
new file mode 100644
index 000000000..72c1749fe
--- /dev/null
+++ b/apps/ottabase-template-app-tanstack/ottabase/models/homepagePolicy.ts
@@ -0,0 +1,35 @@
+import type { ModelRLSConfig } from '@ottabase/ottaorm';
+import { RLSPolicies } from '@ottabase/ottaorm';
+
+/**
+ * Homepage models follow hierarchical (tenant + user + app) scoping.
+ * Admin users manage homepage content within their organization context.
+ */
+
+export const homepageSectionPolicy: ModelRLSConfig = {
+    model: 'homepage_sections',
+    policy: RLSPolicies.Hierarchical(false),
+    contextFields: ['organizationId', 'appId', 'userId'],
+    auditEnabled: true,
+};
+
+export const homepageFeaturePolicy: ModelRLSConfig = {
+    model: 'homepage_features',
+    policy: RLSPolicies.Hierarchical(false),
+    contextFields: ['organizationId', 'appId', 'userId'],
+    auditEnabled: true,
+};
+
+export const homepageActionPolicy: ModelRLSConfig = {
+    model: 'homepage_actions',
+    policy: RLSPolicies.Hierarchical(false),
+    contextFields: ['organizationId', 'appId', 'userId'],
+    auditEnabled: true,
+};
+
+export const homepageDisplaySettingsPolicy: ModelRLSConfig = {
+    model: 'homepage_display_settings',
+    policy: RLSPolicies.Hierarchical(false),
+    contextFields: ['organizationId', 'appId', 'userId'],
+    auditEnabled: true,
+};
diff --git a/apps/ottabase-template-app-tanstack/worker/lib/db-utils.ts b/apps/ottabase-template-app-tanstack/worker/lib/db-utils.ts
index aeb0d207f..aa016b536 100644
--- a/apps/ottabase-template-app-tanstack/worker/lib/db-utils.ts
+++ b/apps/ottabase-template-app-tanstack/worker/lib/db-utils.ts
@@ -39,6 +39,12 @@ import { errorResponse } from '@ottabase/utils/http-errors';
 import { getOttabaseConfig } from '../../ottabase/config.loader';
 import { ChangelogEntry } from '../../ottabase/models/ChangelogEntry';
 import { changelogPolicy } from '../../ottabase/models/changelogPolicy';
+import {
+    homepageSectionPolicy,
+    homepageFeaturePolicy,
+    homepageActionPolicy,
+    homepageDisplaySettingsPolicy,
+} from '../../ottabase/models/homepagePolicy';
 import { HomepageAction } from '../../ottabase/models/HomepageAction';
 import { HomepageDisplaySettings } from '../../ottabase/models/HomepageDisplaySettings';
 import { HomepageFeature } from '../../ottabase/models/HomepageFeature';
@@ -130,6 +136,10 @@ export function initDbConnection(env: CloudflareEnv): void {
     const brandModels = [BrandKit, LayoutTemplate, LayoutRouteMapping, MenuSlotAssignment];
     registerPolicy(mediaLibraryPolicy);
     registerPolicy(changelogPolicy);
+    registerPolicy(homepageSectionPolicy);
+    registerPolicy(homepageFeaturePolicy);
+    registerPolicy(homepageActionPolicy);
+    registerPolicy(homepageDisplaySettingsPolicy);
 
     const appModels = [Todo, ChangelogEntry, HomepageSection, HomepageFeature, HomepageAction, HomepageDisplaySettings];
 
diff --git a/apps/ottabase-template-app-tanstack/worker/routes/blog.ts b/apps/ottabase-template-app-tanstack/worker/routes/blog.ts
index a836d6e69..279f93eb2 100644
--- a/apps/ottabase-template-app-tanstack/worker/routes/blog.ts
+++ b/apps/ottabase-template-app-tanstack/worker/routes/blog.ts
@@ -248,7 +248,7 @@ export async function handleBlogPostsList(context: BlogRouteContext): Promise<Re
         where.contentType = contentType;
     } else {
         // Public blog feed: only show blog articles (exclude changelog + page)
-        where.contentType = { $in: BLOG_FEED_CONTENT_TYPES };
+        where.contentType = BLOG_FEED_CONTENT_TYPES;
     }
     if (seriesId) where.seriesId = seriesId;
 
@@ -594,7 +594,7 @@ export async function handleBlogRssFeed(context: BlogRouteContext): Promise<Resp
         where.contentType = contentType;
     } else {
         // Public RSS feed: only blog articles (exclude changelog + page)
-        where.contentType = { $in: BLOG_FEED_CONTENT_TYPES };
+        where.contentType = BLOG_FEED_CONTENT_TYPES;
     }
 
     const posts = await Post.where(where, {
@@ -680,7 +680,7 @@ export async function handleBlogSitemap(context: BlogRouteContext): Promise<Resp
 
     const appId = url.searchParams.get('appId') || null;
     // Sitemap: only blog articles (exclude changelog + page)
-    const where: Record<string, unknown> = { status: 'published', contentType: { $in: BLOG_FEED_CONTENT_TYPES } };
+    const where: Record<string, unknown> = { status: 'published', contentType: BLOG_FEED_CONTENT_TYPES };
     if (appId) where.appId = appId;
 
     const posts = await Post.where(where, {

From fed02da0258079658a9f6d95d3e926e87335d269 Mon Sep 17 00:00:00 2001
From: Deepak Thomas <think.dj@gmail.com>
Date: Tue, 31 Mar 2026 15:47:52 +0530
Subject: [PATCH 17/19] Add unified homepage admin builder

Introduce a single-page AdminHomepageBuilderPage to consolidate homepage editing (sections, features, actions, display settings) and remove legacy per-page admin UIs (AdminHomepageDisplayPage, AdminHomepagePagesPage, AdminHomepageSectionEditorPage, AdminHomepageSectionsPage, HomepageAdminNav).

Also tighten RLS for homepage models: homepage_sections, homepage_features, homepage_actions and homepage_display_settings are now configured with RLSPolicies.AdminOnly() and their contextFields cleared. Router/index and worker route/db utilities were updated to wire the new builder and related APIs.
---
 .../ottabase/models/homepagePolicy.ts         |  21 +-
 .../homepage/AdminHomepageBuilderPage.tsx     | 938 ++++++++++++++++++
 .../homepage/AdminHomepageDisplayPage.tsx     | 304 ------
 .../admin/homepage/AdminHomepagePagesPage.tsx | 187 ----
 .../AdminHomepageSectionEditorPage.tsx        | 788 ---------------
 .../homepage/AdminHomepageSectionsPage.tsx    | 650 ------------
 .../pages/admin/homepage/HomepageAdminNav.tsx |  52 -
 .../src/pages/admin/homepage/index.ts         |   6 +-
 .../src/router.tsx                            |  39 +-
 .../worker/lib/db-utils.ts                    |  14 +-
 .../worker/routes/homepage.ts                 |  13 +-
 11 files changed, 964 insertions(+), 2048 deletions(-)
 create mode 100644 apps/ottabase-template-app-tanstack/src/pages/admin/homepage/AdminHomepageBuilderPage.tsx
 delete mode 100644 apps/ottabase-template-app-tanstack/src/pages/admin/homepage/AdminHomepageDisplayPage.tsx
 delete mode 100644 apps/ottabase-template-app-tanstack/src/pages/admin/homepage/AdminHomepagePagesPage.tsx
 delete mode 100644 apps/ottabase-template-app-tanstack/src/pages/admin/homepage/AdminHomepageSectionEditorPage.tsx
 delete mode 100644 apps/ottabase-template-app-tanstack/src/pages/admin/homepage/AdminHomepageSectionsPage.tsx
 delete mode 100644 apps/ottabase-template-app-tanstack/src/pages/admin/homepage/HomepageAdminNav.tsx

diff --git a/apps/ottabase-template-app-tanstack/ottabase/models/homepagePolicy.ts b/apps/ottabase-template-app-tanstack/ottabase/models/homepagePolicy.ts
index 72c1749fe..d3bc03af0 100644
--- a/apps/ottabase-template-app-tanstack/ottabase/models/homepagePolicy.ts
+++ b/apps/ottabase-template-app-tanstack/ottabase/models/homepagePolicy.ts
@@ -2,34 +2,35 @@ import type { ModelRLSConfig } from '@ottabase/ottaorm';
 import { RLSPolicies } from '@ottabase/ottaorm';
 
 /**
- * Homepage models follow hierarchical (tenant + user + app) scoping.
- * Admin users manage homepage content within their organization context.
+ * Homepage RLS policies.
+ * Sections & display settings have an `appId` column → AppScoped.
+ * Features & actions are child records (linked via sectionId, no scope columns) → AdminOnly.
  */
 
 export const homepageSectionPolicy: ModelRLSConfig = {
     model: 'homepage_sections',
-    policy: RLSPolicies.Hierarchical(false),
-    contextFields: ['organizationId', 'appId', 'userId'],
+    policy: RLSPolicies.AdminOnly(),
+    contextFields: [],
     auditEnabled: true,
 };
 
 export const homepageFeaturePolicy: ModelRLSConfig = {
     model: 'homepage_features',
-    policy: RLSPolicies.Hierarchical(false),
-    contextFields: ['organizationId', 'appId', 'userId'],
+    policy: RLSPolicies.AdminOnly(),
+    contextFields: [],
     auditEnabled: true,
 };
 
 export const homepageActionPolicy: ModelRLSConfig = {
     model: 'homepage_actions',
-    policy: RLSPolicies.Hierarchical(false),
-    contextFields: ['organizationId', 'appId', 'userId'],
+    policy: RLSPolicies.AdminOnly(),
+    contextFields: [],
     auditEnabled: true,
 };
 
 export const homepageDisplaySettingsPolicy: ModelRLSConfig = {
     model: 'homepage_display_settings',
-    policy: RLSPolicies.Hierarchical(false),
-    contextFields: ['organizationId', 'appId', 'userId'],
+    policy: RLSPolicies.AdminOnly(),
+    contextFields: [],
     auditEnabled: true,
 };
diff --git a/apps/ottabase-template-app-tanstack/src/pages/admin/homepage/AdminHomepageBuilderPage.tsx b/apps/ottabase-template-app-tanstack/src/pages/admin/homepage/AdminHomepageBuilderPage.tsx
new file mode 100644
index 000000000..79ed649d7
--- /dev/null
+++ b/apps/ottabase-template-app-tanstack/src/pages/admin/homepage/AdminHomepageBuilderPage.tsx
@@ -0,0 +1,938 @@
+/**
+ * Admin Homepage Builder
+ *
+ * Unified single-page builder for managing the entire homepage.
+ * All slots, content, features, actions, and display settings in one place.
+ *
+ * Design principles:
+ * - One page, one mental model: "I'm editing my homepage"
+ * - Visual slot cards in layout order
+ * - Click to expand → edit everything inline
+ * - Settings collapsed at top (theme, SEO, CSS)
+ */
+import { ADMIN_LIST_QUERY_CONFIG } from '@/config/queryConfig';
+import {
+    homepageActionHooks,
+    homepageDisplaySettingsHooks,
+    homepageFeatureHooks,
+    homepageSectionHooks,
+    type HomepageActionRow,
+    type HomepageDisplaySettingsRow,
+    type HomepageFeatureRow,
+    type HomepageSectionRow,
+} from '@/hooks/homepageHooks';
+import {
+    Accordion,
+    AccordionContent,
+    AccordionItem,
+    AccordionTrigger,
+    Badge,
+    Button,
+    Card,
+    CardContent,
+    CardDescription,
+    CardHeader,
+    CardTitle,
+    Collapsible,
+    CollapsibleContent,
+    CollapsibleTrigger,
+    Input,
+    Label,
+    Select,
+    SelectContent,
+    SelectItem,
+    SelectTrigger,
+    SelectValue,
+    Separator,
+    Switch,
+    Textarea,
+    Tooltip,
+    TooltipContent,
+    TooltipProvider,
+    TooltipTrigger,
+} from '@ottabase/ui-shadcn';
+import { IconDatabaseImport } from '@tabler/icons-react';
+import {
+    ChevronDown,
+    ExternalLink,
+    FileText,
+    Grid3X3,
+    Home,
+    Layout,
+    Megaphone,
+    Navigation,
+    Palette,
+    Plus,
+    Rows3,
+    Save,
+    Settings,
+    Sparkles,
+    Trash2,
+} from 'lucide-react';
+import { useCallback, useEffect, useMemo, useState } from 'react';
+import {
+    ACTION_VARIANTS,
+    SLOT_CONFIG,
+    SLOT_DESCRIPTIONS,
+    SLOT_LABELS,
+    SLOT_NAMES,
+    THEME_PRESETS,
+    type SlotName,
+} from './homepage-constants';
+
+// ── Icon map for slots ──────────────────────────────────────────────────────
+
+const SLOT_ICON_MAP: Record<SlotName, React.FC<{ className?: string }>> = {
+    navbar: Navigation,
+    hero: Sparkles,
+    features: Grid3X3,
+    cta: Megaphone,
+    footer: Rows3,
+    about: FileText,
+};
+
+// ── Inline Feature Editor ───────────────────────────────────────────────────
+
+function FeatureEditor({
+    sectionId,
+    features,
+    onRefresh,
+}: {
+    sectionId: string;
+    features: HomepageFeatureRow[];
+    onRefresh: () => void;
+}) {
+    const createFeature = homepageFeatureHooks.useCreate();
+    const updateFeature = homepageFeatureHooks.useUpdate();
+    const deleteFeature = homepageFeatureHooks.useDelete();
+    const [adding, setAdding] = useState(false);
+    const [newTitle, setNewTitle] = useState('');
+    const [newDesc, setNewDesc] = useState('');
+    const [newIcon, setNewIcon] = useState('');
+
+    const handleAdd = async () => {
+        if (!newTitle.trim() || !newDesc.trim()) return;
+        await createFeature.mutateAsync({
+            sectionId,
+            title: newTitle.trim(),
+            description: newDesc.trim(),
+            icon: newIcon.trim() || undefined,
+            sortOrder: features.length,
+        });
+        setNewTitle('');
+        setNewDesc('');
+        setNewIcon('');
+        setAdding(false);
+        onRefresh();
+    };
+
+    const handleDelete = async (id: string) => {
+        await deleteFeature.mutateAsync(id);
+        onRefresh();
+    };
+
+    return (
+        <div className="space-y-3">
+            <div className="flex items-center justify-between">
+                <Label className="text-xs font-medium uppercase tracking-wider text-muted-foreground">
+                    Features ({features.length})
+                </Label>
+                <Button variant="ghost" size="sm" className="h-7 text-xs" onClick={() => setAdding(!adding)}>
+                    <Plus className="mr-1 h-3 w-3" />
+                    Add Feature
+                </Button>
+            </div>
+
+            {features.map((f) => (
+                <div key={f.id} className="flex items-start gap-3 rounded-md border bg-muted/30 p-3">
+                    {f.icon && (
+                        <Badge variant="secondary" className="shrink-0 font-mono text-[10px]">
+                            {f.icon}
+                        </Badge>
+                    )}
+                    <div className="min-w-0 flex-1">
+                        <p className="font-medium text-sm">{f.title}</p>
+                        <p className="text-xs text-muted-foreground">{f.description}</p>
+                    </div>
+                    <Button variant="ghost" size="icon" className="h-7 w-7 shrink-0" onClick={() => handleDelete(f.id)}>
+                        <Trash2 className="h-3.5 w-3.5 text-destructive" />
+                    </Button>
+                </div>
+            ))}
+
+            {adding && (
+                <div className="space-y-2 rounded-md border border-dashed p-3">
+                    <div className="flex gap-2">
+                        <Input
+                            placeholder="Feature title"
+                            value={newTitle}
+                            onChange={(e) => setNewTitle(e.target.value)}
+                            className="h-8 text-sm"
+                        />
+                        <Input
+                            placeholder="Icon (e.g. Zap)"
+                            value={newIcon}
+                            onChange={(e) => setNewIcon(e.target.value)}
+                            className="h-8 w-28 text-sm"
+                        />
+                    </div>
+                    <Textarea
+                        placeholder="Short description"
+                        value={newDesc}
+                        onChange={(e) => setNewDesc(e.target.value)}
+                        rows={2}
+                        className="text-sm"
+                    />
+                    <div className="flex gap-2">
+                        <Button
+                            size="sm"
+                            className="h-7 text-xs"
+                            onClick={handleAdd}
+                            disabled={createFeature.isPending}
+                        >
+                            Save
+                        </Button>
+                        <Button
+                            variant="ghost"
+                            size="sm"
+                            className="h-7 text-xs"
+                            onClick={() => {
+                                setAdding(false);
+                                setNewTitle('');
+                                setNewDesc('');
+                                setNewIcon('');
+                            }}
+                        >
+                            Cancel
+                        </Button>
+                    </div>
+                </div>
+            )}
+        </div>
+    );
+}
+
+// ── Inline Action Editor ────────────────────────────────────────────────────
+
+function ActionEditor({
+    sectionId,
+    actions,
+    onRefresh,
+}: {
+    sectionId: string;
+    actions: HomepageActionRow[];
+    onRefresh: () => void;
+}) {
+    const createAction = homepageActionHooks.useCreate();
+    const deleteAction = homepageActionHooks.useDelete();
+    const [adding, setAdding] = useState(false);
+    const [newLabel, setNewLabel] = useState('');
+    const [newHref, setNewHref] = useState('');
+    const [newVariant, setNewVariant] = useState('default');
+    const [newIcon, setNewIcon] = useState('');
+
+    const handleAdd = async () => {
+        if (!newLabel.trim() || !newHref.trim()) return;
+        await createAction.mutateAsync({
+            sectionId,
+            label: newLabel.trim(),
+            href: newHref.trim(),
+            variant: newVariant,
+            icon: newIcon.trim() || undefined,
+            sortOrder: actions.length,
+        });
+        setNewLabel('');
+        setNewHref('');
+        setNewVariant('default');
+        setNewIcon('');
+        setAdding(false);
+        onRefresh();
+    };
+
+    const handleDelete = async (id: string) => {
+        await deleteAction.mutateAsync(id);
+        onRefresh();
+    };
+
+    return (
+        <div className="space-y-3">
+            <div className="flex items-center justify-between">
+                <Label className="text-xs font-medium uppercase tracking-wider text-muted-foreground">
+                    Actions / Buttons ({actions.length})
+                </Label>
+                <Button variant="ghost" size="sm" className="h-7 text-xs" onClick={() => setAdding(!adding)}>
+                    <Plus className="mr-1 h-3 w-3" />
+                    Add Button
+                </Button>
+            </div>
+
+            {actions.map((a) => (
+                <div key={a.id} className="flex items-center gap-3 rounded-md border bg-muted/30 p-3">
+                    <Badge variant="outline" className="shrink-0 text-xs">
+                        {a.variant || 'default'}
+                    </Badge>
+                    <div className="min-w-0 flex-1">
+                        <p className="font-medium text-sm">{a.label}</p>
+                        <p className="text-xs text-muted-foreground truncate">{a.href}</p>
+                    </div>
+                    {a.icon && (
+                        <Badge variant="secondary" className="shrink-0 font-mono text-[10px]">
+                            {a.icon}
+                        </Badge>
+                    )}
+                    <Button variant="ghost" size="icon" className="h-7 w-7 shrink-0" onClick={() => handleDelete(a.id)}>
+                        <Trash2 className="h-3.5 w-3.5 text-destructive" />
+                    </Button>
+                </div>
+            ))}
+
+            {adding && (
+                <div className="space-y-2 rounded-md border border-dashed p-3">
+                    <div className="flex gap-2">
+                        <Input
+                            placeholder="Button label"
+                            value={newLabel}
+                            onChange={(e) => setNewLabel(e.target.value)}
+                            className="h-8 text-sm"
+                        />
+                        <Select value={newVariant} onValueChange={setNewVariant}>
+                            <SelectTrigger className="h-8 w-28 text-sm">
+                                <SelectValue />
+                            </SelectTrigger>
+                            <SelectContent>
+                                {ACTION_VARIANTS.map((v) => (
+                                    <SelectItem key={v.value} value={v.value}>
+                                        {v.label}
+                                    </SelectItem>
+                                ))}
+                            </SelectContent>
+                        </Select>
+                    </div>
+                    <div className="flex gap-2">
+                        <Input
+                            placeholder="URL (e.g. /docs or https://...)"
+                            value={newHref}
+                            onChange={(e) => setNewHref(e.target.value)}
+                            className="h-8 text-sm flex-1"
+                        />
+                        <Input
+                            placeholder="Icon"
+                            value={newIcon}
+                            onChange={(e) => setNewIcon(e.target.value)}
+                            className="h-8 w-24 text-sm"
+                        />
+                    </div>
+                    <div className="flex gap-2">
+                        <Button size="sm" className="h-7 text-xs" onClick={handleAdd} disabled={createAction.isPending}>
+                            Save
+                        </Button>
+                        <Button
+                            variant="ghost"
+                            size="sm"
+                            className="h-7 text-xs"
+                            onClick={() => {
+                                setAdding(false);
+                                setNewLabel('');
+                                setNewHref('');
+                                setNewVariant('default');
+                                setNewIcon('');
+                            }}
+                        >
+                            Cancel
+                        </Button>
+                    </div>
+                </div>
+            )}
+        </div>
+    );
+}
+
+// ── Slot Card Component ─────────────────────────────────────────────────────
+
+function SlotCard({
+    slot,
+    section,
+    features,
+    actions,
+    variantBySlot,
+    onSectionChange,
+    onVariantChange,
+    onRefresh,
+}: {
+    slot: SlotName;
+    section: HomepageSectionRow | null;
+    features: HomepageFeatureRow[];
+    actions: HomepageActionRow[];
+    variantBySlot: Record<string, string>;
+    onSectionChange: (slot: SlotName, field: string, value: unknown) => void;
+    onVariantChange: (slot: SlotName, variantId: string) => void;
+    onRefresh: () => void;
+}) {
+    const createSection = homepageSectionHooks.useCreate();
+    const updateSection = homepageSectionHooks.useUpdate();
+
+    const SlotIcon = SLOT_ICON_MAP[slot];
+    const config = SLOT_CONFIG[slot];
+    const currentVariant = variantBySlot[slot] || config.default;
+    const isEnabled = section?.enabled ?? true;
+
+    // Create section if it doesn't exist
+    const handleEnsureSection = async () => {
+        if (!section) {
+            await createSection.mutateAsync({
+                slot,
+                title: SLOT_LABELS[slot],
+                enabled: true,
+                sortOrder: SLOT_NAMES.indexOf(slot),
+            });
+            onRefresh();
+        }
+    };
+
+    // Update section field
+    const handleFieldChange = async (field: string, value: unknown) => {
+        if (!section) {
+            await handleEnsureSection();
+            return;
+        }
+        await updateSection.mutateAsync({ id: section.id, data: { [field]: value } });
+        onSectionChange(slot, field, value);
+    };
+
+    // Toggle enabled state
+    const handleToggleEnabled = async () => {
+        if (!section) {
+            await createSection.mutateAsync({
+                slot,
+                title: SLOT_LABELS[slot],
+                enabled: true,
+                sortOrder: SLOT_NAMES.indexOf(slot),
+            });
+            onRefresh();
+            return;
+        }
+        await updateSection.mutateAsync({ id: section.id, data: { enabled: !isEnabled } });
+        onRefresh();
+    };
+
+    return (
+        <AccordionItem value={slot} className="border rounded-lg">
+            <div className="flex items-center gap-3 px-4 py-3 [&:has([data-state=open])]:bg-muted/50">
+                <AccordionTrigger className="flex items-center gap-3 flex-1 hover:no-underline p-0 [&>svg:last-child]:hidden">
+                    <div className="flex items-center justify-center w-8 h-8 rounded-md bg-primary/10">
+                        <SlotIcon className="w-4 h-4 text-primary" />
+                    </div>
+                    <div className="flex-1 text-left">
+                        <div className="flex items-center gap-2">
+                            <span className="font-medium">{SLOT_LABELS[slot]}</span>
+                            {!isEnabled && (
+                                <Badge variant="secondary" className="text-[10px]">
+                                    Hidden
+                                </Badge>
+                            )}
+                        </div>
+                        <p className="text-xs text-muted-foreground">{SLOT_DESCRIPTIONS[slot]}</p>
+                    </div>
+                    <ChevronDown className="h-4 w-4 shrink-0 transition-transform duration-200 [[data-state=open]_&]:rotate-180" />
+                </AccordionTrigger>
+                <div className="flex items-center gap-2">
+                    <Select value={currentVariant} onValueChange={(v) => onVariantChange(slot, v)}>
+                        <SelectTrigger className="h-7 w-28 text-xs">
+                            <SelectValue />
+                        </SelectTrigger>
+                        <SelectContent>
+                            {config.variants.map((v) => (
+                                <SelectItem key={v.id} value={v.id}>
+                                    {v.label}
+                                </SelectItem>
+                            ))}
+                        </SelectContent>
+                    </Select>
+                    <TooltipProvider>
+                        <Tooltip>
+                            <TooltipTrigger asChild>
+                                <div>
+                                    <Switch
+                                        checked={isEnabled}
+                                        onCheckedChange={handleToggleEnabled}
+                                        className="data-[state=checked]:bg-green-500"
+                                    />
+                                </div>
+                            </TooltipTrigger>
+                            <TooltipContent>
+                                <p>{isEnabled ? 'Visible on homepage' : 'Hidden from homepage'}</p>
+                            </TooltipContent>
+                        </Tooltip>
+                    </TooltipProvider>
+                </div>
+            </div>
+            <AccordionContent className="px-4 pb-4">
+                <div className="space-y-4 pt-2">
+                    {/* Section Content Fields */}
+                    <div className="grid gap-4 sm:grid-cols-2">
+                        <div className="space-y-2">
+                            <Label htmlFor={`${slot}-title`} className="text-xs">
+                                Title
+                            </Label>
+                            <Input
+                                id={`${slot}-title`}
+                                value={section?.title || ''}
+                                onChange={(e) => handleFieldChange('title', e.target.value)}
+                                placeholder={`${SLOT_LABELS[slot]} title`}
+                                className="h-9"
+                            />
+                        </div>
+                        <div className="space-y-2">
+                            <Label htmlFor={`${slot}-icon`} className="text-xs">
+                                Icon (Lucide name)
+                            </Label>
+                            <Input
+                                id={`${slot}-icon`}
+                                value={section?.icon || ''}
+                                onChange={(e) => handleFieldChange('icon', e.target.value)}
+                                placeholder="e.g. Sparkles, Zap, Shield"
+                                className="h-9"
+                            />
+                        </div>
+                    </div>
+
+                    <div className="space-y-2">
+                        <Label htmlFor={`${slot}-subtitle`} className="text-xs">
+                            Subtitle
+                        </Label>
+                        <Input
+                            id={`${slot}-subtitle`}
+                            value={section?.subtitle || ''}
+                            onChange={(e) => handleFieldChange('subtitle', e.target.value)}
+                            placeholder="Short tagline or description"
+                            className="h-9"
+                        />
+                    </div>
+
+                    <div className="space-y-2">
+                        <Label htmlFor={`${slot}-body`} className="text-xs">
+                            Body Content
+                        </Label>
+                        <Textarea
+                            id={`${slot}-body`}
+                            value={section?.body || ''}
+                            onChange={(e) => handleFieldChange('body', e.target.value)}
+                            placeholder="Main content for this section (supports markdown)"
+                            rows={3}
+                        />
+                    </div>
+
+                    {/* Navbar-specific: GitHub URL */}
+                    {slot === 'navbar' && (
+                        <div className="space-y-2">
+                            <Label htmlFor={`${slot}-github`} className="text-xs">
+                                GitHub URL
+                            </Label>
+                            <Input
+                                id={`${slot}-github`}
+                                value={section?.githubUrl || ''}
+                                onChange={(e) => handleFieldChange('githubUrl', e.target.value)}
+                                placeholder="https://github.com/your-org/your-repo"
+                                className="h-9"
+                            />
+                        </div>
+                    )}
+
+                    <Separator />
+
+                    {/* Features (for features, about slots) */}
+                    {(slot === 'features' || slot === 'about') && section && (
+                        <FeatureEditor sectionId={section.id} features={features} onRefresh={onRefresh} />
+                    )}
+
+                    {/* Actions (for hero, cta, about slots) */}
+                    {(slot === 'hero' || slot === 'cta' || slot === 'about') && section && (
+                        <ActionEditor sectionId={section.id} actions={actions} onRefresh={onRefresh} />
+                    )}
+
+                    {/* Prompt to create section if none exists */}
+                    {!section && (
+                        <div className="text-center py-4">
+                            <p className="text-sm text-muted-foreground mb-2">This slot has no content yet.</p>
+                            <Button size="sm" onClick={handleEnsureSection}>
+                                <Plus className="mr-1 h-4 w-4" />
+                                Initialize Section
+                            </Button>
+                        </div>
+                    )}
+                </div>
+            </AccordionContent>
+        </AccordionItem>
+    );
+}
+
+// ── Main Builder Page ───────────────────────────────────────────────────────
+
+export function AdminHomepageBuilderPage() {
+    // Load all data
+    const {
+        data: sectionsData,
+        isLoading: sectionsLoading,
+        refetch: refetchSections,
+    } = homepageSectionHooks.useList({ orderBy: 'sortOrder', orderDirection: 'asc' }, ADMIN_LIST_QUERY_CONFIG);
+
+    const { data: featuresData, refetch: refetchFeatures } = homepageFeatureHooks.useList(
+        { orderBy: 'sortOrder', orderDirection: 'asc' },
+        ADMIN_LIST_QUERY_CONFIG,
+    );
+
+    const { data: actionsData, refetch: refetchActions } = homepageActionHooks.useList(
+        { orderBy: 'sortOrder', orderDirection: 'asc' },
+        ADMIN_LIST_QUERY_CONFIG,
+    );
+
+    const {
+        data: displayData,
+        isLoading: displayLoading,
+        refetch: refetchDisplay,
+    } = homepageDisplaySettingsHooks.useList({}, ADMIN_LIST_QUERY_CONFIG);
+
+    const createDisplay = homepageDisplaySettingsHooks.useCreate();
+    const updateDisplay = homepageDisplaySettingsHooks.useUpdate();
+
+    // Normalize data
+    const sections = useMemo(
+        () => (Array.isArray(sectionsData) ? sectionsData : []) as HomepageSectionRow[],
+        [sectionsData],
+    );
+    const features = useMemo(
+        () => (Array.isArray(featuresData) ? featuresData : []) as HomepageFeatureRow[],
+        [featuresData],
+    );
+    const actions = useMemo(
+        () => (Array.isArray(actionsData) ? actionsData : []) as HomepageActionRow[],
+        [actionsData],
+    );
+    const displayRows = useMemo(
+        () => (Array.isArray(displayData) ? displayData : []) as HomepageDisplaySettingsRow[],
+        [displayData],
+    );
+    const display = displayRows.find((r) => r.id === 'default') ?? null;
+
+    // Section lookup by slot
+    const sectionBySlot = useMemo(() => {
+        const map: Partial<Record<SlotName, HomepageSectionRow>> = {};
+        for (const s of sections) {
+            if (SLOT_NAMES.includes(s.slot as SlotName)) {
+                map[s.slot as SlotName] = s;
+            }
+        }
+        return map;
+    }, [sections]);
+
+    // Features/actions grouped by sectionId
+    const featuresBySectionId = useMemo(() => {
+        const map: Record<string, HomepageFeatureRow[]> = {};
+        for (const f of features) {
+            if (!map[f.sectionId]) map[f.sectionId] = [];
+            map[f.sectionId].push(f);
+        }
+        return map;
+    }, [features]);
+
+    const actionsBySectionId = useMemo(() => {
+        const map: Record<string, HomepageActionRow[]> = {};
+        for (const a of actions) {
+            if (!map[a.sectionId]) map[a.sectionId] = [];
+            map[a.sectionId].push(a);
+        }
+        return map;
+    }, [actions]);
+
+    // Local state for display settings
+    const getDefaultVariantBySlot = () =>
+        Object.fromEntries(SLOT_NAMES.map((s) => [s, SLOT_CONFIG[s].default])) as Record<string, string>;
+
+    const [variantBySlot, setVariantBySlot] = useState<Record<string, string>>(getDefaultVariantBySlot());
+    const [themePreset, setThemePreset] = useState('default');
+    const [customCss, setCustomCss] = useState('');
+    const [seoTitle, setSeoTitle] = useState('');
+    const [seoDescription, setSeoDescription] = useState('');
+    const [settingsOpen, setSettingsOpen] = useState(false);
+    const [initialized, setInitialized] = useState(false);
+
+    // Populate from DB
+    useEffect(() => {
+        if (display && !initialized) {
+            setVariantBySlot({ ...getDefaultVariantBySlot(), ...(display.variantBySlotJson ?? {}) });
+            setThemePreset(display.themePreset ?? 'default');
+            setCustomCss(display.customCss ?? '');
+            setSeoTitle(display.seoTitle ?? '');
+            setSeoDescription(display.seoDescription ?? '');
+            setInitialized(true);
+        } else if (!displayLoading && !display && !initialized) {
+            setInitialized(true);
+        }
+    }, [display, displayLoading, initialized]);
+
+    // Save display settings
+    const handleSaveDisplaySettings = async () => {
+        const payload = {
+            variantBySlotJson: variantBySlot,
+            themePreset,
+            customCss: customCss || undefined,
+            seoTitle: seoTitle || undefined,
+            seoDescription: seoDescription || undefined,
+        };
+        if (display) {
+            await updateDisplay.mutateAsync({ id: 'default', data: payload });
+        } else {
+            await createDisplay.mutateAsync({ id: 'default', ...payload });
+        }
+        refetchDisplay();
+    };
+
+    // Variant change handler
+    const handleVariantChange = useCallback((slot: SlotName, variantId: string) => {
+        setVariantBySlot((prev) => ({ ...prev, [slot]: variantId }));
+    }, []);
+
+    // Section field change (just refresh data)
+    const handleSectionChange = useCallback(() => {
+        refetchSections();
+    }, [refetchSections]);
+
+    // Refresh all data
+    const handleRefresh = useCallback(() => {
+        refetchSections();
+        refetchFeatures();
+        refetchActions();
+    }, [refetchSections, refetchFeatures, refetchActions]);
+
+    // Seed demo data
+    const [seeding, setSeeding] = useState(false);
+    const handleSeed = async () => {
+        setSeeding(true);
+        try {
+            const res = await fetch('/api/homepage/seed', { method: 'POST' });
+            if (res.ok) {
+                handleRefresh();
+                refetchDisplay();
+            }
+        } finally {
+            setSeeding(false);
+        }
+    };
+
+    if (sectionsLoading || displayLoading) {
+        return (
+            <div className="p-6">
+                <div className="flex items-center gap-3 mb-6">
+                    <div className="flex items-center gap-2 rounded-lg bg-primary/10 p-2">
+                        <Home className="h-5 w-5 text-primary" />
+                    </div>
+                    <div>
+                        <h1 className="text-xl font-semibold">Homepage Builder</h1>
+                        <p className="text-sm text-muted-foreground">Loading...</p>
+                    </div>
+                </div>
+            </div>
+        );
+    }
+
+    const isDirty =
+        initialized &&
+        (JSON.stringify(variantBySlot) !==
+            JSON.stringify({ ...getDefaultVariantBySlot(), ...(display?.variantBySlotJson ?? {}) }) ||
+            themePreset !== (display?.themePreset ?? 'default') ||
+            customCss !== (display?.customCss ?? '') ||
+            seoTitle !== (display?.seoTitle ?? '') ||
+            seoDescription !== (display?.seoDescription ?? ''));
+
+    return (
+        <div className="p-6 space-y-6 max-w-4xl mx-auto">
+            {/* Header */}
+            <div className="flex items-center justify-between">
+                <div className="flex items-center gap-3">
+                    <div className="flex items-center gap-2 rounded-lg bg-primary/10 p-2">
+                        <Home className="h-5 w-5 text-primary" />
+                    </div>
+                    <div>
+                        <h1 className="text-xl font-semibold">Homepage Builder</h1>
+                        <p className="text-sm text-muted-foreground">
+                            Configure all sections, content, and display settings
+                        </p>
+                    </div>
+                </div>
+                <div className="flex items-center gap-2">
+                    <TooltipProvider>
+                        <Tooltip>
+                            <TooltipTrigger asChild>
+                                <Button variant="outline" size="sm" onClick={handleSeed} disabled={seeding}>
+                                    <IconDatabaseImport className="mr-1 h-4 w-4" />
+                                    Seed Demo
+                                </Button>
+                            </TooltipTrigger>
+                            <TooltipContent>
+                                <p>Populate all sections with demo content</p>
+                            </TooltipContent>
+                        </Tooltip>
+                    </TooltipProvider>
+                    <a
+                        href={import.meta.env.VITE_HOMEPAGE_URL || 'http://localhost:3000'}
+                        target="_blank"
+                        rel="noopener noreferrer"
+                    >
+                        <Button variant="outline" size="sm">
+                            <ExternalLink className="mr-1 h-4 w-4" />
+                            Preview
+                        </Button>
+                    </a>
+                </div>
+            </div>
+
+            {/* Settings Panel (Collapsible) */}
+            <Collapsible open={settingsOpen} onOpenChange={setSettingsOpen}>
+                <Card>
+                    <CollapsibleTrigger asChild>
+                        <CardHeader className="cursor-pointer hover:bg-muted/50 transition-colors">
+                            <div className="flex items-center justify-between">
+                                <div className="flex items-center gap-2">
+                                    <Settings className="h-4 w-4 text-muted-foreground" />
+                                    <CardTitle className="text-base">Display Settings</CardTitle>
+                                </div>
+                                <div className="flex items-center gap-2">
+                                    {isDirty && (
+                                        <Badge variant="secondary" className="text-xs">
+                                            Unsaved
+                                        </Badge>
+                                    )}
+                                    <Badge variant="outline" className="text-xs capitalize">
+                                        {themePreset} theme
+                                    </Badge>
+                                    <ChevronDown
+                                        className={`h-4 w-4 text-muted-foreground transition-transform ${settingsOpen ? 'rotate-180' : ''}`}
+                                    />
+                                </div>
+                            </div>
+                            <CardDescription>Theme preset, SEO metadata, and custom styles</CardDescription>
+                        </CardHeader>
+                    </CollapsibleTrigger>
+                    <CollapsibleContent>
+                        <CardContent className="space-y-4 border-t pt-4">
+                            {/* Theme Preset */}
+                            <div className="space-y-2">
+                                <Label className="text-xs">Theme Preset</Label>
+                                <div className="grid grid-cols-4 gap-2">
+                                    {THEME_PRESETS.map((preset) => (
+                                        <button
+                                            key={preset.id}
+                                            type="button"
+                                            onClick={() => setThemePreset(preset.id)}
+                                            className={`rounded-lg border p-3 text-left transition-colors hover:bg-muted/50 ${
+                                                themePreset === preset.id
+                                                    ? 'border-primary bg-primary/5 ring-1 ring-primary'
+                                                    : ''
+                                            }`}
+                                        >
+                                            <div className="flex items-center gap-2">
+                                                <Palette className="h-4 w-4" />
+                                                <span className="font-medium text-sm">{preset.label}</span>
+                                            </div>
+                                            <p className="mt-1 text-xs text-muted-foreground">{preset.description}</p>
+                                        </button>
+                                    ))}
+                                </div>
+                            </div>
+
+                            <Separator />
+
+                            {/* SEO Fields */}
+                            <div className="grid gap-4 sm:grid-cols-2">
+                                <div className="space-y-2">
+                                    <Label htmlFor="seo-title" className="text-xs">
+                                        SEO Title
+                                    </Label>
+                                    <Input
+                                        id="seo-title"
+                                        value={seoTitle}
+                                        onChange={(e) => setSeoTitle(e.target.value)}
+                                        placeholder="Page title for search engines"
+                                        className="h-9"
+                                    />
+                                </div>
+                                <div className="space-y-2">
+                                    <Label htmlFor="seo-desc" className="text-xs">
+                                        SEO Description
+                                    </Label>
+                                    <Input
+                                        id="seo-desc"
+                                        value={seoDescription}
+                                        onChange={(e) => setSeoDescription(e.target.value)}
+                                        placeholder="Meta description for search engines"
+                                        className="h-9"
+                                    />
+                                </div>
+                            </div>
+
+                            {/* Custom CSS */}
+                            <div className="space-y-2">
+                                <Label htmlFor="custom-css" className="text-xs">
+                                    Custom CSS (advanced)
+                                </Label>
+                                <Textarea
+                                    id="custom-css"
+                                    value={customCss}
+                                    onChange={(e) => setCustomCss(e.target.value)}
+                                    placeholder=".hero { background: linear-gradient(...); }"
+                                    rows={3}
+                                    className="font-mono text-xs"
+                                />
+                            </div>
+
+                            {/* Save Button */}
+                            <div className="flex justify-end">
+                                <Button
+                                    size="sm"
+                                    onClick={handleSaveDisplaySettings}
+                                    disabled={!isDirty || updateDisplay.isPending || createDisplay.isPending}
+                                >
+                                    <Save className="mr-1 h-4 w-4" />
+                                    Save Settings
+                                </Button>
+                            </div>
+                        </CardContent>
+                    </CollapsibleContent>
+                </Card>
+            </Collapsible>
+
+            {/* Slot Cards */}
+            <div>
+                <div className="flex items-center gap-2 mb-4">
+                    <Layout className="h-4 w-4 text-muted-foreground" />
+                    <h2 className="font-medium">Page Sections</h2>
+                    <Badge variant="secondary" className="text-xs">
+                        {sections.filter((s) => s.enabled).length} / {SLOT_NAMES.length} active
+                    </Badge>
+                </div>
+
+                <Accordion type="multiple" className="space-y-3">
+                    {SLOT_NAMES.map((slot) => {
+                        const section = sectionBySlot[slot] ?? null;
+                        const sectionFeatures = section ? featuresBySectionId[section.id] || [] : [];
+                        const sectionActions = section ? actionsBySectionId[section.id] || [] : [];
+
+                        return (
+                            <SlotCard
+                                key={slot}
+                                slot={slot}
+                                section={section}
+                                features={sectionFeatures}
+                                actions={sectionActions}
+                                variantBySlot={variantBySlot}
+                                onSectionChange={handleSectionChange}
+                                onVariantChange={handleVariantChange}
+                                onRefresh={handleRefresh}
+                            />
+                        );
+                    })}
+                </Accordion>
+            </div>
+        </div>
+    );
+}
diff --git a/apps/ottabase-template-app-tanstack/src/pages/admin/homepage/AdminHomepageDisplayPage.tsx b/apps/ottabase-template-app-tanstack/src/pages/admin/homepage/AdminHomepageDisplayPage.tsx
deleted file mode 100644
index 37285e9ba..000000000
--- a/apps/ottabase-template-app-tanstack/src/pages/admin/homepage/AdminHomepageDisplayPage.tsx
+++ /dev/null
@@ -1,304 +0,0 @@
-/**
- * Admin Homepage Display Settings
- *
- * Manages the homepage display state: variant selection per slot,
- * theme preset, custom CSS, and SEO metadata.
- *
- * Single-row settings model (id = 'default'). Uses upsert semantics.
- */
-import { ADMIN_LIST_QUERY_CONFIG } from '@/config/queryConfig';
-import { homepageDisplaySettingsHooks, type HomepageDisplaySettingsRow } from '@/hooks/homepageHooks';
-import {
-    Badge,
-    Button,
-    Card,
-    CardContent,
-    CardDescription,
-    CardHeader,
-    CardTitle,
-    Input,
-    Label,
-    Separator,
-    Textarea,
-} from '@ottabase/ui-shadcn';
-import { Check, Code, Globe, Monitor, Palette, RotateCcw, Save, Search } from 'lucide-react';
-import { useCallback, useEffect, useState } from 'react';
-import { HomepageAdminNav } from './HomepageAdminNav';
-import { getDefaultVariantBySlot, SLOT_CONFIG, SLOT_NAMES, THEME_PRESETS, type SlotName } from './homepage-constants';
-
-export function AdminHomepageDisplayPage() {
-    const { data, isLoading } = homepageDisplaySettingsHooks.useList({}, ADMIN_LIST_QUERY_CONFIG);
-    const createSettings = homepageDisplaySettingsHooks.useCreate();
-    const updateSettings = homepageDisplaySettingsHooks.useUpdate();
-
-    // Normalize response: list may return array or paginated
-    const rows = (Array.isArray(data) ? data : []) as HomepageDisplaySettingsRow[];
-    const existing = rows.find((r) => r.id === 'default') ?? null;
-
-    const [variantBySlot, setVariantBySlot] = useState<Record<string, string>>(getDefaultVariantBySlot());
-    const [themePreset, setThemePreset] = useState('default');
-    const [customCss, setCustomCss] = useState('');
-    const [seoTitle, setSeoTitle] = useState('');
-    const [seoDescription, setSeoDescription] = useState('');
-    const [initialized, setInitialized] = useState(false);
-
-    // Populate from DB when data loads
-    useEffect(() => {
-        if (existing && !initialized) {
-            setVariantBySlot({ ...getDefaultVariantBySlot(), ...(existing.variantBySlotJson ?? {}) });
-            setThemePreset(existing.themePreset ?? 'default');
-            setCustomCss(existing.customCss ?? '');
-            setSeoTitle(existing.seoTitle ?? '');
-            setSeoDescription(existing.seoDescription ?? '');
-            setInitialized(true);
-        } else if (!isLoading && !existing && !initialized) {
-            // No row yet — use defaults
-            setInitialized(true);
-        }
-    }, [existing, isLoading, initialized]);
-
-    const isDirty =
-        initialized &&
-        (JSON.stringify(variantBySlot) !==
-            JSON.stringify({ ...getDefaultVariantBySlot(), ...(existing?.variantBySlotJson ?? {}) }) ||
-            themePreset !== (existing?.themePreset ?? 'default') ||
-            customCss !== (existing?.customCss ?? '') ||
-            seoTitle !== (existing?.seoTitle ?? '') ||
-            seoDescription !== (existing?.seoDescription ?? ''));
-
-    const handleSave = useCallback(async () => {
-        const payload = {
-            variantBySlotJson: variantBySlot,
-            themePreset,
-            customCss: customCss || undefined,
-            seoTitle: seoTitle || undefined,
-            seoDescription: seoDescription || undefined,
-        };
-        if (existing) {
-            await updateSettings.mutateAsync({ id: 'default', data: payload });
-        } else {
-            await createSettings.mutateAsync({ id: 'default', ...payload });
-        }
-    }, [existing, variantBySlot, themePreset, customCss, seoTitle, seoDescription, updateSettings, createSettings]);
-
-    const handleVariantChange = (slot: SlotName, variantId: string) => {
-        setVariantBySlot((prev) => ({ ...prev, [slot]: variantId }));
-    };
-
-    const handleResetDefaults = () => {
-        setVariantBySlot(getDefaultVariantBySlot());
-        setThemePreset('default');
-        setCustomCss('');
-        setSeoTitle('');
-        setSeoDescription('');
-    };
-
-    if (isLoading) {
-        return (
-            <div className="space-y-6">
-                <HomepageAdminNav />
-                <Card>
-                    <CardContent className="py-12 text-center">
-                        <p className="text-muted-foreground">Loading display settings…</p>
-                    </CardContent>
-                </Card>
-            </div>
-        );
-    }
-
-    return (
-        <div className="space-y-6">
-            <HomepageAdminNav />
-
-            {/* Header */}
-            <div className="flex flex-col gap-4 sm:flex-row sm:items-center sm:justify-between">
-                <div>
-                    <h1 className="text-3xl font-bold tracking-tight">Display Settings</h1>
-                    <p className="text-muted-foreground mt-1">
-                        Configure layout variants, theme, SEO, and custom styling for the homepage.
-                    </p>
-                </div>
-                <div className="flex gap-2">
-                    <Button variant="outline" onClick={handleResetDefaults}>
-                        <RotateCcw className="mr-2 h-4 w-4" />
-                        Reset
-                    </Button>
-                    <Button
-                        onClick={handleSave}
-                        disabled={!isDirty || updateSettings.isPending || createSettings.isPending}
-                    >
-                        <Save className="mr-2 h-4 w-4" />
-                        {updateSettings.isPending || createSettings.isPending ? 'Saving…' : 'Save'}
-                    </Button>
-                </div>
-            </div>
-
-            {/* Theme Preset */}
-            <Card>
-                <CardHeader>
-                    <CardTitle className="text-base flex items-center gap-2">
-                        <Palette className="h-4 w-4" />
-                        Theme Preset
-                    </CardTitle>
-                    <CardDescription>Select the visual theme for the homepage.</CardDescription>
-                </CardHeader>
-                <CardContent>
-                    <div className="grid gap-3 sm:grid-cols-2 md:grid-cols-4">
-                        {THEME_PRESETS.map((preset) => {
-                            const isActive = themePreset === preset.id;
-                            return (
-                                <button
-                                    key={preset.id}
-                                    type="button"
-                                    onClick={() => setThemePreset(preset.id)}
-                                    className={`relative rounded-lg border-2 p-3 text-left transition-all ${
-                                        isActive
-                                            ? 'border-primary bg-primary/5 ring-1 ring-primary/20'
-                                            : 'border-border hover:border-muted-foreground/30 hover:bg-muted/50'
-                                    }`}
-                                >
-                                    {isActive && (
-                                        <div className="absolute top-2 right-2 rounded-full bg-primary p-0.5">
-                                            <Check className="h-3 w-3 text-primary-foreground" />
-                                        </div>
-                                    )}
-                                    <p className="font-medium text-sm">{preset.label}</p>
-                                    <p className="mt-0.5 text-xs text-muted-foreground">{preset.description}</p>
-                                </button>
-                            );
-                        })}
-                    </div>
-                    <Separator className="my-4" />
-                    <div className="flex items-center gap-3">
-                        <Label htmlFor="theme-preset-custom" className="shrink-0 text-sm">
-                            Custom preset:
-                        </Label>
-                        <Input
-                            id="theme-preset-custom"
-                            value={themePreset}
-                            onChange={(e) => setThemePreset(e.target.value)}
-                            placeholder="default"
-                            className="max-w-xs"
-                        />
-                    </div>
-                </CardContent>
-            </Card>
-
-            {/* Slot Variant Pickers */}
-            <Card>
-                <CardHeader>
-                    <CardTitle className="text-base flex items-center gap-2">
-                        <Monitor className="h-4 w-4" />
-                        Layout Variants
-                    </CardTitle>
-                    <CardDescription>Choose the display variant for each homepage slot.</CardDescription>
-                </CardHeader>
-                <CardContent className="space-y-6">
-                    {SLOT_NAMES.map((slot) => {
-                        const config = SLOT_CONFIG[slot];
-                        const selected = variantBySlot[slot] ?? config.default;
-
-                        return (
-                            <div key={slot}>
-                                <div className="flex items-center gap-2 mb-3">
-                                    <p className="text-sm font-medium">{config.label}</p>
-                                    <Badge variant="outline" className="font-mono text-[10px]">
-                                        {slot}
-                                    </Badge>
-                                </div>
-                                <div className="grid gap-2 sm:grid-cols-3">
-                                    {config.variants.map((v) => {
-                                        const isActive = selected === v.id;
-                                        return (
-                                            <button
-                                                key={v.id}
-                                                type="button"
-                                                onClick={() => handleVariantChange(slot, v.id)}
-                                                className={`relative rounded-lg border-2 p-3 text-left transition-all ${
-                                                    isActive
-                                                        ? 'border-primary bg-primary/5 ring-1 ring-primary/20'
-                                                        : 'border-border hover:border-muted-foreground/30 hover:bg-muted/50'
-                                                }`}
-                                            >
-                                                {isActive && (
-                                                    <div className="absolute top-2 right-2 rounded-full bg-primary p-0.5">
-                                                        <Check className="h-3 w-3 text-primary-foreground" />
-                                                    </div>
-                                                )}
-                                                <p className="font-medium text-sm">{v.label}</p>
-                                                <p className="mt-0.5 text-xs text-muted-foreground">{v.desc}</p>
-                                            </button>
-                                        );
-                                    })}
-                                </div>
-                                {slot !== SLOT_NAMES[SLOT_NAMES.length - 1] && <Separator className="mt-4" />}
-                            </div>
-                        );
-                    })}
-                </CardContent>
-            </Card>
-
-            {/* SEO Settings */}
-            <Card>
-                <CardHeader>
-                    <CardTitle className="text-base flex items-center gap-2">
-                        <Search className="h-4 w-4" />
-                        SEO
-                    </CardTitle>
-                    <CardDescription>Search engine optimization for the homepage.</CardDescription>
-                </CardHeader>
-                <CardContent className="space-y-4">
-                    <div className="space-y-2">
-                        <Label htmlFor="seo-title">Page Title</Label>
-                        <Input
-                            id="seo-title"
-                            value={seoTitle}
-                            onChange={(e) => setSeoTitle(e.target.value)}
-                            placeholder="My Awesome Product — Tagline"
-                            className="max-w-lg"
-                        />
-                        <p className="text-xs text-muted-foreground">
-                            Appears in browser tab and search results. Recommended: 50–60 characters.
-                        </p>
-                    </div>
-                    <div className="space-y-2">
-                        <Label htmlFor="seo-description">Meta Description</Label>
-                        <Textarea
-                            id="seo-description"
-                            value={seoDescription}
-                            onChange={(e) => setSeoDescription(e.target.value)}
-                            placeholder="A brief description of your product or service for search engines."
-                            rows={3}
-                            className="max-w-lg"
-                        />
-                        <p className="text-xs text-muted-foreground">
-                            Shown in search result snippets. Recommended: 150–160 characters.
-                        </p>
-                    </div>
-                </CardContent>
-            </Card>
-
-            {/* Custom CSS */}
-            <Card>
-                <CardHeader>
-                    <CardTitle className="text-base flex items-center gap-2">
-                        <Code className="h-4 w-4" />
-                        Custom CSS
-                    </CardTitle>
-                    <CardDescription>
-                        Inject custom CSS into the homepage. Use with care — overrides may break layout.
-                    </CardDescription>
-                </CardHeader>
-                <CardContent>
-                    <Textarea
-                        value={customCss}
-                        onChange={(e) => setCustomCss(e.target.value)}
-                        placeholder={`.hero-section {\n  background: linear-gradient(135deg, #667eea 0%, #764ba2 100%);\n}`}
-                        rows={8}
-                        className="font-mono text-sm"
-                    />
-                </CardContent>
-            </Card>
-        </div>
-    );
-}
diff --git a/apps/ottabase-template-app-tanstack/src/pages/admin/homepage/AdminHomepagePagesPage.tsx b/apps/ottabase-template-app-tanstack/src/pages/admin/homepage/AdminHomepagePagesPage.tsx
deleted file mode 100644
index 8a87c7699..000000000
--- a/apps/ottabase-template-app-tanstack/src/pages/admin/homepage/AdminHomepagePagesPage.tsx
+++ /dev/null
@@ -1,187 +0,0 @@
-/**
- * Admin Homepage Pages Management
- *
- * Lists CMS pages (contentType = 'page') and manages their expose-to-homepage flag.
- * Provides direct links to the blog editor for full page editing.
- */
-import { ADMIN_LIST_QUERY_CONFIG } from '@/config/queryConfig';
-import { createModelHooks } from '@ottabase/ottaorm/client';
-import { Badge, Button, Card, CardContent, CardDescription, CardHeader, CardTitle, Switch } from '@ottabase/ui-shadcn';
-import { Link } from '@tanstack/react-router';
-import { Edit, ExternalLink, Eye, EyeOff, FileText, Globe, Plus } from 'lucide-react';
-import { HomepageAdminNav } from './HomepageAdminNav';
-
-interface BlogPostRow {
-    id: string;
-    title: string;
-    slug: string;
-    excerpt: string | null;
-    contentType: string;
-    status: string;
-    exposeToHomepage: boolean;
-    publishedAt: string | null;
-    updatedAt: string;
-}
-
-const postHooks = createModelHooks<BlogPostRow>({ entityName: 'posts' });
-
-export function AdminHomepagePagesPage() {
-    const { data, isLoading } = postHooks.useList(
-        { where: { contentType: 'page' }, orderBy: 'updatedAt', orderDirection: 'desc' },
-        ADMIN_LIST_QUERY_CONFIG,
-    );
-    const updatePost = postHooks.useUpdate();
-
-    const pages = (Array.isArray(data) ? data : []) as BlogPostRow[];
-    const publishedPages = pages.filter((p) => p.status === 'published');
-    const exposedCount = pages.filter((p) => p.exposeToHomepage).length;
-
-    const handleToggleExpose = async (page: BlogPostRow) => {
-        await updatePost.mutateAsync({
-            id: page.id,
-            data: { exposeToHomepage: !page.exposeToHomepage },
-        });
-    };
-
-    return (
-        <div className="space-y-6">
-            <HomepageAdminNav />
-
-            {/* Header */}
-            <div className="flex flex-col gap-4 sm:flex-row sm:items-center sm:justify-between">
-                <div>
-                    <h1 className="text-3xl font-bold tracking-tight">CMS Pages</h1>
-                    <p className="text-muted-foreground mt-1">
-                        Manage CMS-powered pages and control which appear in the homepage navbar.
-                    </p>
-                </div>
-                <div className="flex items-center gap-3">
-                    <Badge variant="secondary" className="text-xs">
-                        {exposedCount} exposed to navbar
-                    </Badge>
-                    <Button asChild>
-                        <Link to="/admin/blog/new">
-                            <Plus className="mr-1.5 h-4 w-4" />
-                            New Page
-                        </Link>
-                    </Button>
-                </div>
-            </div>
-
-            {/* Loading */}
-            {isLoading && (
-                <Card>
-                    <CardContent className="py-12 text-center">
-                        <p className="text-muted-foreground">Loading pages…</p>
-                    </CardContent>
-                </Card>
-            )}
-
-            {/* Empty state */}
-            {!isLoading && pages.length === 0 && (
-                <Card>
-                    <CardContent className="py-12 text-center">
-                        <FileText className="mx-auto h-12 w-12 text-muted-foreground/50" />
-                        <h3 className="mt-4 text-lg font-semibold">No pages yet</h3>
-                        <p className="mt-2 text-muted-foreground">
-                            Create a page in the Blog Editor with content type {'"'}Page{'"'} to manage it here.
-                        </p>
-                        <Button variant="outline" className="mt-4" asChild>
-                            <Link to="/admin/blog/new">
-                                <Plus className="mr-1.5 h-4 w-4" />
-                                Create Page
-                            </Link>
-                        </Button>
-                    </CardContent>
-                </Card>
-            )}
-
-            {/* Pages list */}
-            {pages.length > 0 && (
-                <Card>
-                    <CardHeader className="pb-3">
-                        <CardTitle className="text-base">All Pages</CardTitle>
-                        <CardDescription>
-                            Toggle {'"'}Expose to Homepage{'"'} to add pages to the navbar. Pages must be published to
-                            appear.
-                        </CardDescription>
-                    </CardHeader>
-                    <CardContent>
-                        <div className="divide-y">
-                            {pages.map((page) => (
-                                <div key={page.id} className="flex items-center gap-4 py-3">
-                                    <div className="min-w-0 flex-1">
-                                        <div className="flex items-center gap-2">
-                                            <p className="font-medium text-sm truncate">{page.title || '(untitled)'}</p>
-                                            <Badge
-                                                variant={page.status === 'published' ? 'default' : 'secondary'}
-                                                className="text-[10px] shrink-0"
-                                            >
-                                                {page.status}
-                                            </Badge>
-                                        </div>
-                                        <p className="text-xs text-muted-foreground mt-0.5">
-                                            /page/{page.slug}
-                                            {page.excerpt && ` — ${page.excerpt}`}
-                                        </p>
-                                    </div>
-
-                                    {/* Expose toggle */}
-                                    <div className="flex items-center gap-2 shrink-0">
-                                        <Switch
-                                            id={`expose-${page.id}`}
-                                            checked={page.exposeToHomepage}
-                                            onCheckedChange={() => handleToggleExpose(page)}
-                                            disabled={updatePost.isPending}
-                                        />
-                                        <label
-                                            htmlFor={`expose-${page.id}`}
-                                            className="text-xs text-muted-foreground cursor-pointer flex items-center gap-1"
-                                        >
-                                            {page.exposeToHomepage ? (
-                                                <>
-                                                    <Globe className="h-3 w-3 text-primary" />
-                                                    In navbar
-                                                </>
-                                            ) : (
-                                                <>
-                                                    <EyeOff className="h-3 w-3" />
-                                                    Hidden
-                                                </>
-                                            )}
-                                        </label>
-                                    </div>
-
-                                    {/* Edit link */}
-                                    <Button variant="ghost" size="icon" className="h-8 w-8 shrink-0" asChild>
-                                        <Link to="/admin/blog/$postId" params={{ postId: page.id }}>
-                                            <Edit className="h-4 w-4" />
-                                        </Link>
-                                    </Button>
-                                </div>
-                            ))}
-                        </div>
-                    </CardContent>
-                </Card>
-            )}
-
-            {/* Info card */}
-            <Card>
-                <CardContent className="py-4">
-                    <div className="flex items-start gap-3">
-                        <Globe className="h-5 w-5 text-primary shrink-0 mt-0.5" />
-                        <div className="text-sm text-muted-foreground">
-                            <p className="font-medium text-foreground">How pages work</p>
-                            <p className="mt-1">
-                                Pages are CMS content with type {'"'}Page{'"'} created in the Blog Editor. When exposed
-                                to the homepage, they appear as links in the navigation bar. Each page renders at{' '}
-                                <code className="text-xs bg-muted px-1 py-0.5 rounded">/page/slug</code> on the Next.js
-                                homepage.
-                            </p>
-                        </div>
-                    </div>
-                </CardContent>
-            </Card>
-        </div>
-    );
-}
diff --git a/apps/ottabase-template-app-tanstack/src/pages/admin/homepage/AdminHomepageSectionEditorPage.tsx b/apps/ottabase-template-app-tanstack/src/pages/admin/homepage/AdminHomepageSectionEditorPage.tsx
deleted file mode 100644
index 41a14a99a..000000000
--- a/apps/ottabase-template-app-tanstack/src/pages/admin/homepage/AdminHomepageSectionEditorPage.tsx
+++ /dev/null
@@ -1,788 +0,0 @@
-/**
- * Admin Homepage Section Editor
- *
- * Full CRUD editor for a single homepage section with all configurable fields.
- * Includes inline editing of child features and actions with icon, imageUrl, href support.
- * Auto-saves on blur or button click.
- */
-import { ADMIN_LIST_QUERY_CONFIG } from '@/config/queryConfig';
-import {
-    homepageActionHooks,
-    homepageFeatureHooks,
-    homepageSectionHooks,
-    type HomepageActionRow,
-    type HomepageFeatureRow,
-} from '@/hooks/homepageHooks';
-import {
-    AlertDialog,
-    AlertDialogAction,
-    AlertDialogCancel,
-    AlertDialogContent,
-    AlertDialogDescription,
-    AlertDialogFooter,
-    AlertDialogHeader,
-    AlertDialogTitle,
-    Badge,
-    Button,
-    Card,
-    CardContent,
-    CardDescription,
-    CardHeader,
-    CardTitle,
-    Input,
-    Label,
-    Separator,
-    Switch,
-    Textarea,
-    Tooltip,
-    TooltipContent,
-    TooltipProvider,
-    TooltipTrigger,
-} from '@ottabase/ui-shadcn';
-import { useNavigate, useParams } from '@tanstack/react-router';
-import {
-    ArrowDown,
-    ArrowLeft,
-    ArrowUp,
-    ExternalLink,
-    GripVertical,
-    Image,
-    Link2,
-    Plus,
-    Save,
-    Trash2,
-} from 'lucide-react';
-import { useCallback, useEffect, useRef, useState } from 'react';
-import { HomepageAdminNav } from './HomepageAdminNav';
-import { ACTION_VARIANTS, ICON_SUGGESTIONS, SLOT_LABELS } from './homepage-constants';
-
-// ── Feature row editor ──────────────────────────────────────────────────────
-
-function FeatureEditor({
-    feature,
-    onDelete,
-    onMove,
-    isFirst,
-    isLast,
-}: {
-    feature: HomepageFeatureRow;
-    onDelete: (id: string) => void;
-    onMove: (id: string, direction: 'up' | 'down') => void;
-    isFirst: boolean;
-    isLast: boolean;
-}) {
-    const updateFeature = homepageFeatureHooks.useUpdate();
-    const [title, setTitle] = useState(feature.title);
-    const [description, setDescription] = useState(feature.description);
-    const [icon, setIcon] = useState(feature.icon ?? '');
-    const [imageUrl, setImageUrl] = useState(feature.imageUrl ?? '');
-    const [href, setHref] = useState(feature.href ?? '');
-
-    const dirty =
-        title !== feature.title ||
-        description !== feature.description ||
-        icon !== (feature.icon ?? '') ||
-        imageUrl !== (feature.imageUrl ?? '') ||
-        href !== (feature.href ?? '');
-
-    const handleSave = useCallback(() => {
-        if (!dirty) return;
-        updateFeature.mutate({
-            id: feature.id,
-            data: {
-                title,
-                description,
-                icon: icon || undefined,
-                imageUrl: imageUrl || undefined,
-                href: href || undefined,
-            },
-        });
-    }, [dirty, feature.id, title, description, icon, imageUrl, href, updateFeature]);
-
-    return (
-        <div className="rounded-lg border p-3 space-y-3">
-            <div className="flex items-start gap-2">
-                <GripVertical className="mt-2 h-4 w-4 shrink-0 text-muted-foreground/40 cursor-grab" />
-                <div className="flex-1 space-y-2">
-                    <div className="flex gap-2">
-                        <Input
-                            value={title}
-                            onChange={(e) => setTitle(e.target.value)}
-                            onBlur={handleSave}
-                            placeholder="Feature title"
-                            className="h-8 text-sm font-medium"
-                        />
-                        <Input
-                            value={icon}
-                            onChange={(e) => setIcon(e.target.value)}
-                            onBlur={handleSave}
-                            placeholder="Icon (e.g. Zap)"
-                            className="h-8 text-sm w-32"
-                        />
-                    </div>
-                    <Textarea
-                        value={description}
-                        onChange={(e) => setDescription(e.target.value)}
-                        onBlur={handleSave}
-                        placeholder="Short description"
-                        rows={2}
-                        className="text-sm"
-                    />
-                    <div className="flex gap-2">
-                        <div className="flex-1 flex items-center gap-1.5">
-                            <Image className="h-3.5 w-3.5 text-muted-foreground shrink-0" />
-                            <Input
-                                value={imageUrl}
-                                onChange={(e) => setImageUrl(e.target.value)}
-                                onBlur={handleSave}
-                                placeholder="Image URL (optional)"
-                                className="h-7 text-xs"
-                            />
-                        </div>
-                        <div className="flex-1 flex items-center gap-1.5">
-                            <Link2 className="h-3.5 w-3.5 text-muted-foreground shrink-0" />
-                            <Input
-                                value={href}
-                                onChange={(e) => setHref(e.target.value)}
-                                onBlur={handleSave}
-                                placeholder="Link URL (optional)"
-                                className="h-7 text-xs"
-                            />
-                        </div>
-                    </div>
-                </div>
-                <div className="flex flex-col items-center gap-0.5">
-                    <TooltipProvider>
-                        <Tooltip>
-                            <TooltipTrigger asChild>
-                                <Button
-                                    variant="ghost"
-                                    size="icon"
-                                    className="h-6 w-6"
-                                    onClick={() => onMove(feature.id, 'up')}
-                                    disabled={isFirst}
-                                >
-                                    <ArrowUp className="h-3 w-3" />
-                                </Button>
-                            </TooltipTrigger>
-                            <TooltipContent>Move up</TooltipContent>
-                        </Tooltip>
-                        <Tooltip>
-                            <TooltipTrigger asChild>
-                                <Button
-                                    variant="ghost"
-                                    size="icon"
-                                    className="h-6 w-6"
-                                    onClick={() => onMove(feature.id, 'down')}
-                                    disabled={isLast}
-                                >
-                                    <ArrowDown className="h-3 w-3" />
-                                </Button>
-                            </TooltipTrigger>
-                            <TooltipContent>Move down</TooltipContent>
-                        </Tooltip>
-                    </TooltipProvider>
-                    {dirty && (
-                        <Button variant="ghost" size="icon" className="h-6 w-6" onClick={handleSave}>
-                            <Save className="h-3.5 w-3.5 text-primary" />
-                        </Button>
-                    )}
-                    <Button variant="ghost" size="icon" className="h-6 w-6" onClick={() => onDelete(feature.id)}>
-                        <Trash2 className="h-3.5 w-3.5 text-destructive" />
-                    </Button>
-                </div>
-            </div>
-        </div>
-    );
-}
-
-// ── Action row editor ───────────────────────────────────────────────────────
-
-function ActionEditor({
-    action,
-    onDelete,
-    onMove,
-    isFirst,
-    isLast,
-}: {
-    action: HomepageActionRow;
-    onDelete: (id: string) => void;
-    onMove: (id: string, direction: 'up' | 'down') => void;
-    isFirst: boolean;
-    isLast: boolean;
-}) {
-    const updateAction = homepageActionHooks.useUpdate();
-    const [label, setLabel] = useState(action.label);
-    const [href, setHref] = useState(action.href);
-    const [variant, setVariant] = useState(action.variant ?? 'default');
-    const [icon, setIcon] = useState(action.icon ?? '');
-    const [external, setExternal] = useState(action.external);
-
-    // Track previous values for useEffect-based auto-save
-    const prevVariantRef = useRef(variant);
-    const prevExternalRef = useRef(external);
-
-    const dirty =
-        label !== action.label ||
-        href !== action.href ||
-        variant !== (action.variant ?? 'default') ||
-        icon !== (action.icon ?? '') ||
-        external !== action.external;
-
-    const handleSave = useCallback(() => {
-        if (!dirty) return;
-        updateAction.mutate({
-            id: action.id,
-            data: { label, href, variant, icon: icon || undefined, external },
-        });
-    }, [dirty, action.id, label, href, variant, icon, external, updateAction]);
-
-    // Auto-save when variant or external toggle changes
-    useEffect(() => {
-        if (variant !== prevVariantRef.current || external !== prevExternalRef.current) {
-            prevVariantRef.current = variant;
-            prevExternalRef.current = external;
-            const isDirty =
-                label !== action.label ||
-                href !== action.href ||
-                variant !== (action.variant ?? 'default') ||
-                icon !== (action.icon ?? '') ||
-                external !== action.external;
-            if (isDirty) {
-                updateAction.mutate({
-                    id: action.id,
-                    data: { label, href, variant, icon: icon || undefined, external },
-                });
-            }
-        }
-    }, [variant, external]); // eslint-disable-line react-hooks/exhaustive-deps
-
-    return (
-        <div className="rounded-lg border p-3 space-y-2">
-            <div className="flex items-start gap-2">
-                <GripVertical className="mt-2 h-4 w-4 shrink-0 text-muted-foreground/40 cursor-grab" />
-                <div className="flex-1 space-y-2">
-                    <div className="flex gap-2">
-                        <Input
-                            value={label}
-                            onChange={(e) => setLabel(e.target.value)}
-                            onBlur={handleSave}
-                            placeholder="Button label"
-                            className="h-8 text-sm font-medium"
-                        />
-                        <Input
-                            value={href}
-                            onChange={(e) => setHref(e.target.value)}
-                            onBlur={handleSave}
-                            placeholder="/about or https://..."
-                            className="h-8 text-sm"
-                        />
-                    </div>
-                    <div className="flex items-center gap-4 flex-wrap">
-                        <div className="flex items-center gap-2">
-                            <Label className="text-xs">Style:</Label>
-                            <select
-                                value={variant}
-                                onChange={(e) => setVariant(e.target.value)}
-                                className="h-7 rounded-md border border-input bg-background px-2 text-xs"
-                                aria-label="Button style variant"
-                            >
-                                {ACTION_VARIANTS.map((v) => (
-                                    <option key={v.value} value={v.value}>
-                                        {v.label}
-                                    </option>
-                                ))}
-                            </select>
-                        </div>
-                        <div className="flex items-center gap-2">
-                            <Label className="text-xs">Icon:</Label>
-                            <Input
-                                value={icon}
-                                onChange={(e) => setIcon(e.target.value)}
-                                onBlur={handleSave}
-                                placeholder="ArrowRight"
-                                className="h-7 text-xs w-28"
-                            />
-                        </div>
-                        <div className="flex items-center gap-2">
-                            <Switch id={`external-${action.id}`} checked={external} onCheckedChange={setExternal} />
-                            <Label htmlFor={`external-${action.id}`} className="text-xs">
-                                External
-                            </Label>
-                            {external && <ExternalLink className="h-3 w-3 text-muted-foreground" />}
-                        </div>
-                    </div>
-                </div>
-                <div className="flex flex-col items-center gap-0.5">
-                    <TooltipProvider>
-                        <Tooltip>
-                            <TooltipTrigger asChild>
-                                <Button
-                                    variant="ghost"
-                                    size="icon"
-                                    className="h-6 w-6"
-                                    onClick={() => onMove(action.id, 'up')}
-                                    disabled={isFirst}
-                                >
-                                    <ArrowUp className="h-3 w-3" />
-                                </Button>
-                            </TooltipTrigger>
-                            <TooltipContent>Move up</TooltipContent>
-                        </Tooltip>
-                        <Tooltip>
-                            <TooltipTrigger asChild>
-                                <Button
-                                    variant="ghost"
-                                    size="icon"
-                                    className="h-6 w-6"
-                                    onClick={() => onMove(action.id, 'down')}
-                                    disabled={isLast}
-                                >
-                                    <ArrowDown className="h-3 w-3" />
-                                </Button>
-                            </TooltipTrigger>
-                            <TooltipContent>Move down</TooltipContent>
-                        </Tooltip>
-                    </TooltipProvider>
-                    {dirty && (
-                        <Button variant="ghost" size="icon" className="h-6 w-6" onClick={handleSave}>
-                            <Save className="h-3.5 w-3.5 text-primary" />
-                        </Button>
-                    )}
-                    <Button variant="ghost" size="icon" className="h-6 w-6" onClick={() => onDelete(action.id)}>
-                        <Trash2 className="h-3.5 w-3.5 text-destructive" />
-                    </Button>
-                </div>
-            </div>
-        </div>
-    );
-}
-
-// ── Main editor page ────────────────────────────────────────────────────────
-
-export function AdminHomepageSectionEditorPage() {
-    const { sectionId } = useParams({ strict: false }) as { sectionId?: string };
-    const navigate = useNavigate();
-
-    // Section data
-    const { data: sectionData, isLoading: sectionLoading } = homepageSectionHooks.useDetail(sectionId ?? '', {
-        enabled: !!sectionId,
-    });
-    const updateSection = homepageSectionHooks.useUpdate();
-
-    // Child features & actions
-    const { data: featuresData } = homepageFeatureHooks.useList(
-        { where: { sectionId }, orderBy: 'sortOrder', orderDirection: 'asc' },
-        { ...ADMIN_LIST_QUERY_CONFIG, enabled: !!sectionId },
-    );
-    const { data: actionsData } = homepageActionHooks.useList(
-        { where: { sectionId }, orderBy: 'sortOrder', orderDirection: 'asc' },
-        { ...ADMIN_LIST_QUERY_CONFIG, enabled: !!sectionId },
-    );
-
-    const createFeature = homepageFeatureHooks.useCreate();
-    const deleteFeature = homepageFeatureHooks.useDelete();
-    const updateFeature = homepageFeatureHooks.useUpdate();
-    const createAction = homepageActionHooks.useCreate();
-    const deleteAction = homepageActionHooks.useDelete();
-    const updateAction = homepageActionHooks.useUpdate();
-
-    const features = (Array.isArray(featuresData) ? featuresData : []) as HomepageFeatureRow[];
-    const actions = (Array.isArray(actionsData) ? actionsData : []) as HomepageActionRow[];
-
-    // Local section form state
-    const section = sectionData as Record<string, unknown> | undefined;
-    const [title, setTitle] = useState('');
-    const [subtitle, setSubtitle] = useState('');
-    const [body, setBody] = useState('');
-    const [githubUrl, setGithubUrl] = useState('');
-    const [icon, setIcon] = useState('');
-    const [enabled, setEnabled] = useState(true);
-    const [cssClasses, setCssClasses] = useState('');
-    const [metadataStr, setMetadataStr] = useState('');
-    const [initialized, setInitialized] = useState(false);
-
-    // Populate form when section data loads
-    useEffect(() => {
-        if (section && !initialized) {
-            setTitle((section.title as string) ?? '');
-            setSubtitle((section.subtitle as string) ?? '');
-            setBody((section.body as string) ?? '');
-            setGithubUrl((section.githubUrl as string) ?? '');
-            setIcon((section.icon as string) ?? '');
-            setEnabled((section.enabled as boolean) ?? true);
-            setCssClasses((section.cssClasses as string) ?? '');
-            const meta = section.metadata as Record<string, unknown> | null;
-            setMetadataStr(meta ? JSON.stringify(meta, null, 2) : '');
-            setInitialized(true);
-        }
-    }, [section, initialized]);
-
-    // Track previous enabled value for auto-save
-    const prevEnabledRef = useRef(enabled);
-    useEffect(() => {
-        if (initialized && enabled !== prevEnabledRef.current) {
-            prevEnabledRef.current = enabled;
-            if (sectionId) {
-                updateSection.mutate({ id: sectionId, data: { enabled } });
-            }
-        }
-    }, [enabled]); // eslint-disable-line react-hooks/exhaustive-deps
-
-    const [deleteDialog, setDeleteDialog] = useState<{ type: 'feature' | 'action'; id: string } | null>(null);
-
-    const slot = (section?.slot as string) ?? '';
-    const dirty =
-        initialized &&
-        (title !== ((section?.title as string) ?? '') ||
-            subtitle !== ((section?.subtitle as string) ?? '') ||
-            body !== ((section?.body as string) ?? '') ||
-            githubUrl !== ((section?.githubUrl as string) ?? '') ||
-            icon !== ((section?.icon as string) ?? '') ||
-            cssClasses !== ((section?.cssClasses as string) ?? '') ||
-            metadataStr !==
-                (section?.metadata ? JSON.stringify(section.metadata as Record<string, unknown>, null, 2) : ''));
-
-    const handleSaveSection = useCallback(async () => {
-        if (!sectionId || !dirty) return;
-        let metadata: Record<string, unknown> | undefined;
-        if (metadataStr.trim()) {
-            try {
-                metadata = JSON.parse(metadataStr);
-            } catch {
-                // Invalid JSON — skip metadata update
-            }
-        }
-        await updateSection.mutateAsync({
-            id: sectionId,
-            data: {
-                title,
-                subtitle,
-                body,
-                githubUrl,
-                icon: icon || undefined,
-                cssClasses: cssClasses || undefined,
-                ...(metadata !== undefined ? { metadata } : {}),
-            },
-        });
-    }, [sectionId, dirty, title, subtitle, body, githubUrl, icon, cssClasses, metadataStr, updateSection]);
-
-    const handleAddFeature = useCallback(async () => {
-        if (!sectionId) return;
-        await createFeature.mutateAsync({
-            sectionId,
-            title: 'New Feature',
-            description: 'Describe this feature',
-            sortOrder: features.length,
-        });
-    }, [sectionId, createFeature, features.length]);
-
-    const handleAddAction = useCallback(async () => {
-        if (!sectionId) return;
-        await createAction.mutateAsync({
-            sectionId,
-            label: 'New Button',
-            href: '/',
-            variant: 'default',
-            external: false,
-            sortOrder: actions.length,
-        });
-    }, [sectionId, createAction, actions.length]);
-
-    const handleMoveFeature = useCallback(
-        async (id: string, direction: 'up' | 'down') => {
-            const idx = features.findIndex((f) => f.id === id);
-            const swapIdx = direction === 'up' ? idx - 1 : idx + 1;
-            if (swapIdx < 0 || swapIdx >= features.length) return;
-            const other = features[swapIdx];
-            const current = features[idx];
-            await updateFeature.mutateAsync({ id: current.id, data: { sortOrder: other.sortOrder } });
-            await updateFeature.mutateAsync({ id: other.id, data: { sortOrder: current.sortOrder } });
-        },
-        [features, updateFeature],
-    );
-
-    const handleMoveAction = useCallback(
-        async (id: string, direction: 'up' | 'down') => {
-            const idx = actions.findIndex((a) => a.id === id);
-            const swapIdx = direction === 'up' ? idx - 1 : idx + 1;
-            if (swapIdx < 0 || swapIdx >= actions.length) return;
-            const other = actions[swapIdx];
-            const current = actions[idx];
-            await updateAction.mutateAsync({ id: current.id, data: { sortOrder: other.sortOrder } });
-            await updateAction.mutateAsync({ id: other.id, data: { sortOrder: current.sortOrder } });
-        },
-        [actions, updateAction],
-    );
-
-    const handleConfirmDelete = async () => {
-        if (!deleteDialog) return;
-        if (deleteDialog.type === 'feature') {
-            await deleteFeature.mutateAsync(deleteDialog.id);
-        } else {
-            await deleteAction.mutateAsync(deleteDialog.id);
-        }
-        setDeleteDialog(null);
-    };
-
-    if (sectionLoading) {
-        return (
-            <div className="space-y-6">
-                <HomepageAdminNav />
-                <Card>
-                    <CardContent className="py-12 text-center">
-                        <p className="text-muted-foreground">Loading section…</p>
-                    </CardContent>
-                </Card>
-            </div>
-        );
-    }
-
-    if (!section) {
-        return (
-            <div className="space-y-6">
-                <HomepageAdminNav />
-                <Card>
-                    <CardContent className="py-12 text-center">
-                        <p className="text-muted-foreground">Section not found.</p>
-                        <Button variant="outline" className="mt-4" onClick={() => navigate({ to: '/admin/homepage' })}>
-                            Back to Sections
-                        </Button>
-                    </CardContent>
-                </Card>
-            </div>
-        );
-    }
-
-    return (
-        <div className="space-y-6">
-            <HomepageAdminNav />
-
-            {/* Header */}
-            <div className="flex items-center gap-4">
-                <Button variant="ghost" size="icon" onClick={() => navigate({ to: '/admin/homepage' })}>
-                    <ArrowLeft className="h-4 w-4" />
-                </Button>
-                <div className="flex-1">
-                    <div className="flex items-center gap-2">
-                        <Badge variant="outline" className="font-mono text-xs">
-                            {slot}
-                        </Badge>
-                        {icon && (
-                            <Badge variant="secondary" className="text-xs font-mono">
-                                {icon}
-                            </Badge>
-                        )}
-                        <h1 className="text-2xl font-bold tracking-tight">{SLOT_LABELS[slot] ?? slot}</h1>
-                    </div>
-                    <p className="text-muted-foreground text-sm mt-0.5">
-                        Edit section content, features, actions, and display options.
-                    </p>
-                </div>
-                <div className="flex items-center gap-3">
-                    <div className="flex items-center gap-2">
-                        <Switch id="section-enabled" checked={enabled} onCheckedChange={setEnabled} />
-                        <Label htmlFor="section-enabled" className="text-sm">
-                            {enabled ? 'Visible' : 'Hidden'}
-                        </Label>
-                    </div>
-                    <Button onClick={handleSaveSection} disabled={!dirty || updateSection.isPending}>
-                        <Save className="mr-2 h-4 w-4" />
-                        {updateSection.isPending ? 'Saving…' : 'Save'}
-                    </Button>
-                </div>
-            </div>
-
-            {/* Section Content */}
-            <Card>
-                <CardHeader>
-                    <CardTitle className="text-base">Content</CardTitle>
-                    <CardDescription>Title, subtitle, and body text for this slot.</CardDescription>
-                </CardHeader>
-                <CardContent className="space-y-4">
-                    <div className="grid gap-4 md:grid-cols-2">
-                        <div className="space-y-2">
-                            <Label htmlFor="section-title">Title</Label>
-                            <Input
-                                id="section-title"
-                                value={title}
-                                onChange={(e) => setTitle(e.target.value)}
-                                placeholder="Section heading"
-                            />
-                        </div>
-                        <div className="space-y-2">
-                            <Label htmlFor="section-subtitle">Subtitle</Label>
-                            <Input
-                                id="section-subtitle"
-                                value={subtitle}
-                                onChange={(e) => setSubtitle(e.target.value)}
-                                placeholder="Optional subtitle or tagline"
-                            />
-                        </div>
-                    </div>
-                    <div className="space-y-2">
-                        <Label htmlFor="section-body">Body</Label>
-                        <Textarea
-                            id="section-body"
-                            value={body}
-                            onChange={(e) => setBody(e.target.value)}
-                            placeholder="Longer description (optional)"
-                            rows={4}
-                        />
-                    </div>
-                </CardContent>
-            </Card>
-
-            {/* Display Options */}
-            <Card>
-                <CardHeader>
-                    <CardTitle className="text-base">Display Options</CardTitle>
-                    <CardDescription>Icon, GitHub URL, CSS classes, and metadata.</CardDescription>
-                </CardHeader>
-                <CardContent className="space-y-4">
-                    <div className="grid gap-4 md:grid-cols-2">
-                        <div className="space-y-2">
-                            <Label htmlFor="section-icon">Icon</Label>
-                            <Input
-                                id="section-icon"
-                                value={icon}
-                                onChange={(e) => setIcon(e.target.value)}
-                                placeholder="Lucide icon name (e.g. Sparkles)"
-                            />
-                            <p className="text-xs text-muted-foreground">
-                                Suggestions: {ICON_SUGGESTIONS.slice(0, 8).join(', ')}
-                            </p>
-                        </div>
-                        <div className="space-y-2">
-                            <Label htmlFor="section-github">GitHub URL</Label>
-                            <Input
-                                id="section-github"
-                                value={githubUrl}
-                                onChange={(e) => setGithubUrl(e.target.value)}
-                                placeholder="https://github.com/..."
-                            />
-                        </div>
-                    </div>
-                    <div className="space-y-2">
-                        <Label htmlFor="section-css">CSS Classes</Label>
-                        <Input
-                            id="section-css"
-                            value={cssClasses}
-                            onChange={(e) => setCssClasses(e.target.value)}
-                            placeholder="Custom Tailwind classes (e.g. bg-gradient-to-r from-blue-500)"
-                        />
-                    </div>
-                    <div className="space-y-2">
-                        <Label htmlFor="section-metadata">Metadata (JSON)</Label>
-                        <Textarea
-                            id="section-metadata"
-                            value={metadataStr}
-                            onChange={(e) => setMetadataStr(e.target.value)}
-                            placeholder='{"key": "value"}'
-                            rows={3}
-                            className="font-mono text-sm"
-                        />
-                        <p className="text-xs text-muted-foreground">
-                            Arbitrary key-value data passed through to the frontend for custom rendering.
-                        </p>
-                    </div>
-                </CardContent>
-            </Card>
-
-            {/* Features */}
-            <Card>
-                <CardHeader className="pb-3">
-                    <div className="flex items-center justify-between">
-                        <div>
-                            <CardTitle className="text-base">Features ({features.length})</CardTitle>
-                            <CardDescription>Feature items with icon, image, and link support.</CardDescription>
-                        </div>
-                        <Button
-                            variant="outline"
-                            size="sm"
-                            onClick={handleAddFeature}
-                            disabled={createFeature.isPending}
-                        >
-                            <Plus className="mr-1.5 h-3.5 w-3.5" />
-                            Add Feature
-                        </Button>
-                    </div>
-                </CardHeader>
-                <CardContent>
-                    {features.length === 0 ? (
-                        <p className="text-sm text-muted-foreground py-4 text-center">
-                            No features yet. Add one to display feature items in this section.
-                        </p>
-                    ) : (
-                        <div className="space-y-2">
-                            {features.map((f, idx) => (
-                                <FeatureEditor
-                                    key={f.id}
-                                    feature={f}
-                                    onDelete={(id) => setDeleteDialog({ type: 'feature', id })}
-                                    onMove={handleMoveFeature}
-                                    isFirst={idx === 0}
-                                    isLast={idx === features.length - 1}
-                                />
-                            ))}
-                        </div>
-                    )}
-                </CardContent>
-            </Card>
-
-            {/* Actions */}
-            <Card>
-                <CardHeader className="pb-3">
-                    <div className="flex items-center justify-between">
-                        <div>
-                            <CardTitle className="text-base">Action Buttons ({actions.length})</CardTitle>
-                            <CardDescription>
-                                Call-to-action buttons with icon, style variant, and external link support.
-                            </CardDescription>
-                        </div>
-                        <Button variant="outline" size="sm" onClick={handleAddAction} disabled={createAction.isPending}>
-                            <Plus className="mr-1.5 h-3.5 w-3.5" />
-                            Add Action
-                        </Button>
-                    </div>
-                </CardHeader>
-                <CardContent>
-                    {actions.length === 0 ? (
-                        <p className="text-sm text-muted-foreground py-4 text-center">
-                            No actions yet. Add buttons like {'"'}Get Started{'"'} or {'"'}Learn More{'"'}.
-                        </p>
-                    ) : (
-                        <div className="space-y-2">
-                            {actions.map((a, idx) => (
-                                <ActionEditor
-                                    key={a.id}
-                                    action={a}
-                                    onDelete={(id) => setDeleteDialog({ type: 'action', id })}
-                                    onMove={handleMoveAction}
-                                    isFirst={idx === 0}
-                                    isLast={idx === actions.length - 1}
-                                />
-                            ))}
-                        </div>
-                    )}
-                </CardContent>
-            </Card>
-
-            {/* Delete confirmation */}
-            <AlertDialog open={deleteDialog !== null} onOpenChange={(open) => !open && setDeleteDialog(null)}>
-                <AlertDialogContent>
-                    <AlertDialogHeader>
-                        <AlertDialogTitle>
-                            Delete {deleteDialog?.type === 'feature' ? 'Feature' : 'Action'}?
-                        </AlertDialogTitle>
-                        <AlertDialogDescription>This item will be permanently removed.</AlertDialogDescription>
-                    </AlertDialogHeader>
-                    <AlertDialogFooter>
-                        <AlertDialogCancel>Cancel</AlertDialogCancel>
-                        <AlertDialogAction onClick={handleConfirmDelete}>Delete</AlertDialogAction>
-                    </AlertDialogFooter>
-                </AlertDialogContent>
-            </AlertDialog>
-        </div>
-    );
-}
diff --git a/apps/ottabase-template-app-tanstack/src/pages/admin/homepage/AdminHomepageSectionsPage.tsx b/apps/ottabase-template-app-tanstack/src/pages/admin/homepage/AdminHomepageSectionsPage.tsx
deleted file mode 100644
index 8fa1ca6e0..000000000
--- a/apps/ottabase-template-app-tanstack/src/pages/admin/homepage/AdminHomepageSectionsPage.tsx
+++ /dev/null
@@ -1,650 +0,0 @@
-/**
- * Admin Homepage Sections List
- *
- * Visual slot-based overview of all homepage sections with inline CRUD,
- * enable/disable toggles, sort controls, and nested feature/action editors.
- */
-import { ADMIN_LIST_QUERY_CONFIG } from '@/config/queryConfig';
-import {
-    homepageActionHooks,
-    homepageFeatureHooks,
-    homepageSectionHooks,
-    type HomepageActionRow,
-    type HomepageFeatureRow,
-    type HomepageSectionRow,
-} from '@/hooks/homepageHooks';
-import {
-    AlertDialog,
-    AlertDialogAction,
-    AlertDialogCancel,
-    AlertDialogContent,
-    AlertDialogDescription,
-    AlertDialogFooter,
-    AlertDialogHeader,
-    AlertDialogTitle,
-    Badge,
-    Button,
-    Card,
-    CardContent,
-    CardDescription,
-    CardHeader,
-    CardTitle,
-    Collapsible,
-    CollapsibleContent,
-    CollapsibleTrigger,
-    Input,
-    Label,
-    Switch,
-    Textarea,
-    Tooltip,
-    TooltipContent,
-    TooltipProvider,
-    TooltipTrigger,
-} from '@ottabase/ui-shadcn';
-import { IconDatabaseImport } from '@tabler/icons-react';
-import { Link } from '@tanstack/react-router';
-import {
-    ArrowDown,
-    ArrowUp,
-    ChevronDown,
-    Edit,
-    ExternalLink,
-    Eye,
-    EyeOff,
-    GripVertical,
-    Layout,
-    Plus,
-    Trash2,
-} from 'lucide-react';
-import { useQueryClient } from '@tanstack/react-query';
-import { useCallback, useState } from 'react';
-import { HomepageAdminNav } from './HomepageAdminNav';
-import { ACTION_VARIANTS, SLOT_DESCRIPTIONS, SLOT_LABELS, SLOT_NAMES, type SlotName } from './homepage-constants';
-
-// ── Inline mini-editors ─────────────────────────────────────────────────────
-
-/** Inline feature list for a section */
-function SectionFeatures({ sectionId }: { sectionId: string }) {
-    const { data, isLoading } = homepageFeatureHooks.useList(
-        { where: { sectionId }, orderBy: 'sortOrder', orderDirection: 'asc' },
-        ADMIN_LIST_QUERY_CONFIG,
-    );
-    const createFeature = homepageFeatureHooks.useCreate();
-    const deleteFeature = homepageFeatureHooks.useDelete();
-    const [adding, setAdding] = useState(false);
-    const [newTitle, setNewTitle] = useState('');
-    const [newDesc, setNewDesc] = useState('');
-    const [newIcon, setNewIcon] = useState('');
-
-    const features = (Array.isArray(data) ? data : []) as HomepageFeatureRow[];
-
-    const handleAdd = useCallback(async () => {
-        if (!newTitle.trim() || !newDesc.trim()) return;
-        await createFeature.mutateAsync({
-            sectionId,
-            title: newTitle.trim(),
-            description: newDesc.trim(),
-            icon: newIcon.trim() || undefined,
-            sortOrder: features.length,
-        });
-        setNewTitle('');
-        setNewDesc('');
-        setNewIcon('');
-        setAdding(false);
-    }, [createFeature, sectionId, newTitle, newDesc, newIcon, features.length]);
-
-    if (isLoading) return <p className="text-xs text-muted-foreground">Loading features…</p>;
-
-    return (
-        <div className="space-y-2">
-            <div className="flex items-center justify-between">
-                <p className="text-xs font-medium text-muted-foreground uppercase tracking-wider">
-                    Features ({features.length})
-                </p>
-                <Button variant="ghost" size="sm" className="h-6 px-2 text-xs" onClick={() => setAdding(!adding)}>
-                    <Plus className="mr-1 h-3 w-3" />
-                    Add
-                </Button>
-            </div>
-            {features.map((f) => (
-                <div key={f.id} className="flex items-start gap-2 rounded border p-2 text-sm">
-                    <GripVertical className="mt-0.5 h-3.5 w-3.5 shrink-0 text-muted-foreground/50" />
-                    {f.icon && (
-                        <Badge variant="outline" className="shrink-0 text-[10px] font-mono">
-                            {f.icon}
-                        </Badge>
-                    )}
-                    <div className="min-w-0 flex-1">
-                        <p className="font-medium">{f.title}</p>
-                        <p className="text-xs text-muted-foreground line-clamp-1">{f.description}</p>
-                    </div>
-                    <Button variant="ghost" size="icon" className="h-6 w-6" onClick={() => deleteFeature.mutate(f.id)}>
-                        <Trash2 className="h-3 w-3 text-destructive" />
-                    </Button>
-                </div>
-            ))}
-            {adding && (
-                <div className="space-y-2 rounded border border-dashed p-2">
-                    <div className="flex gap-2">
-                        <Input
-                            placeholder="Feature title"
-                            value={newTitle}
-                            onChange={(e) => setNewTitle(e.target.value)}
-                            className="h-8 text-sm"
-                        />
-                        <Input
-                            placeholder="Icon (e.g. Zap)"
-                            value={newIcon}
-                            onChange={(e) => setNewIcon(e.target.value)}
-                            className="h-8 text-sm w-32"
-                        />
-                    </div>
-                    <Textarea
-                        placeholder="Short description"
-                        value={newDesc}
-                        onChange={(e) => setNewDesc(e.target.value)}
-                        rows={2}
-                        className="text-sm"
-                    />
-                    <div className="flex gap-2">
-                        <Button
-                            size="sm"
-                            className="h-7 text-xs"
-                            onClick={handleAdd}
-                            disabled={createFeature.isPending}
-                        >
-                            Save
-                        </Button>
-                        <Button
-                            variant="ghost"
-                            size="sm"
-                            className="h-7 text-xs"
-                            onClick={() => {
-                                setAdding(false);
-                                setNewTitle('');
-                                setNewDesc('');
-                                setNewIcon('');
-                            }}
-                        >
-                            Cancel
-                        </Button>
-                    </div>
-                </div>
-            )}
-        </div>
-    );
-}
-
-/** Inline action list for a section */
-function SectionActions({ sectionId }: { sectionId: string }) {
-    const { data, isLoading } = homepageActionHooks.useList(
-        { where: { sectionId }, orderBy: 'sortOrder', orderDirection: 'asc' },
-        ADMIN_LIST_QUERY_CONFIG,
-    );
-    const createAction = homepageActionHooks.useCreate();
-    const deleteAction = homepageActionHooks.useDelete();
-    const [adding, setAdding] = useState(false);
-    const [newLabel, setNewLabel] = useState('');
-    const [newHref, setNewHref] = useState('');
-    const [newVariant, setNewVariant] = useState('default');
-    const [newIcon, setNewIcon] = useState('');
-
-    const actions = (Array.isArray(data) ? data : []) as HomepageActionRow[];
-
-    const handleAdd = useCallback(async () => {
-        if (!newLabel.trim() || !newHref.trim()) return;
-        await createAction.mutateAsync({
-            sectionId,
-            label: newLabel.trim(),
-            href: newHref.trim(),
-            variant: newVariant,
-            icon: newIcon.trim() || undefined,
-            external: newHref.startsWith('http'),
-            sortOrder: actions.length,
-        });
-        setNewLabel('');
-        setNewHref('');
-        setNewVariant('default');
-        setNewIcon('');
-        setAdding(false);
-    }, [createAction, sectionId, newLabel, newHref, newVariant, newIcon, actions.length]);
-
-    if (isLoading) return <p className="text-xs text-muted-foreground">Loading actions…</p>;
-
-    return (
-        <div className="space-y-2">
-            <div className="flex items-center justify-between">
-                <p className="text-xs font-medium text-muted-foreground uppercase tracking-wider">
-                    Actions ({actions.length})
-                </p>
-                <Button variant="ghost" size="sm" className="h-6 px-2 text-xs" onClick={() => setAdding(!adding)}>
-                    <Plus className="mr-1 h-3 w-3" />
-                    Add
-                </Button>
-            </div>
-            {actions.map((a) => (
-                <div key={a.id} className="flex items-center gap-2 rounded border p-2 text-sm">
-                    <GripVertical className="h-3.5 w-3.5 shrink-0 text-muted-foreground/50" />
-                    <Badge variant="outline" className="shrink-0 text-[10px]">
-                        {a.variant ?? 'default'}
-                    </Badge>
-                    {a.icon && (
-                        <Badge variant="secondary" className="shrink-0 text-[10px] font-mono">
-                            {a.icon}
-                        </Badge>
-                    )}
-                    <span className="truncate font-medium">{a.label}</span>
-                    <span className="ml-auto truncate text-xs text-muted-foreground">{a.href}</span>
-                    {a.external && <ExternalLink className="h-3 w-3 shrink-0 text-muted-foreground" />}
-                    <Button
-                        variant="ghost"
-                        size="icon"
-                        className="h-6 w-6 shrink-0"
-                        onClick={() => deleteAction.mutate(a.id)}
-                    >
-                        <Trash2 className="h-3 w-3 text-destructive" />
-                    </Button>
-                </div>
-            ))}
-            {adding && (
-                <div className="space-y-2 rounded border border-dashed p-2">
-                    <div className="flex gap-2">
-                        <Input
-                            placeholder="Label"
-                            value={newLabel}
-                            onChange={(e) => setNewLabel(e.target.value)}
-                            className="h-8 text-sm"
-                        />
-                        <Input
-                            placeholder="URL (e.g. /about or https://...)"
-                            value={newHref}
-                            onChange={(e) => setNewHref(e.target.value)}
-                            className="h-8 text-sm"
-                        />
-                    </div>
-                    <div className="flex items-center gap-2">
-                        <Label className="text-xs shrink-0">Style:</Label>
-                        <select
-                            value={newVariant}
-                            onChange={(e) => setNewVariant(e.target.value)}
-                            className="h-8 rounded-md border border-input bg-background px-2 text-xs"
-                            aria-label="Button variant"
-                        >
-                            {ACTION_VARIANTS.map((v) => (
-                                <option key={v.value} value={v.value}>
-                                    {v.label}
-                                </option>
-                            ))}
-                        </select>
-                        <Input
-                            placeholder="Icon (e.g. ArrowRight)"
-                            value={newIcon}
-                            onChange={(e) => setNewIcon(e.target.value)}
-                            className="h-8 text-sm w-40"
-                        />
-                    </div>
-                    <div className="flex gap-2">
-                        <Button size="sm" className="h-7 text-xs" onClick={handleAdd} disabled={createAction.isPending}>
-                            Save
-                        </Button>
-                        <Button
-                            variant="ghost"
-                            size="sm"
-                            className="h-7 text-xs"
-                            onClick={() => {
-                                setAdding(false);
-                                setNewLabel('');
-                                setNewHref('');
-                                setNewIcon('');
-                            }}
-                        >
-                            Cancel
-                        </Button>
-                    </div>
-                </div>
-            )}
-        </div>
-    );
-}
-
-// ── Main page ───────────────────────────────────────────────────────────────
-
-export function AdminHomepageSectionsPage() {
-    const queryClient = useQueryClient();
-    const { data, isLoading } = homepageSectionHooks.useList(
-        { orderBy: 'sortOrder', orderDirection: 'asc' },
-        ADMIN_LIST_QUERY_CONFIG,
-    );
-    const createSection = homepageSectionHooks.useCreate();
-    const updateSection = homepageSectionHooks.useUpdate();
-    const deleteSection = homepageSectionHooks.useDelete();
-    const [deleteDialog, setDeleteDialog] = useState<{ id: string; slot: string } | null>(null);
-    const [seeding, setSeeding] = useState(false);
-    const [seedResult, setSeedResult] = useState<'success' | 'exists' | 'error' | null>(null);
-
-    const sections = (Array.isArray(data) ? data : []) as HomepageSectionRow[];
-    const usedSlots = new Set(sections.map((s) => s.slot));
-    const availableSlots = SLOT_NAMES.filter((s) => !usedSlots.has(s));
-
-    const handleSeedDefaults = useCallback(async () => {
-        setSeeding(true);
-        setSeedResult(null);
-        try {
-            const res = await fetch('/api/homepage/seed', { method: 'POST' });
-            const body = await res.json();
-            if (body.skipped) {
-                setSeedResult('exists');
-            } else {
-                setSeedResult('success');
-                // Invalidate all homepage queries to refetch fresh data
-                queryClient.invalidateQueries({ queryKey: ['homepage_sections'] });
-                queryClient.invalidateQueries({ queryKey: ['homepage_features'] });
-                queryClient.invalidateQueries({ queryKey: ['homepage_actions'] });
-                queryClient.invalidateQueries({ queryKey: ['homepage_display_settings'] });
-            }
-        } catch (err) {
-            console.error('[AdminHomepage] Seed failed:', err);
-            setSeedResult('error');
-        } finally {
-            setSeeding(false);
-        }
-    }, [queryClient]);
-
-    const handleCreateSection = async (slot: string) => {
-        await createSection.mutateAsync({
-            slot,
-            title: SLOT_LABELS[slot as SlotName] ?? slot,
-            sortOrder: sections.length,
-            enabled: true,
-        });
-    };
-
-    const handleToggleEnabled = async (section: HomepageSectionRow) => {
-        await updateSection.mutateAsync({
-            id: section.id,
-            data: { enabled: !section.enabled },
-        });
-    };
-
-    const handleMoveSection = async (section: HomepageSectionRow, direction: 'up' | 'down') => {
-        const idx = sections.findIndex((s) => s.id === section.id);
-        const swapIdx = direction === 'up' ? idx - 1 : idx + 1;
-        if (swapIdx < 0 || swapIdx >= sections.length) return;
-        const other = sections[swapIdx];
-        // Swap sort orders
-        await updateSection.mutateAsync({ id: section.id, data: { sortOrder: other.sortOrder } });
-        await updateSection.mutateAsync({ id: other.id, data: { sortOrder: section.sortOrder } });
-    };
-
-    const handleConfirmDelete = async () => {
-        if (!deleteDialog) return;
-        try {
-            await deleteSection.mutateAsync(deleteDialog.id);
-        } catch (err) {
-            console.error('Failed to delete section:', err);
-        } finally {
-            setDeleteDialog(null);
-        }
-    };
-
-    const enabledCount = sections.filter((s) => s.enabled).length;
-    const totalFeatures = 0; // Could be computed if needed
-    const totalActions = 0;
-
-    return (
-        <div className="space-y-6">
-            <HomepageAdminNav />
-
-            {/* Header with stats */}
-            <div className="flex flex-col gap-4 sm:flex-row sm:items-center sm:justify-between">
-                <div>
-                    <h1 className="text-3xl font-bold tracking-tight">Homepage Sections</h1>
-                    <p className="text-muted-foreground mt-1">
-                        Manage content for each homepage slot. Toggle sections on/off, reorder, and edit inline.
-                    </p>
-                </div>
-                <div className="flex items-center gap-3">
-                    <TooltipProvider>
-                        <Tooltip>
-                            <TooltipTrigger asChild>
-                                <Button
-                                    variant="outline"
-                                    size="sm"
-                                    onClick={handleSeedDefaults}
-                                    disabled={seeding || sections.length > 0}
-                                    className="gap-1.5"
-                                >
-                                    <IconDatabaseImport className="h-4 w-4" />
-                                    {seeding ? 'Seeding…' : 'Seed Defaults'}
-                                </Button>
-                            </TooltipTrigger>
-                            <TooltipContent>
-                                {sections.length > 0
-                                    ? 'Sections already exist — seed is only for empty databases'
-                                    : 'Populate D1 with sample homepage data (sections, features, actions, display settings)'}
-                            </TooltipContent>
-                        </Tooltip>
-                    </TooltipProvider>
-                    {seedResult === 'success' && (
-                        <Badge variant="default" className="text-xs bg-green-600">
-                            Seeded!
-                        </Badge>
-                    )}
-                    {seedResult === 'exists' && (
-                        <Badge variant="secondary" className="text-xs">
-                            Already seeded
-                        </Badge>
-                    )}
-                    {seedResult === 'error' && (
-                        <Badge variant="destructive" className="text-xs">
-                            Seed failed
-                        </Badge>
-                    )}
-                    <Badge variant="secondary" className="text-xs">
-                        {enabledCount}/{sections.length} active
-                    </Badge>
-                </div>
-            </div>
-
-            {/* Quick-add for missing slots */}
-            {availableSlots.length > 0 && (
-                <Card>
-                    <CardHeader className="pb-3">
-                        <CardTitle className="text-base">Add Section</CardTitle>
-                        <CardDescription>
-                            Create a section for a slot that doesn{"'"}t have one yet. Each slot maps to a section on
-                            the homepage.
-                        </CardDescription>
-                    </CardHeader>
-                    <CardContent>
-                        <div className="grid gap-2 sm:grid-cols-2 md:grid-cols-3">
-                            {availableSlots.map((slot) => (
-                                <button
-                                    key={slot}
-                                    type="button"
-                                    onClick={() => handleCreateSection(slot)}
-                                    disabled={createSection.isPending}
-                                    className="flex items-start gap-3 rounded-lg border border-dashed p-3 text-left transition-colors hover:border-primary hover:bg-primary/5 disabled:opacity-50"
-                                >
-                                    <Plus className="mt-0.5 h-4 w-4 shrink-0 text-primary" />
-                                    <div className="min-w-0">
-                                        <p className="text-sm font-medium">{SLOT_LABELS[slot]}</p>
-                                        <p className="text-xs text-muted-foreground line-clamp-2">
-                                            {SLOT_DESCRIPTIONS[slot]}
-                                        </p>
-                                    </div>
-                                </button>
-                            ))}
-                        </div>
-                    </CardContent>
-                </Card>
-            )}
-
-            {/* Loading */}
-            {isLoading && (
-                <Card>
-                    <CardContent className="py-12 text-center">
-                        <p className="text-muted-foreground">Loading sections…</p>
-                    </CardContent>
-                </Card>
-            )}
-
-            {/* Empty state */}
-            {!isLoading && sections.length === 0 && (
-                <Card>
-                    <CardContent className="py-12 text-center">
-                        <Layout className="mx-auto h-12 w-12 text-muted-foreground/50" />
-                        <h3 className="mt-4 text-lg font-semibold">No sections yet</h3>
-                        <p className="mt-2 text-muted-foreground">
-                            Create sections for each homepage slot to populate your site with DB-driven content.
-                        </p>
-                    </CardContent>
-                </Card>
-            )}
-
-            {/* Section cards */}
-            <TooltipProvider>
-                {sections.map((section, idx) => (
-                    <Card key={section.id} className={`transition-opacity ${!section.enabled ? 'opacity-60' : ''}`}>
-                        <CardHeader className="pb-3">
-                            <div className="flex items-start justify-between gap-2">
-                                <div className="flex items-start gap-3 min-w-0">
-                                    {/* Enable/disable toggle */}
-                                    <Tooltip>
-                                        <TooltipTrigger asChild>
-                                            <button
-                                                type="button"
-                                                onClick={() => handleToggleEnabled(section)}
-                                                className="mt-0.5 shrink-0"
-                                                aria-label={section.enabled ? 'Disable section' : 'Enable section'}
-                                            >
-                                                {section.enabled ? (
-                                                    <Eye className="h-4 w-4 text-primary" />
-                                                ) : (
-                                                    <EyeOff className="h-4 w-4 text-muted-foreground" />
-                                                )}
-                                            </button>
-                                        </TooltipTrigger>
-                                        <TooltipContent>
-                                            {section.enabled
-                                                ? 'Click to hide this section'
-                                                : 'Click to show this section'}
-                                        </TooltipContent>
-                                    </Tooltip>
-                                    <div className="min-w-0">
-                                        <div className="flex flex-wrap items-center gap-2">
-                                            <Badge variant="outline" className="font-mono text-xs shrink-0">
-                                                {section.slot}
-                                            </Badge>
-                                            {section.icon && (
-                                                <Badge variant="secondary" className="text-[10px] font-mono shrink-0">
-                                                    {section.icon}
-                                                </Badge>
-                                            )}
-                                            <CardTitle className="text-lg">{section.title ?? '(untitled)'}</CardTitle>
-                                        </div>
-                                        {section.subtitle && (
-                                            <CardDescription className="mt-1">{section.subtitle}</CardDescription>
-                                        )}
-                                    </div>
-                                </div>
-                                <div className="flex items-center gap-1 shrink-0">
-                                    {/* Sort controls */}
-                                    <Tooltip>
-                                        <TooltipTrigger asChild>
-                                            <Button
-                                                variant="ghost"
-                                                size="icon"
-                                                className="h-8 w-8"
-                                                onClick={() => handleMoveSection(section, 'up')}
-                                                disabled={idx === 0 || updateSection.isPending}
-                                            >
-                                                <ArrowUp className="h-3.5 w-3.5" />
-                                            </Button>
-                                        </TooltipTrigger>
-                                        <TooltipContent>Move up</TooltipContent>
-                                    </Tooltip>
-                                    <Tooltip>
-                                        <TooltipTrigger asChild>
-                                            <Button
-                                                variant="ghost"
-                                                size="icon"
-                                                className="h-8 w-8"
-                                                onClick={() => handleMoveSection(section, 'down')}
-                                                disabled={idx === sections.length - 1 || updateSection.isPending}
-                                            >
-                                                <ArrowDown className="h-3.5 w-3.5" />
-                                            </Button>
-                                        </TooltipTrigger>
-                                        <TooltipContent>Move down</TooltipContent>
-                                    </Tooltip>
-                                    <Button variant="ghost" size="icon" className="h-8 w-8" asChild>
-                                        <Link to="/admin/homepage/$sectionId/edit" params={{ sectionId: section.id }}>
-                                            <Edit className="h-4 w-4" />
-                                        </Link>
-                                    </Button>
-                                    <Button
-                                        variant="ghost"
-                                        size="icon"
-                                        className="h-8 w-8"
-                                        onClick={() => setDeleteDialog({ id: section.id, slot: section.slot })}
-                                    >
-                                        <Trash2 className="h-4 w-4 text-destructive" />
-                                    </Button>
-                                </div>
-                            </div>
-                        </CardHeader>
-                        <CardContent className="space-y-3">
-                            {section.body && (
-                                <p className="text-sm text-muted-foreground line-clamp-2">{section.body}</p>
-                            )}
-                            {section.cssClasses && (
-                                <p className="text-xs font-mono text-muted-foreground">CSS: {section.cssClasses}</p>
-                            )}
-
-                            {/* Collapsible children */}
-                            <Collapsible>
-                                <CollapsibleTrigger asChild>
-                                    <Button
-                                        variant="ghost"
-                                        size="sm"
-                                        className="h-7 gap-1.5 text-xs w-full justify-start"
-                                    >
-                                        <ChevronDown className="h-3 w-3" />
-                                        Features & Actions
-                                    </Button>
-                                </CollapsibleTrigger>
-                                <CollapsibleContent>
-                                    <div className="grid gap-4 md:grid-cols-2 pt-2">
-                                        <SectionFeatures sectionId={section.id} />
-                                        <SectionActions sectionId={section.id} />
-                                    </div>
-                                </CollapsibleContent>
-                            </Collapsible>
-                        </CardContent>
-                    </Card>
-                ))}
-            </TooltipProvider>
-
-            {/* Delete confirmation */}
-            <AlertDialog open={deleteDialog !== null} onOpenChange={(open) => !open && setDeleteDialog(null)}>
-                <AlertDialogContent>
-                    <AlertDialogHeader>
-                        <AlertDialogTitle>Delete Section?</AlertDialogTitle>
-                        <AlertDialogDescription>
-                            This will permanently remove the {'"'}
-                            {deleteDialog?.slot}
-                            {'"'} section and all its features and actions. This cannot be undone.
-                        </AlertDialogDescription>
-                    </AlertDialogHeader>
-                    <AlertDialogFooter>
-                        <AlertDialogCancel disabled={deleteSection.isPending}>Cancel</AlertDialogCancel>
-                        <AlertDialogAction onClick={handleConfirmDelete} disabled={deleteSection.isPending}>
-                            Delete
-                        </AlertDialogAction>
-                    </AlertDialogFooter>
-                </AlertDialogContent>
-            </AlertDialog>
-        </div>
-    );
-}
diff --git a/apps/ottabase-template-app-tanstack/src/pages/admin/homepage/HomepageAdminNav.tsx b/apps/ottabase-template-app-tanstack/src/pages/admin/homepage/HomepageAdminNav.tsx
deleted file mode 100644
index 60cc8bfe6..000000000
--- a/apps/ottabase-template-app-tanstack/src/pages/admin/homepage/HomepageAdminNav.tsx
+++ /dev/null
@@ -1,52 +0,0 @@
-/**
- * Homepage Admin Navigation
- *
- * Tab navigation for the homepage management section.
- * Uses shadcn Tabs for a polished, consistent admin experience.
- */
-import { Link, useNavigate, useRouterState } from '@tanstack/react-router';
-import { Home, Layout, Monitor, FileText } from 'lucide-react';
-import { Tabs, TabsList, TabsTrigger } from '@ottabase/ui-shadcn';
-
-const TABS = [
-    { href: '/admin/homepage', label: 'Sections', icon: Layout, exact: true },
-    { href: '/admin/homepage/display', label: 'Display', icon: Monitor },
-    { href: '/admin/homepage/pages', label: 'Pages', icon: FileText },
-] as const;
-
-export function HomepageAdminNav() {
-    const { location } = useRouterState();
-    const navigate = useNavigate();
-    const pathname = location.pathname;
-
-    // Determine the active tab value from the current path
-    const activeTab =
-        TABS.find((tab) => ('exact' in tab && tab.exact ? pathname === tab.href : pathname.startsWith(tab.href)))
-            ?.href ?? TABS[0].href;
-
-    return (
-        <div className="space-y-4">
-            <div className="flex items-center gap-3">
-                <div className="flex items-center gap-2 rounded-lg bg-primary/10 p-2">
-                    <Home className="h-5 w-5 text-primary" />
-                </div>
-                <div>
-                    <h2 className="text-lg font-semibold tracking-tight">Homepage Manager</h2>
-                    <p className="text-xs text-muted-foreground">Configure sections, display settings, and CMS pages</p>
-                </div>
-            </div>
-            <Tabs value={activeTab} onValueChange={(v) => navigate({ to: v })}>
-                <TabsList className="w-full justify-start">
-                    {TABS.map(({ href, label, icon: Icon }) => (
-                        <TabsTrigger key={href} value={href} className="gap-1.5" asChild>
-                            <Link to={href}>
-                                <Icon className="h-3.5 w-3.5" />
-                                {label}
-                            </Link>
-                        </TabsTrigger>
-                    ))}
-                </TabsList>
-            </Tabs>
-        </div>
-    );
-}
diff --git a/apps/ottabase-template-app-tanstack/src/pages/admin/homepage/index.ts b/apps/ottabase-template-app-tanstack/src/pages/admin/homepage/index.ts
index 1e49e92be..09e34a46f 100644
--- a/apps/ottabase-template-app-tanstack/src/pages/admin/homepage/index.ts
+++ b/apps/ottabase-template-app-tanstack/src/pages/admin/homepage/index.ts
@@ -1,8 +1,4 @@
-export { AdminHomepageDisplayPage } from './AdminHomepageDisplayPage';
-export { AdminHomepagePagesPage } from './AdminHomepagePagesPage';
-export { AdminHomepageSectionEditorPage } from './AdminHomepageSectionEditorPage';
-export { AdminHomepageSectionsPage } from './AdminHomepageSectionsPage';
-export { HomepageAdminNav } from './HomepageAdminNav';
+export { AdminHomepageBuilderPage } from './AdminHomepageBuilderPage';
 export {
     ACTION_VARIANTS,
     ICON_SUGGESTIONS,
diff --git a/apps/ottabase-template-app-tanstack/src/router.tsx b/apps/ottabase-template-app-tanstack/src/router.tsx
index cdbe982ff..e8dae7739 100644
--- a/apps/ottabase-template-app-tanstack/src/router.tsx
+++ b/apps/ottabase-template-app-tanstack/src/router.tsx
@@ -931,43 +931,13 @@ const adminChangelogEditRoute = new Route({
     ),
 });
 
-// Homepage admin routes
+// Homepage admin routes (unified builder page)
 const adminHomepageRoute = new Route({
     getParentRoute: () => rootRoute,
     path: '/admin/homepage',
     component: lazyRouteComponent(() =>
-        import('@/pages/admin/homepage/AdminHomepageSectionsPage').then((m) => ({
-            default: () => renderAdminRoute(<m.AdminHomepageSectionsPage />),
-        })),
-    ),
-});
-
-const adminHomepageSectionEditRoute = new Route({
-    getParentRoute: () => rootRoute,
-    path: '/admin/homepage/$sectionId/edit',
-    component: lazyRouteComponent(() =>
-        import('@/pages/admin/homepage/AdminHomepageSectionEditorPage').then((m) => ({
-            default: () => renderAdminRoute(<m.AdminHomepageSectionEditorPage />),
-        })),
-    ),
-});
-
-const adminHomepageDisplayRoute = new Route({
-    getParentRoute: () => rootRoute,
-    path: '/admin/homepage/display',
-    component: lazyRouteComponent(() =>
-        import('@/pages/admin/homepage/AdminHomepageDisplayPage').then((m) => ({
-            default: () => renderAdminRoute(<m.AdminHomepageDisplayPage />),
-        })),
-    ),
-});
-
-const adminHomepagePagesRoute = new Route({
-    getParentRoute: () => rootRoute,
-    path: '/admin/homepage/pages',
-    component: lazyRouteComponent(() =>
-        import('@/pages/admin/homepage/AdminHomepagePagesPage').then((m) => ({
-            default: () => renderAdminRoute(<m.AdminHomepagePagesPage />),
+        import('@/pages/admin/homepage/AdminHomepageBuilderPage').then((m) => ({
+            default: () => renderAdminRoute(<m.AdminHomepageBuilderPage />),
         })),
     ),
 });
@@ -1204,9 +1174,6 @@ const coreRoutes = [
     adminChangelogNewRoute,
     adminChangelogEditRoute,
     adminHomepageRoute,
-    adminHomepageSectionEditRoute,
-    adminHomepageDisplayRoute,
-    adminHomepagePagesRoute,
     adminDevMailRoute,
     adminQueueRoute,
     adminCronRoute,
diff --git a/apps/ottabase-template-app-tanstack/worker/lib/db-utils.ts b/apps/ottabase-template-app-tanstack/worker/lib/db-utils.ts
index aa016b536..b6cf82dee 100644
--- a/apps/ottabase-template-app-tanstack/worker/lib/db-utils.ts
+++ b/apps/ottabase-template-app-tanstack/worker/lib/db-utils.ts
@@ -38,18 +38,18 @@ import { Shortlink } from '@ottabase/shortlinks';
 import { errorResponse } from '@ottabase/utils/http-errors';
 import { getOttabaseConfig } from '../../ottabase/config.loader';
 import { ChangelogEntry } from '../../ottabase/models/ChangelogEntry';
-import { changelogPolicy } from '../../ottabase/models/changelogPolicy';
-import {
-    homepageSectionPolicy,
-    homepageFeaturePolicy,
-    homepageActionPolicy,
-    homepageDisplaySettingsPolicy,
-} from '../../ottabase/models/homepagePolicy';
 import { HomepageAction } from '../../ottabase/models/HomepageAction';
 import { HomepageDisplaySettings } from '../../ottabase/models/HomepageDisplaySettings';
 import { HomepageFeature } from '../../ottabase/models/HomepageFeature';
 import { HomepageSection } from '../../ottabase/models/HomepageSection';
 import { Todo } from '../../ottabase/models/Todo';
+import { changelogPolicy } from '../../ottabase/models/changelogPolicy';
+import {
+    homepageActionPolicy,
+    homepageDisplaySettingsPolicy,
+    homepageFeaturePolicy,
+    homepageSectionPolicy,
+} from '../../ottabase/models/homepagePolicy';
 import { mediaLibraryPolicy } from '../../ottabase/models/mediaLibraryPolicy';
 import type { CloudflareEnv } from '../cloudflare-env';
 import { readJson } from './utils';
diff --git a/apps/ottabase-template-app-tanstack/worker/routes/homepage.ts b/apps/ottabase-template-app-tanstack/worker/routes/homepage.ts
index fab4ba986..076b96cd0 100644
--- a/apps/ottabase-template-app-tanstack/worker/routes/homepage.ts
+++ b/apps/ottabase-template-app-tanstack/worker/routes/homepage.ts
@@ -7,14 +7,9 @@
 // Pattern follows worker/routes/changelog.ts (public, read-only, no auth).
 // ============================================================
 
-import { Post } from '@ottabase/ottablog';
 import { createD1Driver } from '@ottabase/db/drizzle-d1';
-import type {
-    HomepageSectionPayload,
-    HomepageDisplayPayload,
-    HomepageDataPayload,
-    ExposedPage,
-} from '@ottabase/homepage-contract';
+import type { HomepageDataPayload, HomepageDisplayPayload, HomepageSectionPayload } from '@ottabase/homepage-contract';
+import { Post } from '@ottabase/ottablog';
 import { registerConnection } from '@ottabase/ottaorm';
 import { errorResponse } from '@ottabase/utils/http-errors';
 import { jsonResponse } from '@ottabase/utils/http-response';
@@ -79,12 +74,12 @@ export async function handleHomepageData(context: HomepageRouteContext): Promise
 
         if (sectionIds.length > 0) {
             allFeatures = (await HomepageFeature.where(
-                { sectionId: { $in: sectionIds } },
+                { sectionId: sectionIds },
                 { orderBy: 'sortOrder', orderDirection: 'asc' },
             )) as InstanceType<typeof HomepageFeature>[];
 
             allActions = (await HomepageAction.where(
-                { sectionId: { $in: sectionIds } },
+                { sectionId: sectionIds },
                 { orderBy: 'sortOrder', orderDirection: 'asc' },
             )) as InstanceType<typeof HomepageAction>[];
         }

From 8efb3da5ac79795e762524ebe00bd71b38fd7ebc Mon Sep 17 00:00:00 2001
From: Deepak Thomas <think.dj@gmail.com>
Date: Tue, 31 Mar 2026 21:52:16 +0530
Subject: [PATCH 18/19] Add flexible pages system & marketing pages UI

Introduce a new flexible Marketing Pages system and wire it into frontend/admin workflows.

Key changes:
- Add DB schemas, models and RLS policies for pages, page_sections, page_features, and page_actions (drizzle/ottaorm) to support block-based and content pages.
- Add admin-side hooks and pages (pageHooks, admin pages list, page builder) and register a new "Marketing Pages" entry in the admin index.
- Add a detailed PAGES_README documenting the new pages system, API routes and usage.
- Add Next.js frontend support: dynamic route for /{slug} (app/[slug]/page.tsx) and a client renderer (MarketingPageContent) that maps page sections to slot components.
- Extend lib/api to fetch pages (fetchPageByPageSlug, fetchNavPages) and re-export additional contract types.
- Update layout/brand-server to read themePreset from homepage data and pass it into generateBrandConfig for SSR theme resolution.
- Update DB schema helper to include the new page tables (kept legacy homepage tables for migration).
- Add drag-and-drop deps to the TanStack app package.json (dnd-kit) for builder UX.

These changes implement an additive pages system (homepage remains compatible) and provide API/DB/admin/frontend support for creating and rendering multi-page marketing content.
---
 .../app/[slug]/marketing-page-content.tsx     |  213 +++
 .../app/[slug]/page.tsx                       |   69 +
 .../app/layout.tsx                            |   14 +-
 .../lib/api.ts                                |   57 +-
 .../lib/brand-server.ts                       |   11 +-
 .../ottabase/db/schemas-helper.ts             |   18 +
 .../ottabase/models/PAGES_README.md           |  167 +++
 .../ottabase/models/Page.schema.ts            |   92 ++
 .../ottabase/models/Page.ts                   |   61 +
 .../ottabase/models/PageAction.schema.ts      |   47 +
 .../ottabase/models/PageAction.ts             |   24 +
 .../ottabase/models/PageFeature.schema.ts     |   45 +
 .../ottabase/models/PageFeature.ts            |   24 +
 .../ottabase/models/PageSection.schema.ts     |   88 ++
 .../ottabase/models/PageSection.ts            |   35 +
 .../ottabase/models/pagePolicy.ts             |   48 +
 .../package.json                              |    3 +
 .../src/hooks/pageHooks.ts                    |  135 ++
 .../src/pages/admin/AdminIndexPage.tsx        |    7 +
 .../homepage/AdminHomepageBuilderPage.tsx     | 1283 ++++++++---------
 .../admin/pages/AdminPageBuilderPage.tsx      |  838 +++++++++++
 .../pages/admin/pages/AdminPagesListPage.tsx  |  299 ++++
 .../admin/pages/MarketingPageBuilder.tsx      | 1253 ++++++++++++++++
 .../src/pages/admin/pages/index.ts            |    7 +
 .../src/pages/admin/pages/pages-constants.ts  |  304 ++++
 .../src/router.tsx                            |   23 +
 .../worker/lib/db-utils.ts                    |   17 +-
 .../worker/routes/pages.ts                    |  599 ++++++++
 .../worker/routes/router.ts                   |   33 +-
 packages/homepage-contract/src/index.ts       |   60 +-
 packages/homepage-contract/src/schemas.ts     |  133 +-
 packages/homepage-contract/src/types.ts       |   57 +-
 pnpm-lock.yaml                                |   56 +
 33 files changed, 5373 insertions(+), 747 deletions(-)
 create mode 100644 apps/ottabase-template-app-nextjs-homepage/app/[slug]/marketing-page-content.tsx
 create mode 100644 apps/ottabase-template-app-nextjs-homepage/app/[slug]/page.tsx
 create mode 100644 apps/ottabase-template-app-tanstack/ottabase/models/PAGES_README.md
 create mode 100644 apps/ottabase-template-app-tanstack/ottabase/models/Page.schema.ts
 create mode 100644 apps/ottabase-template-app-tanstack/ottabase/models/Page.ts
 create mode 100644 apps/ottabase-template-app-tanstack/ottabase/models/PageAction.schema.ts
 create mode 100644 apps/ottabase-template-app-tanstack/ottabase/models/PageAction.ts
 create mode 100644 apps/ottabase-template-app-tanstack/ottabase/models/PageFeature.schema.ts
 create mode 100644 apps/ottabase-template-app-tanstack/ottabase/models/PageFeature.ts
 create mode 100644 apps/ottabase-template-app-tanstack/ottabase/models/PageSection.schema.ts
 create mode 100644 apps/ottabase-template-app-tanstack/ottabase/models/PageSection.ts
 create mode 100644 apps/ottabase-template-app-tanstack/ottabase/models/pagePolicy.ts
 create mode 100644 apps/ottabase-template-app-tanstack/src/hooks/pageHooks.ts
 create mode 100644 apps/ottabase-template-app-tanstack/src/pages/admin/pages/AdminPageBuilderPage.tsx
 create mode 100644 apps/ottabase-template-app-tanstack/src/pages/admin/pages/AdminPagesListPage.tsx
 create mode 100644 apps/ottabase-template-app-tanstack/src/pages/admin/pages/MarketingPageBuilder.tsx
 create mode 100644 apps/ottabase-template-app-tanstack/src/pages/admin/pages/index.ts
 create mode 100644 apps/ottabase-template-app-tanstack/src/pages/admin/pages/pages-constants.ts
 create mode 100644 apps/ottabase-template-app-tanstack/worker/routes/pages.ts

diff --git a/apps/ottabase-template-app-nextjs-homepage/app/[slug]/marketing-page-content.tsx b/apps/ottabase-template-app-nextjs-homepage/app/[slug]/marketing-page-content.tsx
new file mode 100644
index 000000000..332b0fa25
--- /dev/null
+++ b/apps/ottabase-template-app-nextjs-homepage/app/[slug]/marketing-page-content.tsx
@@ -0,0 +1,213 @@
+'use client';
+
+/**
+ * Marketing Page Content
+ *
+ * Renders the block-based sections of a marketing page using existing slot components.
+ * Transforms PageDataPayload sections into slot-specific data shapes.
+ */
+
+import type { PageDataPayload, PageSectionPayload } from '@ottabase/homepage-contract';
+import { SlotRenderer } from '../../components/SlotRenderer';
+import type { AboutData } from '../../components/variants/about';
+import type { CTAAction, CTAData } from '../../components/variants/cta';
+import type { FeaturesData } from '../../components/variants/features';
+import type { FooterData } from '../../components/variants/footer';
+import type { HeroAction, HeroData } from '../../components/variants/hero';
+import type { NavbarData } from '../../components/variants/navbar';
+
+interface MarketingPageContentProps {
+    pageData: PageDataPayload;
+    isPreview?: boolean;
+}
+
+// Valid button variants
+type ButtonVariant = 'default' | 'secondary' | 'outline' | 'ghost';
+const VALID_VARIANTS: ButtonVariant[] = ['default', 'secondary', 'outline', 'ghost'];
+
+function toButtonVariant(v: string | null | undefined): ButtonVariant {
+    if (v && VALID_VARIANTS.includes(v as ButtonVariant)) {
+        return v as ButtonVariant;
+    }
+    return 'default';
+}
+
+/**
+ * Transform a PageSectionPayload into the data shape expected by each slot variant.
+ */
+function transformSection(section: PageSectionPayload): { slot: string; data: Record<string, unknown> } | null {
+    const { slot, title, subtitle, body, features, actions, githubUrl } = section;
+
+    switch (slot) {
+        case 'hero':
+            return {
+                slot: 'hero',
+                data: {
+                    title: title || 'Welcome',
+                    subtitle: subtitle || undefined,
+                    body: body || undefined,
+                    actions: actions.map(
+                        (a): HeroAction => ({
+                            label: a.label,
+                            href: a.href,
+                            variant: toButtonVariant(a.variant),
+                            external: a.external,
+                        }),
+                    ),
+                } satisfies HeroData,
+            };
+
+        case 'features':
+            return {
+                slot: 'features',
+                data: {
+                    title: title || undefined,
+                    features: features.map((f) => ({
+                        title: f.title,
+                        description: f.description || '',
+                        icon: f.icon || undefined,
+                        href: f.href || undefined,
+                    })),
+                } satisfies FeaturesData,
+            };
+
+        case 'cta':
+            return {
+                slot: 'cta',
+                data: {
+                    title: title || 'Ready to Get Started?',
+                    description: subtitle || body || undefined,
+                    actions: actions.map(
+                        (a): CTAAction => ({
+                            label: a.label,
+                            href: a.href,
+                            variant: toButtonVariant(a.variant),
+                            external: a.external,
+                        }),
+                    ),
+                } satisfies CTAData,
+            };
+
+        case 'about':
+            return {
+                slot: 'about',
+                data: {
+                    title: title || 'About',
+                    description: subtitle || body || undefined,
+                    githubUrl: githubUrl || undefined,
+                } satisfies AboutData,
+            };
+
+        case 'navbar':
+            return {
+                slot: 'navbar',
+                data: {
+                    title: title || 'Ottabase',
+                    githubUrl: githubUrl || undefined,
+                } satisfies NavbarData,
+            };
+
+        case 'footer':
+            return {
+                slot: 'footer',
+                data: {
+                    siteName: title || 'Ottabase',
+                    tagline: subtitle || body || undefined,
+                } satisfies FooterData,
+            };
+
+        // Slots that don't have specific components yet - render as CTA-style sections
+        case 'testimonials':
+        case 'gallery':
+        case 'team':
+        case 'pricing':
+        case 'faq':
+        case 'video':
+        case 'code':
+        case 'custom':
+            return {
+                slot: 'cta',
+                data: {
+                    title: title || slot.charAt(0).toUpperCase() + slot.slice(1),
+                    description: subtitle || body || undefined,
+                    actions: actions.map(
+                        (a): CTAAction => ({
+                            label: a.label,
+                            href: a.href,
+                            variant: toButtonVariant(a.variant),
+                            external: a.external,
+                        }),
+                    ),
+                } satisfies CTAData,
+            };
+
+        default:
+            return null;
+    }
+}
+
+export function MarketingPageContent({ pageData, isPreview = false }: MarketingPageContentProps) {
+    const { sections, page } = pageData;
+
+    // Filter to enabled sections and sort by sortOrder
+    const enabledSections = sections.filter((s) => s.enabled !== false).sort((a, b) => a.sortOrder - b.sortOrder);
+
+    // Check for navbar and footer
+    const navbarSection = enabledSections.find((s) => s.slot === 'navbar');
+    const footerSection = enabledSections.find((s) => s.slot === 'footer');
+    const contentSections = enabledSections.filter((s) => s.slot !== 'navbar' && s.slot !== 'footer');
+
+    return (
+        <div className="min-h-screen flex flex-col">
+            {/* Preview Banner */}
+            {isPreview && (
+                <div className="bg-amber-500 text-black px-4 py-2 text-center text-sm font-medium">
+                    Preview Mode — This page is {page.status}. Only you can see this preview.
+                </div>
+            )}
+            {/* Navbar */}
+            {navbarSection &&
+                (() => {
+                    const transformed = transformSection(navbarSection);
+                    if (!transformed) return null;
+                    return <SlotRenderer slot={transformed.slot as 'navbar'} data={transformed.data as NavbarData} />;
+                })()}
+
+            {/* Main content sections */}
+            <main className="flex-1">
+                {contentSections.map((section) => {
+                    const transformed = transformSection(section);
+                    if (!transformed) return null;
+
+                    // Type-safe rendering based on slot
+                    switch (transformed.slot) {
+                        case 'hero':
+                            return <SlotRenderer key={section.id} slot="hero" data={transformed.data as HeroData} />;
+                        case 'features':
+                            return (
+                                <SlotRenderer
+                                    key={section.id}
+                                    slot="features"
+                                    data={transformed.data as FeaturesData}
+                                />
+                            );
+                        case 'cta':
+                            return <SlotRenderer key={section.id} slot="cta" data={transformed.data as CTAData} />;
+                        case 'about':
+                            return <SlotRenderer key={section.id} slot="about" data={transformed.data as AboutData} />;
+                        default:
+                            return null;
+                    }
+                })}
+            </main>
+
+            {/* Footer */}
+            {footerSection &&
+                (() => {
+                    const transformed = transformSection(footerSection);
+                    if (!transformed) return null;
+                    return <SlotRenderer slot={transformed.slot as 'footer'} data={transformed.data as FooterData} />;
+                })()}
+        </div>
+    );
+}
diff --git a/apps/ottabase-template-app-nextjs-homepage/app/[slug]/page.tsx b/apps/ottabase-template-app-nextjs-homepage/app/[slug]/page.tsx
new file mode 100644
index 000000000..789e8e55a
--- /dev/null
+++ b/apps/ottabase-template-app-nextjs-homepage/app/[slug]/page.tsx
@@ -0,0 +1,69 @@
+/**
+ * Dynamic Marketing Page Route
+ *
+ * Handles marketing pages created via Admin → Marketing Pages.
+ * Fetches page data from /api/pages/:slug and renders block-based layouts.
+ *
+ * Routes:
+ * - /{slug} → This component (e.g., /pricing, /about-us, /features)
+ * - / (homepage) → app/(site)/page.tsx
+ * - /page/{slug} → app/page/[slug]/page.tsx (ottablog content pages)
+ */
+import type { Metadata } from 'next';
+import { notFound } from 'next/navigation';
+import { fetchPageByPageSlug } from '../../lib/api';
+import { MarketingPageContent } from './marketing-page-content';
+
+interface PageProps {
+    params: Promise<{ slug: string }>;
+    searchParams: Promise<{ preview?: string }>;
+}
+
+export async function generateMetadata({ params, searchParams }: PageProps): Promise<Metadata> {
+    const { slug } = await params;
+    const { preview } = await searchParams;
+    const isPreview = preview === 'true';
+
+    // Don't handle homepage here - let (site)/page.tsx handle it
+    if (slug === 'homepage') {
+        return { title: 'Home' };
+    }
+
+    const pageData = await fetchPageByPageSlug(slug, isPreview);
+    if (!pageData) return { title: 'Not Found' };
+
+    return {
+        title: pageData.display.seoTitle || pageData.page.title,
+        description: pageData.display.seoDescription || undefined,
+        openGraph: pageData.display.seoImage
+            ? {
+                  images: [{ url: pageData.display.seoImage }],
+              }
+            : undefined,
+    };
+}
+
+export default async function MarketingPage({ params, searchParams }: PageProps) {
+    const { slug } = await params;
+    const { preview } = await searchParams;
+    const isPreview = preview === 'true';
+
+    // Don't handle homepage here - redirect or let (site)/page.tsx handle it
+    if (slug === 'homepage') {
+        notFound(); // Or redirect to /
+    }
+
+    const pageData = await fetchPageByPageSlug(slug, isPreview);
+
+    // If no marketing page found, show 404
+    if (!pageData) {
+        notFound();
+    }
+
+    // Only show published pages (unless in preview mode)
+    if (!isPreview && pageData.page.status !== 'published') {
+        notFound();
+    }
+
+    return <MarketingPageContent pageData={pageData} isPreview={isPreview} />;
+}
diff --git a/apps/ottabase-template-app-nextjs-homepage/app/layout.tsx b/apps/ottabase-template-app-nextjs-homepage/app/layout.tsx
index b99eae388..d0bd81870 100644
--- a/apps/ottabase-template-app-nextjs-homepage/app/layout.tsx
+++ b/apps/ottabase-template-app-nextjs-homepage/app/layout.tsx
@@ -1,7 +1,7 @@
 import { buildCriticalCSS } from '@ottabase/brand-engine';
 import type { Metadata } from 'next';
-import { getHomepageData } from '../lib/get-homepage-data';
 import { generateBrandConfig } from '../lib/brand-server';
+import { getHomepageData } from '../lib/get-homepage-data';
 import './globals.css';
 import { LayoutShell } from './layout-shell';
 import { Providers } from './providers';
@@ -15,20 +15,20 @@ export const metadata: Metadata = {
 };
 
 export default async function RootLayout({ children }: { children: React.ReactNode }) {
-    // Generate brand config server-side (SSR)
+    // Fetch homepage data FIRST to get the theme preset from DB
+    const homepageData = await getHomepageData();
+    const themePresetId = homepageData.display.themePreset ?? null;
+
+    // Generate brand config server-side using the API theme preset
     // Note: Using 'light' for initial SSR. BrandProvider will handle dynamic theme switching on client.
-    const brandConfig = generateBrandConfig('light');
+    const brandConfig = generateBrandConfig('light', themePresetId);
     const theme = brandConfig.brandKitsMap.default.theme;
 
     // Generate critical CSS for SSR (prevents FOUC)
     const criticalCSS = buildCriticalCSS(theme);
 
-    // Fetch and validate full homepage data from the worker API (Zod-validated)
-    const homepageData = await getHomepageData();
-
     // Extract display settings for Providers
     const initialHomepageConfig = homepageData.display.variantBySlot ?? null;
-    const themePresetId = homepageData.display.themePreset ?? null;
 
     // Apply SEO overrides from DB if available
     const seoTitle = homepageData.display.seoTitle;
diff --git a/apps/ottabase-template-app-nextjs-homepage/lib/api.ts b/apps/ottabase-template-app-nextjs-homepage/lib/api.ts
index 131ab63bb..ed5ecde8a 100644
--- a/apps/ottabase-template-app-nextjs-homepage/lib/api.ts
+++ b/apps/ottabase-template-app-nextjs-homepage/lib/api.ts
@@ -8,16 +8,23 @@
  * always agree on the payload shape.
  */
 
-import type { HomepageDataPayload, ExposedPage } from '@ottabase/homepage-contract';
+import type { ExposedPage, HomepageDataPayload, NavPagesPayload, PageDataPayload } from '@ottabase/homepage-contract';
 
 // Re-export shared contract types so existing imports continue to work
 export type {
     ExposedPage,
-    HomepageSectionPayload,
-    HomepageDisplayPayload,
+    HomepageActionPayload,
     HomepageDataPayload,
+    HomepageDisplayPayload,
     HomepageFeaturePayload,
-    HomepageActionPayload,
+    HomepageSectionPayload,
+    NavPagePayload,
+    NavPagesPayload,
+    // New flexible page system types
+    PageDataPayload,
+    PageDisplayPayload,
+    PageMetaPayload,
+    PageSectionPayload,
 } from '@ottabase/homepage-contract';
 
 const API_URL = process.env.NEXT_PUBLIC_API_URL ?? '';
@@ -129,3 +136,45 @@ export async function fetchExposedPages(): Promise<ExposedPage[]> {
         return [];
     }
 }
+
+// ============================================================================
+// NEW FLEXIBLE PAGE SYSTEM API
+// ============================================================================
+
+/**
+ * Fetch page data by slug from the new flexible page system.
+ * Use this for pages created via /admin/pages.
+ * Returns null on error.
+ */
+export async function fetchPageByPageSlug(slug: string, preview = false): Promise<PageDataPayload | null> {
+    if (!API_URL) return null;
+    try {
+        const url = new URL(`${API_URL}/api/pages/${encodeURIComponent(slug)}`);
+        if (preview) url.searchParams.set('preview', 'true');
+        const res = await fetch(url.toString(), {
+            next: { revalidate: preview ? 0 : 60 }, // No cache in preview mode
+        });
+        if (!res.ok) return null;
+        return await res.json();
+    } catch {
+        return null;
+    }
+}
+
+/**
+ * Fetch nav-enabled pages from the new flexible page system.
+ * Returns pages marked with showInNav=true, sorted by navOrder.
+ */
+export async function fetchNavPages(): Promise<NavPagesPayload['pages']> {
+    if (!API_URL) return [];
+    try {
+        const res = await fetch(`${API_URL}/api/pages/nav`, {
+            next: { revalidate: 60 },
+        });
+        if (!res.ok) return [];
+        const data: NavPagesPayload = await res.json();
+        return Array.isArray(data.pages) ? data.pages : [];
+    } catch {
+        return [];
+    }
+}
diff --git a/apps/ottabase-template-app-nextjs-homepage/lib/brand-server.ts b/apps/ottabase-template-app-nextjs-homepage/lib/brand-server.ts
index f0c7f26c6..154939478 100644
--- a/apps/ottabase-template-app-nextjs-homepage/lib/brand-server.ts
+++ b/apps/ottabase-template-app-nextjs-homepage/lib/brand-server.ts
@@ -13,10 +13,13 @@ registerBuiltInThemes();
  * Generate brand configuration for SSR
  * This replaces the need for a /api/brand endpoint
  * Generates both light and dark themes for client-side switching
+ * @param mode - Initial color mode (light/dark)
+ * @param themePresetId - Theme preset from API (overrides hardcoded config)
  */
-export function generateBrandConfig(mode: 'light' | 'dark' = 'light'): FullBrandConfig {
-    // Get the theme preset
-    const baseTheme = getThemeByName(themePreset) || getThemeByName('default')!;
+export function generateBrandConfig(mode: 'light' | 'dark' = 'light', themePresetId?: string | null): FullBrandConfig {
+    // Get the theme preset - API value takes precedence over config
+    const presetName = themePresetId || themePreset;
+    const baseTheme = getThemeByName(presetName) || getThemeByName('default')!;
 
     // Resolve both light and dark themes
     const lightTheme = resolveTheme({
@@ -54,7 +57,7 @@ export function generateBrandConfig(mode: 'light' | 'dark' = 'light'): FullBrand
                 logos: {},
                 theme: lightTheme,
                 darkTheme: darkTheme,
-                themeBase: themePreset,
+                themeBase: presetName,
                 tenantTheme: brandConfig,
                 defaultColorScheme: 'system',
                 allowDarkModeToggle: true,
diff --git a/apps/ottabase-template-app-tanstack/ottabase/db/schemas-helper.ts b/apps/ottabase-template-app-tanstack/ottabase/db/schemas-helper.ts
index 23df84d12..cd62f0e82 100644
--- a/apps/ottabase-template-app-tanstack/ottabase/db/schemas-helper.ts
+++ b/apps/ottabase-template-app-tanstack/ottabase/db/schemas-helper.ts
@@ -34,10 +34,16 @@ import {
 } from '@ottabase/ottaorm';
 import { getEnabledPackageTables } from '../config.migrations';
 import { changelogEntriesTable } from '../models/ChangelogEntry';
+// Legacy homepage tables (will be migrated to pages)
 import { homepageActionsTable } from '../models/HomepageAction';
 import { homepageDisplaySettingsTable } from '../models/HomepageDisplaySettings';
 import { homepageFeaturesTable } from '../models/HomepageFeature';
 import { homepageSectionsTable } from '../models/HomepageSection';
+// New flexible page system
+import { pagesTable } from '../models/Page';
+import { pageActionsTable } from '../models/PageAction';
+import { pageFeaturesTable } from '../models/PageFeature';
+import { pageSectionsTable } from '../models/PageSection';
 import { todosTable } from '../models/Todo';
 
 /**
@@ -67,10 +73,16 @@ export function getAllSchemas() {
     const appTables = {
         changelogEntriesTable,
         todosTable,
+        // Legacy homepage (kept for migration)
         homepageSectionsTable,
         homepageFeaturesTable,
         homepageActionsTable,
         homepageDisplaySettingsTable,
+        // New flexible page system
+        pagesTable,
+        pageSectionsTable,
+        pageFeaturesTable,
+        pageActionsTable,
     };
 
     // 3. Package schemas from enabled packages (ottablog, shortlinks, referrals, etc.)
@@ -113,10 +125,16 @@ export function getSchemaSummary() {
     const appTables = {
         changelogEntriesTable,
         todosTable,
+        // Legacy homepage (kept for migration)
         homepageSectionsTable,
         homepageFeaturesTable,
         homepageActionsTable,
         homepageDisplaySettingsTable,
+        // New flexible page system
+        pagesTable,
+        pageSectionsTable,
+        pageFeaturesTable,
+        pageActionsTable,
     };
 
     const packageTables = getEnabledPackageTables();
diff --git a/apps/ottabase-template-app-tanstack/ottabase/models/PAGES_README.md b/apps/ottabase-template-app-tanstack/ottabase/models/PAGES_README.md
new file mode 100644
index 000000000..ce9be8208
--- /dev/null
+++ b/apps/ottabase-template-app-tanstack/ottabase/models/PAGES_README.md
@@ -0,0 +1,167 @@
+# Marketing Pages System
+
+A drag-and-drop page builder for creating marketing pages, landing pages, about pages, and more.
+
+## Overview
+
+The Marketing Pages system provides:
+
+1. **Block-based Pages**: Build pages with reusable blocks (hero, features, CTA, pricing, FAQ, etc.)
+2. **Content Pages**: Rich text pages that link to ottablog Post content
+3. **Drag-and-Drop Editor**: Visual page builder with block palette and reordering
+4. **Multi-page Support**: Create unlimited marketing pages beyond the homepage
+
+## Schema
+
+### Core Entities
+
+| Table           | Purpose                                             |
+| --------------- | --------------------------------------------------- |
+| `pages`         | Page metadata, slug, type, status, SEO settings     |
+| `page_sections` | Blocks within a page (hero, features, footer, etc.) |
+| `page_features` | Feature items within sections                       |
+| `page_actions`  | CTA buttons within sections                         |
+
+### Page Types
+
+- **`block`**: Section-based page (landing pages, marketing pages)
+- **`content`**: Links to an ottablog Post for rich text content
+
+### Page Status
+
+- **`draft`**: Not visible to public
+- **`published`**: Visible and accessible
+- **`archived`**: Hidden but preserved
+
+## API Routes
+
+### Public Routes
+
+| Route              | Method | Description                |
+| ------------------ | ------ | -------------------------- |
+| `/api/pages`       | GET    | List all published pages   |
+| `/api/pages/nav`   | GET    | Get nav-enabled pages      |
+| `/api/pages/:slug` | GET    | Get full page data by slug |
+| `/api/pages/seed`  | POST   | Seed default homepage      |
+
+### Legacy Routes (kept for compatibility)
+
+| Route                | Description                     |
+| -------------------- | ------------------------------- |
+| `/api/homepage/data` | Original homepage data endpoint |
+| `/api/homepage/seed` | Original homepage seed endpoint |
+
+## Admin UI
+
+Access via **Admin → Marketing Pages**:
+
+### Pages List (`/admin/pages`)
+
+- View all marketing pages
+- Create new pages
+- Duplicate existing pages
+- Delete pages (homepage protected)
+
+### Page Builder (`/admin/pages/:pageId`)
+
+Drag-and-drop page builder with:
+
+- **Block Palette** (left sidebar): Available block types organized by category
+- **Canvas** (center): Your page layout with sortable blocks
+- **Block Editor** (right panel): Opens when clicking a block to edit content
+- **Page Settings** (dialog): Page info, theme, navigation, and SEO settings
+
+### Available Blocks
+
+| Block Type   | Description                       | Supports Features | Supports Actions |
+| ------------ | --------------------------------- | ----------------- | ---------------- |
+| Navigation   | Site navigation with logo & links | ❌                | ✅               |
+| Hero Section | Bold headline with CTA buttons    | ❌                | ✅               |
+| Features     | Showcase features in grid layout  | ✅                | ❌               |
+| CTA          | Call to action with buttons       | ❌                | ✅               |
+| About        | Rich content with optional images | ✅                | ✅               |
+| Testimonials | Customer reviews                  | ✅                | ❌               |
+| Gallery      | Image showcase                    | ✅                | ❌               |
+| Team         | Team member profiles              | ✅                | ❌               |
+| Pricing      | Pricing tables                    | ✅                | ✅               |
+| FAQ          | Frequently asked questions        | ✅                | ❌               |
+| Video        | Embedded video with text          | ❌                | ✅               |
+| Code Block   | Code snippet with highlighting    | ❌                | ❌               |
+| Custom       | Flexible custom content           | ✅                | ✅               |
+| Footer       | Page footer with links            | ❌                | ✅               |
+
+### Block Variants
+
+Each block type supports multiple layout variants (e.g., hero: centered, split, fullscreen).
+
+## Usage
+
+### Creating a Page Programmatically
+
+```typescript
+import { Page } from '@/ottabase/models/Page';
+
+const newPage = await Page.create({
+    slug: 'pricing',
+    title: 'Pricing',
+    type: 'block',
+    status: 'draft',
+    themePreset: 'neo',
+});
+```
+
+### Using Admin Hooks
+
+```typescript
+import { pageHooks, pageSectionHooks } from '@/hooks/pageHooks';
+
+// List pages
+const { data: pages } = pageHooks.useList({});
+
+// Get single page
+const { data: page } = pageHooks.useDetail(pageId);
+
+// Create page
+const createPage = useCreatePage();
+await createPage.mutateAsync({ slug: 'about', title: 'About Us', type: 'block' });
+```
+
+### Fetching Page Data (Next.js)
+
+```typescript
+import { fetchPageByPageSlug, fetchNavPages } from '@/lib/api';
+
+// Get page by slug
+const pageData = await fetchPageByPageSlug('pricing');
+
+// Get nav pages
+const navPages = await fetchNavPages();
+```
+
+## Contract Types
+
+Import from `@ottabase/homepage-contract`:
+
+```typescript
+import {
+    // Zod schemas
+    PageDataSchema,
+    PageSectionSchema,
+    NavPageSchema,
+
+    // TypeScript types
+    type PageDataPayload,
+    type PageSectionPayload,
+    type NavPagePayload,
+} from '@ottabase/homepage-contract';
+```
+
+## Migration from Legacy Homepage
+
+The new pages system is additive. Legacy homepage routes continue to work:
+
+1. Keep using `/api/homepage/data` for existing integrations
+2. Migrate to `/api/pages/homepage` when ready
+3. Use `/admin/pages` for the new flexible builder
+
+The homepage is simply a page with `slug: 'homepage'`.
diff --git a/apps/ottabase-template-app-tanstack/ottabase/models/Page.schema.ts b/apps/ottabase-template-app-tanstack/ottabase/models/Page.schema.ts
new file mode 100644
index 000000000..6c2aad2a3
--- /dev/null
+++ b/apps/ottabase-template-app-tanstack/ottabase/models/Page.schema.ts
@@ -0,0 +1,92 @@
+/**
+ * Page Schema
+ *
+ * A page is a configurable landing page that can be:
+ * - Block-based: Composed of sections (hero, features, CTA, etc.)
+ * - Content-based: Rich text content (links to ottablog Post for content)
+ *
+ * Example pages: homepage, about, pricing, features, contact
+ */
+import { index, integer, sqliteTable, text } from 'drizzle-orm/sqlite-core';
+
+// Page type determines how it's rendered
+export type PageType = 'block' | 'content';
+
+// Page status (similar to Post status)
+export type PageStatus = 'draft' | 'published' | 'archived';
+
+export const pagesTable = sqliteTable(
+    'pages',
+    {
+        id: text('id')
+            .primaryKey()
+            .$defaultFn(() => crypto.randomUUID()),
+
+        // URL slug (e.g., 'homepage', 'about', 'pricing')
+        // 'homepage' is the default landing page
+        slug: text('slug').notNull().unique(),
+
+        // Display title
+        title: text('title').notNull(),
+
+        // Page type: 'block' (section-based) or 'content' (rich text via ottablog)
+        type: text('type').$type<PageType>().notNull().default('block'),
+
+        // Publication status
+        status: text('status').$type<PageStatus>().notNull().default('draft'),
+
+        // For content-type pages, link to ottablog Post
+        // This allows using the full ottablog editor for content pages
+        postId: text('post_id'),
+
+        // Theme preset for this page (overrides default)
+        themePreset: text('theme_preset'),
+
+        // SEO metadata
+        seoTitle: text('seo_title'),
+        seoDescription: text('seo_description'),
+        seoKeywords: text('seo_keywords'),
+
+        // Custom CSS for this page
+        customCss: text('custom_css'),
+
+        // Variant overrides for sections (JSON: { "hero": "centered", "features": "grid" })
+        variantBySlotJson: text('variant_by_slot_json', { mode: 'json' }).$type<Record<string, string>>(),
+
+        // Whether to show in main navigation
+        showInNav: integer('show_in_nav', { mode: 'boolean' }).notNull().default(false),
+
+        // Nav order (lower = first)
+        navOrder: integer('nav_order').notNull().default(100),
+
+        // Nav label (defaults to title if not set)
+        navLabel: text('nav_label'),
+
+        // Optional icon for nav
+        icon: text('icon'),
+
+        // Metadata (JSON blob for extensibility)
+        metadata: text('metadata', { mode: 'json' }).$type<Record<string, unknown>>(),
+
+        // Multi-tenant support
+        appId: text('app_id'),
+
+        // Timestamps
+        createdAt: integer('created_at')
+            .$defaultFn(() => Date.now())
+            .notNull(),
+        updatedAt: integer('updated_at')
+            .$defaultFn(() => Date.now())
+            .$onUpdateFn(() => Date.now())
+            .notNull(),
+    },
+    (table) => [
+        index('pages_slug_idx').on(table.slug),
+        index('pages_status_idx').on(table.status),
+        index('pages_nav_idx').on(table.showInNav, table.navOrder),
+        index('pages_app_idx').on(table.appId),
+    ],
+);
+
+export type PageRow = typeof pagesTable.$inferSelect;
+export type NewPageRow = typeof pagesTable.$inferInsert;
diff --git a/apps/ottabase-template-app-tanstack/ottabase/models/Page.ts b/apps/ottabase-template-app-tanstack/ottabase/models/Page.ts
new file mode 100644
index 000000000..99766348b
--- /dev/null
+++ b/apps/ottabase-template-app-tanstack/ottabase/models/Page.ts
@@ -0,0 +1,61 @@
+/**
+ * Page Model
+ *
+ * OttaORM model for managing pages (landing pages, about, pricing, etc.)
+ */
+import { BaseModel } from '@ottabase/ottaorm';
+import { pagesTable } from './Page.schema';
+
+export { pagesTable, type NewPageRow, type PageRow, type PageStatus, type PageType } from './Page.schema';
+
+export class Page extends BaseModel {
+    static entity = 'pages';
+    static table = pagesTable;
+    static primaryKey = 'id';
+
+    static casts = {
+        showInNav: 'boolean' as const,
+        variantBySlotJson: 'json' as const,
+        metadata: 'json' as const,
+    };
+
+    /**
+     * Get the homepage (slug = 'homepage')
+     */
+    static async getHomepage(): Promise<Page | null> {
+        const results = await this.where({ slug: 'homepage', status: 'published' });
+        return results.length > 0 ? (results[0] as Page) : null;
+    }
+
+    /**
+     * Get all published pages for navigation
+     */
+    static async getNavPages(): Promise<Page[]> {
+        return (await this.where(
+            { showInNav: true, status: 'published' },
+            { orderBy: 'navOrder', orderDirection: 'asc' },
+        )) as Page[];
+    }
+
+    /**
+     * Get published page by slug
+     */
+    static async getBySlug(slug: string): Promise<Page | null> {
+        const results = await this.where({ slug, status: 'published' });
+        return results.length > 0 ? (results[0] as Page) : null;
+    }
+
+    /**
+     * Check if this is the homepage
+     */
+    get isHomepage(): boolean {
+        return this.get('slug') === 'homepage';
+    }
+
+    /**
+     * Get nav label (falls back to title)
+     */
+    get displayNavLabel(): string {
+        return this.get('navLabel') || this.get('title') || '';
+    }
+}
diff --git a/apps/ottabase-template-app-tanstack/ottabase/models/PageAction.schema.ts b/apps/ottabase-template-app-tanstack/ottabase/models/PageAction.schema.ts
new file mode 100644
index 000000000..5a548de62
--- /dev/null
+++ b/apps/ottabase-template-app-tanstack/ottabase/models/PageAction.schema.ts
@@ -0,0 +1,47 @@
+/**
+ * PageAction Schema
+ *
+ * Actions are CTA buttons within a section (e.g., "Get Started", "Learn More").
+ */
+import { integer, sqliteTable, text } from 'drizzle-orm/sqlite-core';
+import { pageSectionsTable } from './PageSection.schema';
+
+// Button variants
+export type ActionVariant = 'default' | 'primary' | 'secondary' | 'outline' | 'ghost' | 'destructive' | 'link';
+
+export const pageActionsTable = sqliteTable('page_actions', {
+    id: text('id')
+        .primaryKey()
+        .$defaultFn(() => crypto.randomUUID()),
+
+    // Reference to parent section
+    sectionId: text('section_id')
+        .notNull()
+        .references(() => pageSectionsTable.id, { onDelete: 'cascade' }),
+
+    // Button content
+    label: text('label').notNull(),
+    href: text('href').notNull(),
+
+    // Styling
+    variant: text('variant').$type<ActionVariant>().default('default'),
+    icon: text('icon'), // Lucide icon name
+
+    // Behavior
+    external: integer('external', { mode: 'boolean' }).default(false),
+
+    // Sort order
+    sortOrder: integer('sort_order').notNull().default(0),
+
+    // Timestamps
+    createdAt: integer('created_at')
+        .$defaultFn(() => Date.now())
+        .notNull(),
+    updatedAt: integer('updated_at')
+        .$defaultFn(() => Date.now())
+        .$onUpdateFn(() => Date.now())
+        .notNull(),
+});
+
+export type PageActionRow = typeof pageActionsTable.$inferSelect;
+export type NewPageActionRow = typeof pageActionsTable.$inferInsert;
diff --git a/apps/ottabase-template-app-tanstack/ottabase/models/PageAction.ts b/apps/ottabase-template-app-tanstack/ottabase/models/PageAction.ts
new file mode 100644
index 000000000..d955b844a
--- /dev/null
+++ b/apps/ottabase-template-app-tanstack/ottabase/models/PageAction.ts
@@ -0,0 +1,24 @@
+/**
+ * PageAction Model
+ */
+import { BaseModel } from '@ottabase/ottaorm';
+import { pageActionsTable } from './PageAction.schema';
+
+export { pageActionsTable, type ActionVariant, type NewPageActionRow, type PageActionRow } from './PageAction.schema';
+
+export class PageAction extends BaseModel {
+    static entity = 'page_actions';
+    static table = pageActionsTable;
+    static primaryKey = 'id';
+
+    static casts = {
+        external: 'boolean' as const,
+    };
+
+    /**
+     * Get all actions for a section
+     */
+    static async getForSection(sectionId: string): Promise<PageAction[]> {
+        return (await this.where({ sectionId }, { orderBy: 'sortOrder', orderDirection: 'asc' })) as PageAction[];
+    }
+}
diff --git a/apps/ottabase-template-app-tanstack/ottabase/models/PageFeature.schema.ts b/apps/ottabase-template-app-tanstack/ottabase/models/PageFeature.schema.ts
new file mode 100644
index 000000000..f3bf58933
--- /dev/null
+++ b/apps/ottabase-template-app-tanstack/ottabase/models/PageFeature.schema.ts
@@ -0,0 +1,45 @@
+/**
+ * PageFeature Schema
+ *
+ * Features are child items within a section (e.g., feature cards, benefits list).
+ */
+import { integer, sqliteTable, text } from 'drizzle-orm/sqlite-core';
+import { pageSectionsTable } from './PageSection.schema';
+
+export const pageFeaturesTable = sqliteTable('page_features', {
+    id: text('id')
+        .primaryKey()
+        .$defaultFn(() => crypto.randomUUID()),
+
+    // Reference to parent section
+    sectionId: text('section_id')
+        .notNull()
+        .references(() => pageSectionsTable.id, { onDelete: 'cascade' }),
+
+    // Content
+    title: text('title').notNull(),
+    description: text('description'),
+
+    // Visual
+    icon: text('icon'), // Lucide icon name
+    imageUrl: text('image_url'),
+
+    // Optional link
+    href: text('href'),
+    external: integer('external', { mode: 'boolean' }).default(false),
+
+    // Sort order
+    sortOrder: integer('sort_order').notNull().default(0),
+
+    // Timestamps
+    createdAt: integer('created_at')
+        .$defaultFn(() => Date.now())
+        .notNull(),
+    updatedAt: integer('updated_at')
+        .$defaultFn(() => Date.now())
+        .$onUpdateFn(() => Date.now())
+        .notNull(),
+});
+
+export type PageFeatureRow = typeof pageFeaturesTable.$inferSelect;
+export type NewPageFeatureRow = typeof pageFeaturesTable.$inferInsert;
diff --git a/apps/ottabase-template-app-tanstack/ottabase/models/PageFeature.ts b/apps/ottabase-template-app-tanstack/ottabase/models/PageFeature.ts
new file mode 100644
index 000000000..45ff1849a
--- /dev/null
+++ b/apps/ottabase-template-app-tanstack/ottabase/models/PageFeature.ts
@@ -0,0 +1,24 @@
+/**
+ * PageFeature Model
+ */
+import { BaseModel } from '@ottabase/ottaorm';
+import { pageFeaturesTable } from './PageFeature.schema';
+
+export { pageFeaturesTable, type NewPageFeatureRow, type PageFeatureRow } from './PageFeature.schema';
+
+export class PageFeature extends BaseModel {
+    static entity = 'page_features';
+    static table = pageFeaturesTable;
+    static primaryKey = 'id';
+
+    static casts = {
+        external: 'boolean' as const,
+    };
+
+    /**
+     * Get all features for a section
+     */
+    static async getForSection(sectionId: string): Promise<PageFeature[]> {
+        return (await this.where({ sectionId }, { orderBy: 'sortOrder', orderDirection: 'asc' })) as PageFeature[];
+    }
+}
diff --git a/apps/ottabase-template-app-tanstack/ottabase/models/PageSection.schema.ts b/apps/ottabase-template-app-tanstack/ottabase/models/PageSection.schema.ts
new file mode 100644
index 000000000..1dca3789a
--- /dev/null
+++ b/apps/ottabase-template-app-tanstack/ottabase/models/PageSection.schema.ts
@@ -0,0 +1,88 @@
+/**
+ * PageSection Schema
+ *
+ * Sections are the building blocks of block-type pages.
+ * Examples: hero, features, cta, footer, navbar, testimonials, pricing, etc.
+ *
+ * Each section has a slot type (determines rendering) and belongs to a page.
+ */
+import { index, integer, sqliteTable, text } from 'drizzle-orm/sqlite-core';
+import { pagesTable } from './Page.schema';
+
+// Built-in slot types (extensible via metadata)
+export type SlotType =
+    | 'navbar'
+    | 'hero'
+    | 'features'
+    | 'cta'
+    | 'footer'
+    | 'about'
+    | 'pricing'
+    | 'testimonials'
+    | 'faq'
+    | 'contact'
+    | 'custom';
+
+export const pageSectionsTable = sqliteTable(
+    'page_sections',
+    {
+        id: text('id')
+            .primaryKey()
+            .$defaultFn(() => crypto.randomUUID()),
+
+        // Reference to parent page
+        pageId: text('page_id')
+            .notNull()
+            .references(() => pagesTable.id, { onDelete: 'cascade' }),
+
+        // Slot type determines the component used to render
+        slot: text('slot').$type<SlotType>().notNull(),
+
+        // Content fields
+        title: text('title'),
+        subtitle: text('subtitle'),
+        body: text('body'), // Markdown content
+
+        // Visual customization
+        icon: text('icon'), // Lucide icon name
+        imageUrl: text('image_url'), // Background or hero image
+        videoUrl: text('video_url'), // Background video
+
+        // Navigation-specific (for navbar/footer)
+        githubUrl: text('github_url'),
+        logoUrl: text('logo_url'),
+
+        // Variant for this section (e.g., "centered", "split", "grid")
+        variant: text('variant'),
+
+        // Layout/styling
+        cssClasses: text('css_classes'),
+        backgroundColor: text('background_color'),
+
+        // Enabled/disabled toggle
+        enabled: integer('enabled', { mode: 'boolean' }).notNull().default(true),
+
+        // Sort order within page
+        sortOrder: integer('sort_order').notNull().default(0),
+
+        // Extensible metadata
+        metadata: text('metadata', { mode: 'json' }).$type<Record<string, unknown>>(),
+
+        // Timestamps
+        createdAt: integer('created_at')
+            .$defaultFn(() => Date.now())
+            .notNull(),
+        updatedAt: integer('updated_at')
+            .$defaultFn(() => Date.now())
+            .$onUpdateFn(() => Date.now())
+            .notNull(),
+    },
+    (table) => [
+        index('page_sections_page_idx').on(table.pageId),
+        index('page_sections_slot_idx').on(table.slot),
+        index('page_sections_order_idx').on(table.pageId, table.sortOrder),
+    ],
+);
+
+export type PageSectionRow = typeof pageSectionsTable.$inferSelect;
+export type NewPageSectionRow = typeof pageSectionsTable.$inferInsert;
diff --git a/apps/ottabase-template-app-tanstack/ottabase/models/PageSection.ts b/apps/ottabase-template-app-tanstack/ottabase/models/PageSection.ts
new file mode 100644
index 000000000..aae2ce25f
--- /dev/null
+++ b/apps/ottabase-template-app-tanstack/ottabase/models/PageSection.ts
@@ -0,0 +1,35 @@
+/**
+ * PageSection Model
+ */
+import { BaseModel } from '@ottabase/ottaorm';
+import { pageSectionsTable } from './PageSection.schema';
+
+export { pageSectionsTable, type NewPageSectionRow, type PageSectionRow, type SlotType } from './PageSection.schema';
+
+export class PageSection extends BaseModel {
+    static entity = 'page_sections';
+    static table = pageSectionsTable;
+    static primaryKey = 'id';
+
+    static casts = {
+        enabled: 'boolean' as const,
+        metadata: 'json' as const,
+    };
+
+    /**
+     * Get all sections for a page
+     */
+    static async getForPage(pageId: string): Promise<PageSection[]> {
+        return (await this.where({ pageId }, { orderBy: 'sortOrder', orderDirection: 'asc' })) as PageSection[];
+    }
+
+    /**
+     * Get enabled sections for a page
+     */
+    static async getEnabledForPage(pageId: string): Promise<PageSection[]> {
+        return (await this.where(
+            { pageId, enabled: true },
+            { orderBy: 'sortOrder', orderDirection: 'asc' },
+        )) as PageSection[];
+    }
+}
diff --git a/apps/ottabase-template-app-tanstack/ottabase/models/pagePolicy.ts b/apps/ottabase-template-app-tanstack/ottabase/models/pagePolicy.ts
new file mode 100644
index 000000000..828ad66ec
--- /dev/null
+++ b/apps/ottabase-template-app-tanstack/ottabase/models/pagePolicy.ts
@@ -0,0 +1,48 @@
+/**
+ * Page-related RLS Policies
+ *
+ * AdminOnly for all page entities.
+ * Public read access is handled at the API route level.
+ */
+import type { ModelRLSConfig } from '@ottabase/ottaorm';
+import { RLSPolicies } from '@ottabase/ottaorm';
+
+/**
+ * Pages RLS policy - AdminOnly
+ */
+export const pagePolicy: ModelRLSConfig = {
+    model: 'pages',
+    policy: RLSPolicies.AdminOnly(),
+    contextFields: [],
+    auditEnabled: true,
+};
+
+/**
+ * PageSections RLS policy - AdminOnly
+ */
+export const pageSectionPolicy: ModelRLSConfig = {
+    model: 'page_sections',
+    policy: RLSPolicies.AdminOnly(),
+    contextFields: [],
+    auditEnabled: true,
+};
+
+/**
+ * PageFeatures RLS policy - AdminOnly
+ */
+export const pageFeaturePolicy: ModelRLSConfig = {
+    model: 'page_features',
+    policy: RLSPolicies.AdminOnly(),
+    contextFields: [],
+    auditEnabled: true,
+};
+
+/**
+ * PageActions RLS policy - AdminOnly
+ */
+export const pageActionPolicy: ModelRLSConfig = {
+    model: 'page_actions',
+    policy: RLSPolicies.AdminOnly(),
+    contextFields: [],
+    auditEnabled: true,
+};
diff --git a/apps/ottabase-template-app-tanstack/package.json b/apps/ottabase-template-app-tanstack/package.json
index 0bb797a28..f1f369489 100644
--- a/apps/ottabase-template-app-tanstack/package.json
+++ b/apps/ottabase-template-app-tanstack/package.json
@@ -21,6 +21,9 @@
     },
     "dependencies": {
         "@auth/core": "catalog:",
+        "@dnd-kit/core": "^6.3.1",
+        "@dnd-kit/sortable": "^10.0.0",
+        "@dnd-kit/utilities": "^3.2.2",
         "@hookform/resolvers": "catalog:",
         "@mantine/carousel": "catalog:",
         "@mantine/core": "catalog:",
diff --git a/apps/ottabase-template-app-tanstack/src/hooks/pageHooks.ts b/apps/ottabase-template-app-tanstack/src/hooks/pageHooks.ts
new file mode 100644
index 000000000..2c16a8b69
--- /dev/null
+++ b/apps/ottabase-template-app-tanstack/src/hooks/pageHooks.ts
@@ -0,0 +1,135 @@
+/**
+ * Pages Admin Hooks
+ *
+ * Pre-configured model hooks for the flexible page system entities.
+ * Used by the admin UI to manage pages, sections, features, and actions.
+ *
+ * This replaces the legacy homepageHooks.ts for new integrations.
+ */
+import { createModelHooks } from '@ottabase/ottaorm/client';
+
+// ── Row types ───────────────────────────────────────────────────────────────
+
+export interface PageRow {
+    id: string;
+    slug: string;
+    title: string;
+    type: 'block' | 'content';
+    status: 'draft' | 'published' | 'archived';
+    postId: string | null;
+    themePreset: string | null;
+    fallbackThemePresetId: string | null;
+    customCss: string | null;
+    seoTitle: string | null;
+    seoDescription: string | null;
+    seoImage: string | null;
+    variantBySlotJson: Record<string, string> | null;
+    showInNav: boolean;
+    navOrder: number;
+    navLabel: string | null;
+    icon: string | null;
+    metadata: Record<string, unknown> | null;
+    appId: string | null;
+    createdAt: string;
+    updatedAt: string;
+}
+
+export interface PageSectionRow {
+    id: string;
+    pageId: string;
+    slot: string;
+    title: string | null;
+    subtitle: string | null;
+    body: string | null;
+    variant: string | null;
+    githubUrl: string | null;
+    icon: string | null;
+    imageUrl: string | null;
+    videoUrl: string | null;
+    logoUrl: string | null;
+    cssClasses: string | null;
+    backgroundColor: string | null;
+    enabled: boolean;
+    metadata: Record<string, unknown> | null;
+    sortOrder: number;
+    appId: string | null;
+    createdAt: string;
+    updatedAt: string;
+}
+
+export interface PageFeatureRow {
+    id: string;
+    sectionId: string;
+    title: string;
+    description: string;
+    icon: string | null;
+    imageUrl: string | null;
+    href: string | null;
+    sortOrder: number;
+    appId: string | null;
+    createdAt: string;
+    updatedAt: string;
+}
+
+export interface PageActionRow {
+    id: string;
+    sectionId: string;
+    label: string;
+    href: string;
+    variant: string | null;
+    icon: string | null;
+    external: boolean;
+    sortOrder: number;
+    appId: string | null;
+    createdAt: string;
+    updatedAt: string;
+}
+
+// ── Hooks ───────────────────────────────────────────────────────────────────
+
+export const pageHooks = createModelHooks<PageRow>({
+    entityName: 'pages',
+});
+
+export const pageSectionHooks = createModelHooks<PageSectionRow>({
+    entityName: 'page_sections',
+});
+
+export const pageFeatureHooks = createModelHooks<PageFeatureRow>({
+    entityName: 'page_features',
+});
+
+export const pageActionHooks = createModelHooks<PageActionRow>({
+    entityName: 'page_actions',
+});
+
+// ── Convenience exports ─────────────────────────────────────────────────────
+
+export const {
+    useList: usePages,
+    useDetail: usePage,
+    useCreate: useCreatePage,
+    useUpdate: useUpdatePage,
+    useDelete: useDeletePage,
+} = pageHooks;
+
+export const {
+    useList: usePageSections,
+    useCreate: useCreatePageSection,
+    useUpdate: useUpdatePageSection,
+    useDelete: useDeletePageSection,
+} = pageSectionHooks;
+
+export const {
+    useList: usePageFeatures,
+    useCreate: useCreatePageFeature,
+    useUpdate: useUpdatePageFeature,
+    useDelete: useDeletePageFeature,
+} = pageFeatureHooks;
+
+export const {
+    useList: usePageActions,
+    useCreate: useCreatePageAction,
+    useUpdate: useUpdatePageAction,
+    useDelete: useDeletePageAction,
+} = pageActionHooks;
diff --git a/apps/ottabase-template-app-tanstack/src/pages/admin/AdminIndexPage.tsx b/apps/ottabase-template-app-tanstack/src/pages/admin/AdminIndexPage.tsx
index 578f85f55..1c388c289 100644
--- a/apps/ottabase-template-app-tanstack/src/pages/admin/AdminIndexPage.tsx
+++ b/apps/ottabase-template-app-tanstack/src/pages/admin/AdminIndexPage.tsx
@@ -13,6 +13,7 @@ import {
     Home,
     Layers,
     Layout,
+    LayoutDashboard,
     Mail,
     Palette,
     Power,
@@ -94,6 +95,12 @@ const ADMIN_CATEGORIES: AdminCategory[] = [
                 href: '/admin/homepage',
                 icon: Home,
             },
+            {
+                title: 'Marketing Pages',
+                description: 'Drag & drop page builder for landing pages, about pages, and more.',
+                href: '/admin/pages',
+                icon: LayoutDashboard,
+            },
             ...(MEDIA_LIBRARY_ENABLED
                 ? [
                       {
diff --git a/apps/ottabase-template-app-tanstack/src/pages/admin/homepage/AdminHomepageBuilderPage.tsx b/apps/ottabase-template-app-tanstack/src/pages/admin/homepage/AdminHomepageBuilderPage.tsx
index 79ed649d7..e0cf868ac 100644
--- a/apps/ottabase-template-app-tanstack/src/pages/admin/homepage/AdminHomepageBuilderPage.tsx
+++ b/apps/ottabase-template-app-tanstack/src/pages/admin/homepage/AdminHomepageBuilderPage.tsx
@@ -1,14 +1,8 @@
 /**
- * Admin Homepage Builder
+ * Admin Homepage Builder - Tab-based UX
  *
- * Unified single-page builder for managing the entire homepage.
- * All slots, content, features, actions, and display settings in one place.
- *
- * Design principles:
- * - One page, one mental model: "I'm editing my homepage"
- * - Visual slot cards in layout order
- * - Click to expand → edit everything inline
- * - Settings collapsed at top (theme, SEO, CSS)
+ * Design: Full-width tabs for each section type.
+ * Each tab has dedicated editing space - no cramped modals.
  */
 import { ADMIN_LIST_QUERY_CONFIG } from '@/config/queryConfig';
 import {
@@ -22,10 +16,6 @@ import {
     type HomepageSectionRow,
 } from '@/hooks/homepageHooks';
 import {
-    Accordion,
-    AccordionContent,
-    AccordionItem,
-    AccordionTrigger,
     Badge,
     Button,
     Card,
@@ -33,9 +23,6 @@ import {
     CardDescription,
     CardHeader,
     CardTitle,
-    Collapsible,
-    CollapsibleContent,
-    CollapsibleTrigger,
     Input,
     Label,
     Select,
@@ -45,20 +32,19 @@ import {
     SelectValue,
     Separator,
     Switch,
+    Tabs,
+    TabsContent,
+    TabsList,
+    TabsTrigger,
     Textarea,
-    Tooltip,
-    TooltipContent,
-    TooltipProvider,
-    TooltipTrigger,
 } from '@ottabase/ui-shadcn';
 import { IconDatabaseImport } from '@tabler/icons-react';
 import {
-    ChevronDown,
+    Check,
     ExternalLink,
     FileText,
     Grid3X3,
     Home,
-    Layout,
     Megaphone,
     Navigation,
     Palette,
@@ -70,528 +56,529 @@ import {
     Trash2,
 } from 'lucide-react';
 import { useCallback, useEffect, useMemo, useState } from 'react';
-import {
-    ACTION_VARIANTS,
-    SLOT_CONFIG,
-    SLOT_DESCRIPTIONS,
-    SLOT_LABELS,
-    SLOT_NAMES,
-    THEME_PRESETS,
-    type SlotName,
-} from './homepage-constants';
-
-// ── Icon map for slots ──────────────────────────────────────────────────────
-
-const SLOT_ICON_MAP: Record<SlotName, React.FC<{ className?: string }>> = {
-    navbar: Navigation,
-    hero: Sparkles,
-    features: Grid3X3,
-    cta: Megaphone,
-    footer: Rows3,
-    about: FileText,
-};
-
-// ── Inline Feature Editor ───────────────────────────────────────────────────
-
-function FeatureEditor({
-    sectionId,
-    features,
-    onRefresh,
+import { ACTION_VARIANTS, THEME_PRESETS } from './homepage-constants';
+
+// ── Section type config ─────────────────────────────────────────────────────
+
+const SECTION_TYPES = [
+    { id: 'navbar', label: 'Navbar', icon: Navigation, description: 'Top navigation bar' },
+    { id: 'hero', label: 'Hero', icon: Sparkles, description: 'Main headline section' },
+    { id: 'features', label: 'Features', icon: Grid3X3, description: 'Feature grid' },
+    { id: 'cta', label: 'CTA', icon: Megaphone, description: 'Call to action' },
+    { id: 'about', label: 'About', icon: FileText, description: 'About section' },
+    { id: 'footer', label: 'Footer', icon: Rows3, description: 'Page footer' },
+] as const;
+
+type SectionType = (typeof SECTION_TYPES)[number]['id'];
+
+// ── Settings Tab ────────────────────────────────────────────────────────────
+
+function SettingsTab({
+    display,
+    onSave,
+    onSeed,
+    seeding,
 }: {
-    sectionId: string;
-    features: HomepageFeatureRow[];
-    onRefresh: () => void;
+    display: HomepageDisplaySettingsRow | null;
+    onSave: (data: { themePreset: string; seoTitle?: string; seoDescription?: string; customCss?: string }) => void;
+    onSeed: () => void;
+    seeding: boolean;
 }) {
-    const createFeature = homepageFeatureHooks.useCreate();
-    const updateFeature = homepageFeatureHooks.useUpdate();
-    const deleteFeature = homepageFeatureHooks.useDelete();
-    const [adding, setAdding] = useState(false);
-    const [newTitle, setNewTitle] = useState('');
-    const [newDesc, setNewDesc] = useState('');
-    const [newIcon, setNewIcon] = useState('');
+    const [themePreset, setThemePreset] = useState(display?.themePreset ?? 'default');
+    const [seoTitle, setSeoTitle] = useState(display?.seoTitle ?? '');
+    const [seoDescription, setSeoDescription] = useState(display?.seoDescription ?? '');
+    const [customCss, setCustomCss] = useState(display?.customCss ?? '');
+    const [saved, setSaved] = useState(false);
 
-    const handleAdd = async () => {
-        if (!newTitle.trim() || !newDesc.trim()) return;
-        await createFeature.mutateAsync({
-            sectionId,
-            title: newTitle.trim(),
-            description: newDesc.trim(),
-            icon: newIcon.trim() || undefined,
-            sortOrder: features.length,
-        });
-        setNewTitle('');
-        setNewDesc('');
-        setNewIcon('');
-        setAdding(false);
-        onRefresh();
-    };
+    useEffect(() => {
+        if (display) {
+            setThemePreset(display.themePreset ?? 'default');
+            setSeoTitle(display.seoTitle ?? '');
+            setSeoDescription(display.seoDescription ?? '');
+            setCustomCss(display.customCss ?? '');
+        }
+    }, [display]);
 
-    const handleDelete = async (id: string) => {
-        await deleteFeature.mutateAsync(id);
-        onRefresh();
+    const handleSave = () => {
+        onSave({
+            themePreset,
+            seoTitle: seoTitle || undefined,
+            seoDescription: seoDescription || undefined,
+            customCss: customCss || undefined,
+        });
+        setSaved(true);
+        setTimeout(() => setSaved(false), 2000);
     };
 
     return (
-        <div className="space-y-3">
-            <div className="flex items-center justify-between">
-                <Label className="text-xs font-medium uppercase tracking-wider text-muted-foreground">
-                    Features ({features.length})
-                </Label>
-                <Button variant="ghost" size="sm" className="h-7 text-xs" onClick={() => setAdding(!adding)}>
-                    <Plus className="mr-1 h-3 w-3" />
-                    Add Feature
-                </Button>
-            </div>
-
-            {features.map((f) => (
-                <div key={f.id} className="flex items-start gap-3 rounded-md border bg-muted/30 p-3">
-                    {f.icon && (
-                        <Badge variant="secondary" className="shrink-0 font-mono text-[10px]">
-                            {f.icon}
-                        </Badge>
-                    )}
-                    <div className="min-w-0 flex-1">
-                        <p className="font-medium text-sm">{f.title}</p>
-                        <p className="text-xs text-muted-foreground">{f.description}</p>
+        <div className="space-y-8">
+            {/* Theme Selection */}
+            <Card>
+                <CardHeader>
+                    <CardTitle className="flex items-center gap-2">
+                        <Palette className="h-5 w-5" />
+                        Theme
+                    </CardTitle>
+                    <CardDescription>Choose a visual theme for your homepage</CardDescription>
+                </CardHeader>
+                <CardContent>
+                    <div className="grid grid-cols-2 md:grid-cols-4 gap-3">
+                        {THEME_PRESETS.map((preset) => (
+                            <button
+                                key={preset.id}
+                                onClick={() => setThemePreset(preset.id)}
+                                className={`p-4 rounded-lg border text-left transition-all ${
+                                    themePreset === preset.id
+                                        ? 'border-primary bg-primary/5 ring-2 ring-primary shadow-sm'
+                                        : 'hover:bg-muted/50 hover:border-muted-foreground/30'
+                                }`}
+                            >
+                                <div className="font-medium">{preset.label}</div>
+                                <p className="text-xs text-muted-foreground mt-1">{preset.description}</p>
+                            </button>
+                        ))}
                     </div>
-                    <Button variant="ghost" size="icon" className="h-7 w-7 shrink-0" onClick={() => handleDelete(f.id)}>
-                        <Trash2 className="h-3.5 w-3.5 text-destructive" />
-                    </Button>
-                </div>
-            ))}
-
-            {adding && (
-                <div className="space-y-2 rounded-md border border-dashed p-3">
-                    <div className="flex gap-2">
+                </CardContent>
+            </Card>
+
+            {/* SEO */}
+            <Card>
+                <CardHeader>
+                    <CardTitle>SEO</CardTitle>
+                    <CardDescription>Search engine optimization settings</CardDescription>
+                </CardHeader>
+                <CardContent className="space-y-4">
+                    <div className="space-y-2">
+                        <Label>Page Title</Label>
                         <Input
-                            placeholder="Feature title"
-                            value={newTitle}
-                            onChange={(e) => setNewTitle(e.target.value)}
-                            className="h-8 text-sm"
+                            value={seoTitle}
+                            onChange={(e) => setSeoTitle(e.target.value)}
+                            placeholder="My Amazing Product - Build Better Software"
                         />
-                        <Input
-                            placeholder="Icon (e.g. Zap)"
-                            value={newIcon}
-                            onChange={(e) => setNewIcon(e.target.value)}
-                            className="h-8 w-28 text-sm"
+                    </div>
+                    <div className="space-y-2">
+                        <Label>Meta Description</Label>
+                        <Textarea
+                            value={seoDescription}
+                            onChange={(e) => setSeoDescription(e.target.value)}
+                            placeholder="A compelling description for search engines..."
+                            rows={3}
                         />
                     </div>
+                </CardContent>
+            </Card>
+
+            {/* Custom CSS */}
+            <Card>
+                <CardHeader>
+                    <CardTitle>Custom CSS</CardTitle>
+                    <CardDescription>Add custom styles (advanced)</CardDescription>
+                </CardHeader>
+                <CardContent>
                     <Textarea
-                        placeholder="Short description"
-                        value={newDesc}
-                        onChange={(e) => setNewDesc(e.target.value)}
-                        rows={2}
-                        className="text-sm"
+                        value={customCss}
+                        onChange={(e) => setCustomCss(e.target.value)}
+                        placeholder=".hero { background: linear-gradient(...); }"
+                        rows={5}
+                        className="font-mono text-sm"
                     />
-                    <div className="flex gap-2">
-                        <Button
-                            size="sm"
-                            className="h-7 text-xs"
-                            onClick={handleAdd}
-                            disabled={createFeature.isPending}
-                        >
-                            Save
-                        </Button>
-                        <Button
-                            variant="ghost"
-                            size="sm"
-                            className="h-7 text-xs"
-                            onClick={() => {
-                                setAdding(false);
-                                setNewTitle('');
-                                setNewDesc('');
-                                setNewIcon('');
-                            }}
-                        >
-                            Cancel
-                        </Button>
-                    </div>
-                </div>
-            )}
+                </CardContent>
+            </Card>
+
+            {/* Actions */}
+            <div className="flex items-center justify-between pt-4">
+                <Button variant="outline" onClick={onSeed} disabled={seeding}>
+                    <IconDatabaseImport className="mr-2 h-4 w-4" />
+                    {seeding ? 'Seeding...' : 'Seed Demo Data'}
+                </Button>
+                <Button onClick={handleSave}>
+                    {saved ? <Check className="mr-2 h-4 w-4" /> : <Save className="mr-2 h-4 w-4" />}
+                    {saved ? 'Saved!' : 'Save Settings'}
+                </Button>
+            </div>
         </div>
     );
 }
 
-// ── Inline Action Editor ────────────────────────────────────────────────────
+// ── Section Tab (reusable for each section type) ────────────────────────────
 
-function ActionEditor({
-    sectionId,
+function SectionTab({
+    sectionType,
+    section,
+    features,
     actions,
+    onCreateSection,
+    onUpdateSection,
+    onToggleSection,
+    onDeleteSection,
     onRefresh,
 }: {
-    sectionId: string;
+    sectionType: (typeof SECTION_TYPES)[number];
+    section: HomepageSectionRow | null;
+    features: HomepageFeatureRow[];
     actions: HomepageActionRow[];
+    onCreateSection: () => void;
+    onUpdateSection: (data: Partial<HomepageSectionRow>) => void;
+    onToggleSection: () => void;
+    onDeleteSection: () => void;
     onRefresh: () => void;
 }) {
+    const createFeature = homepageFeatureHooks.useCreate();
+    const deleteFeature = homepageFeatureHooks.useDelete();
     const createAction = homepageActionHooks.useCreate();
     const deleteAction = homepageActionHooks.useDelete();
-    const [adding, setAdding] = useState(false);
-    const [newLabel, setNewLabel] = useState('');
-    const [newHref, setNewHref] = useState('');
-    const [newVariant, setNewVariant] = useState('default');
-    const [newIcon, setNewIcon] = useState('');
-
-    const handleAdd = async () => {
-        if (!newLabel.trim() || !newHref.trim()) return;
-        await createAction.mutateAsync({
-            sectionId,
-            label: newLabel.trim(),
-            href: newHref.trim(),
-            variant: newVariant,
-            icon: newIcon.trim() || undefined,
-            sortOrder: actions.length,
+
+    const [form, setForm] = useState({
+        title: section?.title || '',
+        subtitle: section?.subtitle || '',
+        body: section?.body || '',
+        icon: section?.icon || '',
+        githubUrl: section?.githubUrl || '',
+    });
+
+    const [newFeature, setNewFeature] = useState({ title: '', description: '', icon: '' });
+    const [newAction, setNewAction] = useState({ label: '', href: '', variant: 'default', icon: '' });
+    const [saved, setSaved] = useState(false);
+
+    // Sync form with section data
+    useEffect(() => {
+        if (section) {
+            setForm({
+                title: section.title || '',
+                subtitle: section.subtitle || '',
+                body: section.body || '',
+                icon: section.icon || '',
+                githubUrl: section.githubUrl || '',
+            });
+        }
+    }, [section]);
+
+    const showFeatures = sectionType.id === 'features' || sectionType.id === 'about';
+    const showActions = sectionType.id === 'hero' || sectionType.id === 'cta' || sectionType.id === 'about';
+    const showGithub = sectionType.id === 'navbar';
+
+    const handleSave = () => {
+        onUpdateSection(form);
+        setSaved(true);
+        setTimeout(() => setSaved(false), 2000);
+    };
+
+    const handleAddFeature = async () => {
+        if (!newFeature.title.trim() || !section) return;
+        await createFeature.mutateAsync({
+            sectionId: section.id,
+            title: newFeature.title.trim(),
+            description: newFeature.description.trim(),
+            icon: newFeature.icon.trim() || undefined,
+            sortOrder: features.length,
         });
-        setNewLabel('');
-        setNewHref('');
-        setNewVariant('default');
-        setNewIcon('');
-        setAdding(false);
+        setNewFeature({ title: '', description: '', icon: '' });
         onRefresh();
     };
 
-    const handleDelete = async (id: string) => {
-        await deleteAction.mutateAsync(id);
+    const handleAddAction = async () => {
+        if (!newAction.label.trim() || !newAction.href.trim() || !section) return;
+        await createAction.mutateAsync({
+            sectionId: section.id,
+            label: newAction.label.trim(),
+            href: newAction.href.trim(),
+            variant: newAction.variant,
+            icon: newAction.icon.trim() || undefined,
+            sortOrder: actions.length,
+        });
+        setNewAction({ label: '', href: '', variant: 'default', icon: '' });
         onRefresh();
     };
 
-    return (
-        <div className="space-y-3">
-            <div className="flex items-center justify-between">
-                <Label className="text-xs font-medium uppercase tracking-wider text-muted-foreground">
-                    Actions / Buttons ({actions.length})
-                </Label>
-                <Button variant="ghost" size="sm" className="h-7 text-xs" onClick={() => setAdding(!adding)}>
-                    <Plus className="mr-1 h-3 w-3" />
-                    Add Button
+    // Section not created yet
+    if (!section) {
+        return (
+            <div className="flex flex-col items-center justify-center py-16 text-center">
+                <div className="w-16 h-16 rounded-full bg-muted flex items-center justify-center mb-4">
+                    <sectionType.icon className="h-8 w-8 text-muted-foreground" />
+                </div>
+                <h3 className="text-lg font-medium mb-2">{sectionType.label} Section</h3>
+                <p className="text-muted-foreground mb-6 max-w-md">{sectionType.description}</p>
+                <Button onClick={onCreateSection}>
+                    <Plus className="mr-2 h-4 w-4" />
+                    Create {sectionType.label} Section
                 </Button>
             </div>
+        );
+    }
 
-            {actions.map((a) => (
-                <div key={a.id} className="flex items-center gap-3 rounded-md border bg-muted/30 p-3">
-                    <Badge variant="outline" className="shrink-0 text-xs">
-                        {a.variant || 'default'}
-                    </Badge>
-                    <div className="min-w-0 flex-1">
-                        <p className="font-medium text-sm">{a.label}</p>
-                        <p className="text-xs text-muted-foreground truncate">{a.href}</p>
-                    </div>
-                    {a.icon && (
-                        <Badge variant="secondary" className="shrink-0 font-mono text-[10px]">
-                            {a.icon}
-                        </Badge>
-                    )}
-                    <Button variant="ghost" size="icon" className="h-7 w-7 shrink-0" onClick={() => handleDelete(a.id)}>
-                        <Trash2 className="h-3.5 w-3.5 text-destructive" />
-                    </Button>
-                </div>
-            ))}
-
-            {adding && (
-                <div className="space-y-2 rounded-md border border-dashed p-3">
-                    <div className="flex gap-2">
-                        <Input
-                            placeholder="Button label"
-                            value={newLabel}
-                            onChange={(e) => setNewLabel(e.target.value)}
-                            className="h-8 text-sm"
+    return (
+        <div className="space-y-6">
+            {/* Header with toggle */}
+            <div className="flex items-center justify-between">
+                <div className="flex items-center gap-3">
+                    <div
+                        className={`w-10 h-10 rounded-lg flex items-center justify-center ${section.enabled ? 'bg-primary/10' : 'bg-muted'}`}
+                    >
+                        <sectionType.icon
+                            className={`h-5 w-5 ${section.enabled ? 'text-primary' : 'text-muted-foreground'}`}
                         />
-                        <Select value={newVariant} onValueChange={setNewVariant}>
-                            <SelectTrigger className="h-8 w-28 text-sm">
-                                <SelectValue />
-                            </SelectTrigger>
-                            <SelectContent>
-                                {ACTION_VARIANTS.map((v) => (
-                                    <SelectItem key={v.value} value={v.value}>
-                                        {v.label}
-                                    </SelectItem>
-                                ))}
-                            </SelectContent>
-                        </Select>
                     </div>
-                    <div className="flex gap-2">
-                        <Input
-                            placeholder="URL (e.g. /docs or https://...)"
-                            value={newHref}
-                            onChange={(e) => setNewHref(e.target.value)}
-                            className="h-8 text-sm flex-1"
-                        />
-                        <Input
-                            placeholder="Icon"
-                            value={newIcon}
-                            onChange={(e) => setNewIcon(e.target.value)}
-                            className="h-8 w-24 text-sm"
-                        />
+                    <div>
+                        <h3 className="font-medium">{sectionType.label} Section</h3>
+                        <p className="text-sm text-muted-foreground">
+                            {section.enabled ? 'Visible on homepage' : 'Hidden from homepage'}
+                        </p>
                     </div>
-                    <div className="flex gap-2">
-                        <Button size="sm" className="h-7 text-xs" onClick={handleAdd} disabled={createAction.isPending}>
-                            Save
-                        </Button>
-                        <Button
-                            variant="ghost"
-                            size="sm"
-                            className="h-7 text-xs"
-                            onClick={() => {
-                                setAdding(false);
-                                setNewLabel('');
-                                setNewHref('');
-                                setNewVariant('default');
-                                setNewIcon('');
-                            }}
-                        >
-                            Cancel
-                        </Button>
+                </div>
+                <div className="flex items-center gap-4">
+                    <div className="flex items-center gap-2">
+                        <Label htmlFor="enabled" className="text-sm">
+                            Enabled
+                        </Label>
+                        <Switch id="enabled" checked={section.enabled} onCheckedChange={onToggleSection} />
                     </div>
+                    <Button
+                        variant="ghost"
+                        size="sm"
+                        className="text-destructive hover:text-destructive"
+                        onClick={onDeleteSection}
+                    >
+                        <Trash2 className="h-4 w-4" />
+                    </Button>
                 </div>
-            )}
-        </div>
-    );
-}
+            </div>
 
-// ── Slot Card Component ─────────────────────────────────────────────────────
+            <Separator />
 
-function SlotCard({
-    slot,
-    section,
-    features,
-    actions,
-    variantBySlot,
-    onSectionChange,
-    onVariantChange,
-    onRefresh,
-}: {
-    slot: SlotName;
-    section: HomepageSectionRow | null;
-    features: HomepageFeatureRow[];
-    actions: HomepageActionRow[];
-    variantBySlot: Record<string, string>;
-    onSectionChange: (slot: SlotName, field: string, value: unknown) => void;
-    onVariantChange: (slot: SlotName, variantId: string) => void;
-    onRefresh: () => void;
-}) {
-    const createSection = homepageSectionHooks.useCreate();
-    const updateSection = homepageSectionHooks.useUpdate();
+            {/* Content Fields */}
+            <div className="grid gap-6 md:grid-cols-2">
+                <div className="space-y-2">
+                    <Label>Title</Label>
+                    <Input
+                        value={form.title}
+                        onChange={(e) => setForm({ ...form, title: e.target.value })}
+                        placeholder="Section title"
+                    />
+                </div>
+                <div className="space-y-2">
+                    <Label>Icon (Lucide name)</Label>
+                    <Input
+                        value={form.icon}
+                        onChange={(e) => setForm({ ...form, icon: e.target.value })}
+                        placeholder="e.g. Sparkles, Zap"
+                    />
+                </div>
+            </div>
 
-    const SlotIcon = SLOT_ICON_MAP[slot];
-    const config = SLOT_CONFIG[slot];
-    const currentVariant = variantBySlot[slot] || config.default;
-    const isEnabled = section?.enabled ?? true;
-
-    // Create section if it doesn't exist
-    const handleEnsureSection = async () => {
-        if (!section) {
-            await createSection.mutateAsync({
-                slot,
-                title: SLOT_LABELS[slot],
-                enabled: true,
-                sortOrder: SLOT_NAMES.indexOf(slot),
-            });
-            onRefresh();
-        }
-    };
+            <div className="space-y-2">
+                <Label>Subtitle</Label>
+                <Input
+                    value={form.subtitle}
+                    onChange={(e) => setForm({ ...form, subtitle: e.target.value })}
+                    placeholder="A short tagline or description"
+                />
+            </div>
 
-    // Update section field
-    const handleFieldChange = async (field: string, value: unknown) => {
-        if (!section) {
-            await handleEnsureSection();
-            return;
-        }
-        await updateSection.mutateAsync({ id: section.id, data: { [field]: value } });
-        onSectionChange(slot, field, value);
-    };
+            <div className="space-y-2">
+                <Label>Body Content</Label>
+                <Textarea
+                    value={form.body}
+                    onChange={(e) => setForm({ ...form, body: e.target.value })}
+                    rows={4}
+                    placeholder="Main content for this section (supports markdown)"
+                />
+            </div>
 
-    // Toggle enabled state
-    const handleToggleEnabled = async () => {
-        if (!section) {
-            await createSection.mutateAsync({
-                slot,
-                title: SLOT_LABELS[slot],
-                enabled: true,
-                sortOrder: SLOT_NAMES.indexOf(slot),
-            });
-            onRefresh();
-            return;
-        }
-        await updateSection.mutateAsync({ id: section.id, data: { enabled: !isEnabled } });
-        onRefresh();
-    };
+            {showGithub && (
+                <div className="space-y-2">
+                    <Label>GitHub URL</Label>
+                    <Input
+                        value={form.githubUrl}
+                        onChange={(e) => setForm({ ...form, githubUrl: e.target.value })}
+                        placeholder="https://github.com/your-org/your-repo"
+                    />
+                </div>
+            )}
 
-    return (
-        <AccordionItem value={slot} className="border rounded-lg">
-            <div className="flex items-center gap-3 px-4 py-3 [&:has([data-state=open])]:bg-muted/50">
-                <AccordionTrigger className="flex items-center gap-3 flex-1 hover:no-underline p-0 [&>svg:last-child]:hidden">
-                    <div className="flex items-center justify-center w-8 h-8 rounded-md bg-primary/10">
-                        <SlotIcon className="w-4 h-4 text-primary" />
-                    </div>
-                    <div className="flex-1 text-left">
-                        <div className="flex items-center gap-2">
-                            <span className="font-medium">{SLOT_LABELS[slot]}</span>
-                            {!isEnabled && (
-                                <Badge variant="secondary" className="text-[10px]">
-                                    Hidden
-                                </Badge>
-                            )}
-                        </div>
-                        <p className="text-xs text-muted-foreground">{SLOT_DESCRIPTIONS[slot]}</p>
-                    </div>
-                    <ChevronDown className="h-4 w-4 shrink-0 transition-transform duration-200 [[data-state=open]_&]:rotate-180" />
-                </AccordionTrigger>
-                <div className="flex items-center gap-2">
-                    <Select value={currentVariant} onValueChange={(v) => onVariantChange(slot, v)}>
-                        <SelectTrigger className="h-7 w-28 text-xs">
-                            <SelectValue />
-                        </SelectTrigger>
-                        <SelectContent>
-                            {config.variants.map((v) => (
-                                <SelectItem key={v.id} value={v.id}>
-                                    {v.label}
-                                </SelectItem>
-                            ))}
-                        </SelectContent>
-                    </Select>
-                    <TooltipProvider>
-                        <Tooltip>
-                            <TooltipTrigger asChild>
-                                <div>
-                                    <Switch
-                                        checked={isEnabled}
-                                        onCheckedChange={handleToggleEnabled}
-                                        className="data-[state=checked]:bg-green-500"
+            {/* Features */}
+            {showFeatures && (
+                <Card>
+                    <CardHeader>
+                        <CardTitle className="text-base">Features</CardTitle>
+                        <CardDescription>Items displayed in this section</CardDescription>
+                    </CardHeader>
+                    <CardContent className="space-y-4">
+                        {features.length > 0 && (
+                            <div className="space-y-2">
+                                {features.map((f) => (
+                                    <div
+                                        key={f.id}
+                                        className="flex items-center gap-3 p-3 rounded-lg border bg-muted/30"
+                                    >
+                                        {f.icon && <Badge variant="secondary">{f.icon}</Badge>}
+                                        <div className="flex-1 min-w-0">
+                                            <p className="font-medium text-sm">{f.title}</p>
+                                            {f.description && (
+                                                <p className="text-xs text-muted-foreground truncate">
+                                                    {f.description}
+                                                </p>
+                                            )}
+                                        </div>
+                                        <Button
+                                            variant="ghost"
+                                            size="icon"
+                                            className="h-8 w-8 shrink-0"
+                                            onClick={async () => {
+                                                await deleteFeature.mutateAsync(f.id);
+                                                onRefresh();
+                                            }}
+                                        >
+                                            <Trash2 className="h-4 w-4 text-destructive" />
+                                        </Button>
+                                    </div>
+                                ))}
+                            </div>
+                        )}
+                        <Separator />
+                        <div className="space-y-3">
+                            <Label className="text-sm">Add Feature</Label>
+                            <div className="grid gap-3 md:grid-cols-3">
+                                <Input
+                                    placeholder="Title"
+                                    value={newFeature.title}
+                                    onChange={(e) => setNewFeature({ ...newFeature, title: e.target.value })}
+                                />
+                                <Input
+                                    placeholder="Description"
+                                    value={newFeature.description}
+                                    onChange={(e) => setNewFeature({ ...newFeature, description: e.target.value })}
+                                />
+                                <div className="flex gap-2">
+                                    <Input
+                                        placeholder="Icon"
+                                        value={newFeature.icon}
+                                        onChange={(e) => setNewFeature({ ...newFeature, icon: e.target.value })}
+                                        className="flex-1"
                                     />
+                                    <Button onClick={handleAddFeature} disabled={!newFeature.title.trim()}>
+                                        <Plus className="h-4 w-4" />
+                                    </Button>
                                 </div>
-                            </TooltipTrigger>
-                            <TooltipContent>
-                                <p>{isEnabled ? 'Visible on homepage' : 'Hidden from homepage'}</p>
-                            </TooltipContent>
-                        </Tooltip>
-                    </TooltipProvider>
-                </div>
-            </div>
-            <AccordionContent className="px-4 pb-4">
-                <div className="space-y-4 pt-2">
-                    {/* Section Content Fields */}
-                    <div className="grid gap-4 sm:grid-cols-2">
-                        <div className="space-y-2">
-                            <Label htmlFor={`${slot}-title`} className="text-xs">
-                                Title
-                            </Label>
-                            <Input
-                                id={`${slot}-title`}
-                                value={section?.title || ''}
-                                onChange={(e) => handleFieldChange('title', e.target.value)}
-                                placeholder={`${SLOT_LABELS[slot]} title`}
-                                className="h-9"
-                            />
-                        </div>
-                        <div className="space-y-2">
-                            <Label htmlFor={`${slot}-icon`} className="text-xs">
-                                Icon (Lucide name)
-                            </Label>
-                            <Input
-                                id={`${slot}-icon`}
-                                value={section?.icon || ''}
-                                onChange={(e) => handleFieldChange('icon', e.target.value)}
-                                placeholder="e.g. Sparkles, Zap, Shield"
-                                className="h-9"
-                            />
+                            </div>
                         </div>
-                    </div>
-
-                    <div className="space-y-2">
-                        <Label htmlFor={`${slot}-subtitle`} className="text-xs">
-                            Subtitle
-                        </Label>
-                        <Input
-                            id={`${slot}-subtitle`}
-                            value={section?.subtitle || ''}
-                            onChange={(e) => handleFieldChange('subtitle', e.target.value)}
-                            placeholder="Short tagline or description"
-                            className="h-9"
-                        />
-                    </div>
-
-                    <div className="space-y-2">
-                        <Label htmlFor={`${slot}-body`} className="text-xs">
-                            Body Content
-                        </Label>
-                        <Textarea
-                            id={`${slot}-body`}
-                            value={section?.body || ''}
-                            onChange={(e) => handleFieldChange('body', e.target.value)}
-                            placeholder="Main content for this section (supports markdown)"
-                            rows={3}
-                        />
-                    </div>
+                    </CardContent>
+                </Card>
+            )}
 
-                    {/* Navbar-specific: GitHub URL */}
-                    {slot === 'navbar' && (
-                        <div className="space-y-2">
-                            <Label htmlFor={`${slot}-github`} className="text-xs">
-                                GitHub URL
-                            </Label>
-                            <Input
-                                id={`${slot}-github`}
-                                value={section?.githubUrl || ''}
-                                onChange={(e) => handleFieldChange('githubUrl', e.target.value)}
-                                placeholder="https://github.com/your-org/your-repo"
-                                className="h-9"
-                            />
-                        </div>
-                    )}
-
-                    <Separator />
-
-                    {/* Features (for features, about slots) */}
-                    {(slot === 'features' || slot === 'about') && section && (
-                        <FeatureEditor sectionId={section.id} features={features} onRefresh={onRefresh} />
-                    )}
-
-                    {/* Actions (for hero, cta, about slots) */}
-                    {(slot === 'hero' || slot === 'cta' || slot === 'about') && section && (
-                        <ActionEditor sectionId={section.id} actions={actions} onRefresh={onRefresh} />
-                    )}
-
-                    {/* Prompt to create section if none exists */}
-                    {!section && (
-                        <div className="text-center py-4">
-                            <p className="text-sm text-muted-foreground mb-2">This slot has no content yet.</p>
-                            <Button size="sm" onClick={handleEnsureSection}>
-                                <Plus className="mr-1 h-4 w-4" />
-                                Initialize Section
-                            </Button>
+            {/* Actions */}
+            {showActions && (
+                <Card>
+                    <CardHeader>
+                        <CardTitle className="text-base">Buttons / Actions</CardTitle>
+                        <CardDescription>Call-to-action buttons in this section</CardDescription>
+                    </CardHeader>
+                    <CardContent className="space-y-4">
+                        {actions.length > 0 && (
+                            <div className="space-y-2">
+                                {actions.map((a) => (
+                                    <div
+                                        key={a.id}
+                                        className="flex items-center gap-3 p-3 rounded-lg border bg-muted/30"
+                                    >
+                                        <Badge variant="outline">{a.variant || 'default'}</Badge>
+                                        <div className="flex-1 min-w-0">
+                                            <p className="font-medium text-sm">{a.label}</p>
+                                            <p className="text-xs text-muted-foreground truncate">{a.href}</p>
+                                        </div>
+                                        <Button
+                                            variant="ghost"
+                                            size="icon"
+                                            className="h-8 w-8 shrink-0"
+                                            onClick={async () => {
+                                                await deleteAction.mutateAsync(a.id);
+                                                onRefresh();
+                                            }}
+                                        >
+                                            <Trash2 className="h-4 w-4 text-destructive" />
+                                        </Button>
+                                    </div>
+                                ))}
+                            </div>
+                        )}
+                        <Separator />
+                        <div className="space-y-3">
+                            <Label className="text-sm">Add Button</Label>
+                            <div className="grid gap-3 md:grid-cols-4">
+                                <Input
+                                    placeholder="Label"
+                                    value={newAction.label}
+                                    onChange={(e) => setNewAction({ ...newAction, label: e.target.value })}
+                                />
+                                <Input
+                                    placeholder="URL (e.g. /docs)"
+                                    value={newAction.href}
+                                    onChange={(e) => setNewAction({ ...newAction, href: e.target.value })}
+                                />
+                                <Select
+                                    value={newAction.variant}
+                                    onValueChange={(v) => setNewAction({ ...newAction, variant: v })}
+                                >
+                                    <SelectTrigger>
+                                        <SelectValue />
+                                    </SelectTrigger>
+                                    <SelectContent>
+                                        {ACTION_VARIANTS.map((v) => (
+                                            <SelectItem key={v.value} value={v.value}>
+                                                {v.label}
+                                            </SelectItem>
+                                        ))}
+                                    </SelectContent>
+                                </Select>
+                                <Button
+                                    onClick={handleAddAction}
+                                    disabled={!newAction.label.trim() || !newAction.href.trim()}
+                                >
+                                    <Plus className="h-4 w-4" />
+                                </Button>
+                            </div>
                         </div>
-                    )}
-                </div>
-            </AccordionContent>
-        </AccordionItem>
+                    </CardContent>
+                </Card>
+            )}
+
+            {/* Save */}
+            <div className="flex justify-end pt-4">
+                <Button onClick={handleSave} size="lg">
+                    {saved ? <Check className="mr-2 h-4 w-4" /> : <Save className="mr-2 h-4 w-4" />}
+                    {saved ? 'Saved!' : 'Save Changes'}
+                </Button>
+            </div>
+        </div>
     );
 }
 
 // ── Main Builder Page ───────────────────────────────────────────────────────
 
 export function AdminHomepageBuilderPage() {
-    // Load all data
+    // Data hooks
     const {
         data: sectionsData,
         isLoading: sectionsLoading,
         refetch: refetchSections,
     } = homepageSectionHooks.useList({ orderBy: 'sortOrder', orderDirection: 'asc' }, ADMIN_LIST_QUERY_CONFIG);
-
     const { data: featuresData, refetch: refetchFeatures } = homepageFeatureHooks.useList(
         { orderBy: 'sortOrder', orderDirection: 'asc' },
         ADMIN_LIST_QUERY_CONFIG,
     );
-
     const { data: actionsData, refetch: refetchActions } = homepageActionHooks.useList(
         { orderBy: 'sortOrder', orderDirection: 'asc' },
         ADMIN_LIST_QUERY_CONFIG,
     );
-
     const {
         data: displayData,
         isLoading: displayLoading,
         refetch: refetchDisplay,
     } = homepageDisplaySettingsHooks.useList({}, ADMIN_LIST_QUERY_CONFIG);
 
+    const createSection = homepageSectionHooks.useCreate();
+    const updateSection = homepageSectionHooks.useUpdate();
+    const deleteSection = homepageSectionHooks.useDelete();
     const createDisplay = homepageDisplaySettingsHooks.useCreate();
     const updateDisplay = homepageDisplaySettingsHooks.useUpdate();
 
@@ -614,18 +601,13 @@ export function AdminHomepageBuilderPage() {
     );
     const display = displayRows.find((r) => r.id === 'default') ?? null;
 
-    // Section lookup by slot
+    // Lookup maps
     const sectionBySlot = useMemo(() => {
-        const map: Partial<Record<SlotName, HomepageSectionRow>> = {};
-        for (const s of sections) {
-            if (SLOT_NAMES.includes(s.slot as SlotName)) {
-                map[s.slot as SlotName] = s;
-            }
-        }
+        const map: Record<string, HomepageSectionRow> = {};
+        for (const s of sections) map[s.slot] = s;
         return map;
     }, [sections]);
 
-    // Features/actions grouped by sectionId
     const featuresBySectionId = useMemo(() => {
         const map: Record<string, HomepageFeatureRow[]> = {};
         for (const f of features) {
@@ -644,67 +626,57 @@ export function AdminHomepageBuilderPage() {
         return map;
     }, [actions]);
 
-    // Local state for display settings
-    const getDefaultVariantBySlot = () =>
-        Object.fromEntries(SLOT_NAMES.map((s) => [s, SLOT_CONFIG[s].default])) as Record<string, string>;
+    // Refresh
+    const handleRefresh = useCallback(() => {
+        refetchSections();
+        refetchFeatures();
+        refetchActions();
+    }, [refetchSections, refetchFeatures, refetchActions]);
 
-    const [variantBySlot, setVariantBySlot] = useState<Record<string, string>>(getDefaultVariantBySlot());
-    const [themePreset, setThemePreset] = useState('default');
-    const [customCss, setCustomCss] = useState('');
-    const [seoTitle, setSeoTitle] = useState('');
-    const [seoDescription, setSeoDescription] = useState('');
-    const [settingsOpen, setSettingsOpen] = useState(false);
-    const [initialized, setInitialized] = useState(false);
+    // Section CRUD
+    const handleCreateSection = async (type: SectionType) => {
+        const typeInfo = SECTION_TYPES.find((t) => t.id === type);
+        await createSection.mutateAsync({
+            slot: type,
+            title: typeInfo?.label ?? type,
+            enabled: true,
+            sortOrder: sections.length,
+        });
+        handleRefresh();
+    };
 
-    // Populate from DB
-    useEffect(() => {
-        if (display && !initialized) {
-            setVariantBySlot({ ...getDefaultVariantBySlot(), ...(display.variantBySlotJson ?? {}) });
-            setThemePreset(display.themePreset ?? 'default');
-            setCustomCss(display.customCss ?? '');
-            setSeoTitle(display.seoTitle ?? '');
-            setSeoDescription(display.seoDescription ?? '');
-            setInitialized(true);
-        } else if (!displayLoading && !display && !initialized) {
-            setInitialized(true);
-        }
-    }, [display, displayLoading, initialized]);
+    const handleUpdateSection = async (id: string, data: Partial<HomepageSectionRow>) => {
+        await updateSection.mutateAsync({ id, data });
+        handleRefresh();
+    };
 
-    // Save display settings
-    const handleSaveDisplaySettings = async () => {
-        const payload = {
-            variantBySlotJson: variantBySlot,
-            themePreset,
-            customCss: customCss || undefined,
-            seoTitle: seoTitle || undefined,
-            seoDescription: seoDescription || undefined,
-        };
+    const handleToggleSection = async (section: HomepageSectionRow) => {
+        await updateSection.mutateAsync({ id: section.id, data: { enabled: !section.enabled } });
+        handleRefresh();
+    };
+
+    const handleDeleteSection = async (section: HomepageSectionRow) => {
+        if (!confirm(`Delete "${section.title || section.slot}" section?`)) return;
+        await deleteSection.mutateAsync(section.id);
+        handleRefresh();
+    };
+
+    // Display settings
+    const handleSaveSettings = async (data: {
+        themePreset: string;
+        seoTitle?: string;
+        seoDescription?: string;
+        customCss?: string;
+    }) => {
         if (display) {
-            await updateDisplay.mutateAsync({ id: 'default', data: payload });
+            await updateDisplay.mutateAsync({ id: 'default', data });
         } else {
-            await createDisplay.mutateAsync({ id: 'default', ...payload });
+            await createDisplay.mutateAsync({ id: 'default', ...data });
         }
         refetchDisplay();
     };
 
-    // Variant change handler
-    const handleVariantChange = useCallback((slot: SlotName, variantId: string) => {
-        setVariantBySlot((prev) => ({ ...prev, [slot]: variantId }));
-    }, []);
-
-    // Section field change (just refresh data)
-    const handleSectionChange = useCallback(() => {
-        refetchSections();
-    }, [refetchSections]);
-
-    // Refresh all data
-    const handleRefresh = useCallback(() => {
-        refetchSections();
-        refetchFeatures();
-        refetchActions();
-    }, [refetchSections, refetchFeatures, refetchActions]);
-
-    // Seed demo data
+    // Seed
     const [seeding, setSeeding] = useState(false);
     const handleSeed = async () => {
         setSeeding(true);
@@ -721,218 +693,101 @@ export function AdminHomepageBuilderPage() {
 
     if (sectionsLoading || displayLoading) {
         return (
-            <div className="p-6">
-                <div className="flex items-center gap-3 mb-6">
-                    <div className="flex items-center gap-2 rounded-lg bg-primary/10 p-2">
-                        <Home className="h-5 w-5 text-primary" />
-                    </div>
-                    <div>
-                        <h1 className="text-xl font-semibold">Homepage Builder</h1>
-                        <p className="text-sm text-muted-foreground">Loading...</p>
-                    </div>
-                </div>
+            <div className="flex items-center justify-center min-h-[400px]">
+                <div className="text-muted-foreground">Loading...</div>
             </div>
         );
     }
 
-    const isDirty =
-        initialized &&
-        (JSON.stringify(variantBySlot) !==
-            JSON.stringify({ ...getDefaultVariantBySlot(), ...(display?.variantBySlotJson ?? {}) }) ||
-            themePreset !== (display?.themePreset ?? 'default') ||
-            customCss !== (display?.customCss ?? '') ||
-            seoTitle !== (display?.seoTitle ?? '') ||
-            seoDescription !== (display?.seoDescription ?? ''));
-
     return (
-        <div className="p-6 space-y-6 max-w-4xl mx-auto">
+        <div className="min-h-screen">
             {/* Header */}
-            <div className="flex items-center justify-between">
-                <div className="flex items-center gap-3">
-                    <div className="flex items-center gap-2 rounded-lg bg-primary/10 p-2">
-                        <Home className="h-5 w-5 text-primary" />
-                    </div>
-                    <div>
-                        <h1 className="text-xl font-semibold">Homepage Builder</h1>
-                        <p className="text-sm text-muted-foreground">
-                            Configure all sections, content, and display settings
-                        </p>
+            <div className="border-b bg-background/95 backdrop-blur supports-[backdrop-filter]:bg-background/60">
+                <div className="flex items-center justify-between px-6 py-4">
+                    <div className="flex items-center gap-3">
+                        <div className="w-10 h-10 rounded-lg bg-primary/10 flex items-center justify-center">
+                            <Home className="h-5 w-5 text-primary" />
+                        </div>
+                        <div>
+                            <h1 className="text-xl font-semibold">Homepage Builder</h1>
+                            <p className="text-sm text-muted-foreground">{sections.length} sections configured</p>
+                        </div>
                     </div>
-                </div>
-                <div className="flex items-center gap-2">
-                    <TooltipProvider>
-                        <Tooltip>
-                            <TooltipTrigger asChild>
-                                <Button variant="outline" size="sm" onClick={handleSeed} disabled={seeding}>
-                                    <IconDatabaseImport className="mr-1 h-4 w-4" />
-                                    Seed Demo
-                                </Button>
-                            </TooltipTrigger>
-                            <TooltipContent>
-                                <p>Populate all sections with demo content</p>
-                            </TooltipContent>
-                        </Tooltip>
-                    </TooltipProvider>
                     <a
                         href={import.meta.env.VITE_HOMEPAGE_URL || 'http://localhost:3000'}
                         target="_blank"
                         rel="noopener noreferrer"
                     >
-                        <Button variant="outline" size="sm">
-                            <ExternalLink className="mr-1 h-4 w-4" />
-                            Preview
+                        <Button variant="outline">
+                            <ExternalLink className="mr-2 h-4 w-4" />
+                            Preview Site
                         </Button>
                     </a>
                 </div>
             </div>
 
-            {/* Settings Panel (Collapsible) */}
-            <Collapsible open={settingsOpen} onOpenChange={setSettingsOpen}>
-                <Card>
-                    <CollapsibleTrigger asChild>
-                        <CardHeader className="cursor-pointer hover:bg-muted/50 transition-colors">
-                            <div className="flex items-center justify-between">
-                                <div className="flex items-center gap-2">
-                                    <Settings className="h-4 w-4 text-muted-foreground" />
-                                    <CardTitle className="text-base">Display Settings</CardTitle>
-                                </div>
-                                <div className="flex items-center gap-2">
-                                    {isDirty && (
-                                        <Badge variant="secondary" className="text-xs">
-                                            Unsaved
-                                        </Badge>
-                                    )}
-                                    <Badge variant="outline" className="text-xs capitalize">
-                                        {themePreset} theme
-                                    </Badge>
-                                    <ChevronDown
-                                        className={`h-4 w-4 text-muted-foreground transition-transform ${settingsOpen ? 'rotate-180' : ''}`}
-                                    />
-                                </div>
-                            </div>
-                            <CardDescription>Theme preset, SEO metadata, and custom styles</CardDescription>
-                        </CardHeader>
-                    </CollapsibleTrigger>
-                    <CollapsibleContent>
-                        <CardContent className="space-y-4 border-t pt-4">
-                            {/* Theme Preset */}
-                            <div className="space-y-2">
-                                <Label className="text-xs">Theme Preset</Label>
-                                <div className="grid grid-cols-4 gap-2">
-                                    {THEME_PRESETS.map((preset) => (
-                                        <button
-                                            key={preset.id}
-                                            type="button"
-                                            onClick={() => setThemePreset(preset.id)}
-                                            className={`rounded-lg border p-3 text-left transition-colors hover:bg-muted/50 ${
-                                                themePreset === preset.id
-                                                    ? 'border-primary bg-primary/5 ring-1 ring-primary'
-                                                    : ''
-                                            }`}
-                                        >
-                                            <div className="flex items-center gap-2">
-                                                <Palette className="h-4 w-4" />
-                                                <span className="font-medium text-sm">{preset.label}</span>
-                                            </div>
-                                            <p className="mt-1 text-xs text-muted-foreground">{preset.description}</p>
-                                        </button>
-                                    ))}
-                                </div>
-                            </div>
-
-                            <Separator />
-
-                            {/* SEO Fields */}
-                            <div className="grid gap-4 sm:grid-cols-2">
-                                <div className="space-y-2">
-                                    <Label htmlFor="seo-title" className="text-xs">
-                                        SEO Title
-                                    </Label>
-                                    <Input
-                                        id="seo-title"
-                                        value={seoTitle}
-                                        onChange={(e) => setSeoTitle(e.target.value)}
-                                        placeholder="Page title for search engines"
-                                        className="h-9"
-                                    />
-                                </div>
-                                <div className="space-y-2">
-                                    <Label htmlFor="seo-desc" className="text-xs">
-                                        SEO Description
-                                    </Label>
-                                    <Input
-                                        id="seo-desc"
-                                        value={seoDescription}
-                                        onChange={(e) => setSeoDescription(e.target.value)}
-                                        placeholder="Meta description for search engines"
-                                        className="h-9"
-                                    />
-                                </div>
-                            </div>
-
-                            {/* Custom CSS */}
-                            <div className="space-y-2">
-                                <Label htmlFor="custom-css" className="text-xs">
-                                    Custom CSS (advanced)
-                                </Label>
-                                <Textarea
-                                    id="custom-css"
-                                    value={customCss}
-                                    onChange={(e) => setCustomCss(e.target.value)}
-                                    placeholder=".hero { background: linear-gradient(...); }"
-                                    rows={3}
-                                    className="font-mono text-xs"
-                                />
-                            </div>
-
-                            {/* Save Button */}
-                            <div className="flex justify-end">
-                                <Button
-                                    size="sm"
-                                    onClick={handleSaveDisplaySettings}
-                                    disabled={!isDirty || updateDisplay.isPending || createDisplay.isPending}
+            {/* Tabs */}
+            <Tabs defaultValue="settings" className="w-full">
+                <div className="border-b px-6">
+                    <TabsList className="h-12 bg-transparent gap-2">
+                        <TabsTrigger value="settings" className="data-[state=active]:bg-muted gap-2">
+                            <Settings className="h-4 w-4" />
+                            Settings
+                        </TabsTrigger>
+                        {SECTION_TYPES.map((type) => {
+                            const section = sectionBySlot[type.id];
+                            return (
+                                <TabsTrigger
+                                    key={type.id}
+                                    value={type.id}
+                                    className="data-[state=active]:bg-muted gap-2"
                                 >
-                                    <Save className="mr-1 h-4 w-4" />
-                                    Save Settings
-                                </Button>
-                            </div>
-                        </CardContent>
-                    </CollapsibleContent>
-                </Card>
-            </Collapsible>
-
-            {/* Slot Cards */}
-            <div>
-                <div className="flex items-center gap-2 mb-4">
-                    <Layout className="h-4 w-4 text-muted-foreground" />
-                    <h2 className="font-medium">Page Sections</h2>
-                    <Badge variant="secondary" className="text-xs">
-                        {sections.filter((s) => s.enabled).length} / {SLOT_NAMES.length} active
-                    </Badge>
+                                    <type.icon className="h-4 w-4" />
+                                    {type.label}
+                                    {section && (
+                                        <span
+                                            className={`w-2 h-2 rounded-full ${section.enabled ? 'bg-green-500' : 'bg-muted-foreground/30'}`}
+                                        />
+                                    )}
+                                </TabsTrigger>
+                            );
+                        })}
+                    </TabsList>
                 </div>
 
-                <Accordion type="multiple" className="space-y-3">
-                    {SLOT_NAMES.map((slot) => {
-                        const section = sectionBySlot[slot] ?? null;
-                        const sectionFeatures = section ? featuresBySectionId[section.id] || [] : [];
-                        const sectionActions = section ? actionsBySectionId[section.id] || [] : [];
+                <div className="p-6 max-w-4xl mx-auto">
+                    <TabsContent value="settings" className="mt-0">
+                        <SettingsTab
+                            display={display}
+                            onSave={handleSaveSettings}
+                            onSeed={handleSeed}
+                            seeding={seeding}
+                        />
+                    </TabsContent>
+
+                    {SECTION_TYPES.map((type) => {
+                        const section = sectionBySlot[type.id] ?? null;
+                        const sectionFeatures = section ? (featuresBySectionId[section.id] ?? []) : [];
+                        const sectionActions = section ? (actionsBySectionId[section.id] ?? []) : [];
 
                         return (
-                            <SlotCard
-                                key={slot}
-                                slot={slot}
-                                section={section}
-                                features={sectionFeatures}
-                                actions={sectionActions}
-                                variantBySlot={variantBySlot}
-                                onSectionChange={handleSectionChange}
-                                onVariantChange={handleVariantChange}
-                                onRefresh={handleRefresh}
-                            />
+                            <TabsContent key={type.id} value={type.id} className="mt-0">
+                                <SectionTab
+                                    sectionType={type}
+                                    section={section}
+                                    features={sectionFeatures}
+                                    actions={sectionActions}
+                                    onCreateSection={() => handleCreateSection(type.id)}
+                                    onUpdateSection={(data) => section && handleUpdateSection(section.id, data)}
+                                    onToggleSection={() => section && handleToggleSection(section)}
+                                    onDeleteSection={() => section && handleDeleteSection(section)}
+                                    onRefresh={handleRefresh}
+                                />
+                            </TabsContent>
                         );
                     })}
-                </Accordion>
-            </div>
+                </div>
+            </Tabs>
         </div>
     );
 }
diff --git a/apps/ottabase-template-app-tanstack/src/pages/admin/pages/AdminPageBuilderPage.tsx b/apps/ottabase-template-app-tanstack/src/pages/admin/pages/AdminPageBuilderPage.tsx
new file mode 100644
index 000000000..168fa9319
--- /dev/null
+++ b/apps/ottabase-template-app-tanstack/src/pages/admin/pages/AdminPageBuilderPage.tsx
@@ -0,0 +1,838 @@
+/**
+ * Admin Page Builder
+ *
+ * Full-featured page editor with tab-based section management.
+ * Similar to homepage builder but works for any page by ID.
+ */
+import { ADMIN_LIST_QUERY_CONFIG } from '@/config/queryConfig';
+import {
+    pageActionHooks,
+    pageFeatureHooks,
+    pageHooks,
+    pageSectionHooks,
+    type PageActionRow,
+    type PageFeatureRow,
+    type PageRow,
+    type PageSectionRow,
+} from '@/hooks/pageHooks';
+import {
+    Badge,
+    Button,
+    Card,
+    CardContent,
+    CardDescription,
+    CardHeader,
+    CardTitle,
+    Input,
+    Label,
+    Select,
+    SelectContent,
+    SelectItem,
+    SelectTrigger,
+    SelectValue,
+    Separator,
+    Switch,
+    Tabs,
+    TabsContent,
+    TabsList,
+    TabsTrigger,
+    Textarea,
+} from '@ottabase/ui-shadcn';
+import { Link, useParams } from '@tanstack/react-router';
+import { ArrowLeft, Check, ExternalLink, Palette, Plus, Save, Settings, Trash2 } from 'lucide-react';
+import { useCallback, useEffect, useMemo, useState } from 'react';
+import {
+    ACTION_VARIANTS,
+    getSlotConfig,
+    PAGE_STATUS_OPTIONS,
+    SLOT_TYPES,
+    THEME_PRESETS,
+    type SlotConfig,
+} from './pages-constants';
+
+// ── Settings Tab ────────────────────────────────────────────────────────────
+
+function SettingsTab({ page, onSave }: { page: PageRow; onSave: (data: Partial<PageRow>) => void }) {
+    const [form, setForm] = useState({
+        title: page.title,
+        slug: page.slug,
+        status: page.status,
+        themePreset: page.themePreset ?? 'default',
+        seoTitle: page.seoTitle ?? '',
+        seoDescription: page.seoDescription ?? '',
+        seoImage: page.seoImage ?? '',
+        customCss: page.customCss ?? '',
+        showInNav: page.showInNav ?? false,
+        navOrder: page.navOrder ?? 0,
+        navLabel: page.navLabel ?? '',
+        icon: page.icon ?? '',
+    });
+    const [saved, setSaved] = useState(false);
+
+    useEffect(() => {
+        setForm({
+            title: page.title,
+            slug: page.slug,
+            status: page.status,
+            themePreset: page.themePreset ?? 'default',
+            seoTitle: page.seoTitle ?? '',
+            seoDescription: page.seoDescription ?? '',
+            seoImage: page.seoImage ?? '',
+            customCss: page.customCss ?? '',
+            showInNav: page.showInNav ?? false,
+            navOrder: page.navOrder ?? 0,
+            navLabel: page.navLabel ?? '',
+            icon: page.icon ?? '',
+        });
+    }, [page]);
+
+    const handleSave = () => {
+        onSave(form);
+        setSaved(true);
+        setTimeout(() => setSaved(false), 2000);
+    };
+
+    return (
+        <div className="space-y-8">
+            {/* Page Info */}
+            <Card>
+                <CardHeader>
+                    <CardTitle>Page Info</CardTitle>
+                    <CardDescription>Basic page settings</CardDescription>
+                </CardHeader>
+                <CardContent className="space-y-4">
+                    <div className="grid gap-4 md:grid-cols-2">
+                        <div className="space-y-2">
+                            <Label>Title</Label>
+                            <Input
+                                value={form.title}
+                                onChange={(e) => setForm({ ...form, title: e.target.value })}
+                                placeholder="Page Title"
+                            />
+                        </div>
+                        <div className="space-y-2">
+                            <Label>Slug</Label>
+                            <Input
+                                value={form.slug}
+                                onChange={(e) => setForm({ ...form, slug: e.target.value })}
+                                placeholder="page-slug"
+                                disabled={page.slug === 'homepage'}
+                            />
+                            {page.slug === 'homepage' && (
+                                <p className="text-xs text-muted-foreground">Homepage slug cannot be changed</p>
+                            )}
+                        </div>
+                    </div>
+                    <div className="space-y-2">
+                        <Label>Status</Label>
+                        <Select
+                            value={form.status}
+                            onValueChange={(v: PageRow['status']) => setForm({ ...form, status: v })}
+                        >
+                            <SelectTrigger className="w-48">
+                                <SelectValue />
+                            </SelectTrigger>
+                            <SelectContent>
+                                {PAGE_STATUS_OPTIONS.map((opt) => (
+                                    <SelectItem key={opt.value} value={opt.value}>
+                                        {opt.label}
+                                    </SelectItem>
+                                ))}
+                            </SelectContent>
+                        </Select>
+                    </div>
+                </CardContent>
+            </Card>
+
+            {/* Theme Selection */}
+            <Card>
+                <CardHeader>
+                    <CardTitle className="flex items-center gap-2">
+                        <Palette className="h-5 w-5" />
+                        Theme
+                    </CardTitle>
+                    <CardDescription>Choose a visual theme for this page</CardDescription>
+                </CardHeader>
+                <CardContent>
+                    <div className="grid grid-cols-2 md:grid-cols-4 gap-3">
+                        {THEME_PRESETS.map((preset) => (
+                            <button
+                                key={preset.id}
+                                type="button"
+                                onClick={() => setForm({ ...form, themePreset: preset.id })}
+                                className={`p-4 rounded-lg border text-left transition-all ${
+                                    form.themePreset === preset.id
+                                        ? 'border-primary bg-primary/5 ring-2 ring-primary shadow-sm'
+                                        : 'hover:bg-muted/50 hover:border-muted-foreground/30'
+                                }`}
+                            >
+                                <div className="font-medium">{preset.label}</div>
+                                <p className="text-xs text-muted-foreground mt-1">{preset.description}</p>
+                            </button>
+                        ))}
+                    </div>
+                </CardContent>
+            </Card>
+
+            {/* Navigation */}
+            <Card>
+                <CardHeader>
+                    <CardTitle>Navigation</CardTitle>
+                    <CardDescription>Control how this page appears in navigation</CardDescription>
+                </CardHeader>
+                <CardContent className="space-y-4">
+                    <div className="flex items-center justify-between">
+                        <div>
+                            <Label>Show in navigation</Label>
+                            <p className="text-sm text-muted-foreground">Display link in site navigation</p>
+                        </div>
+                        <Switch checked={form.showInNav} onCheckedChange={(v) => setForm({ ...form, showInNav: v })} />
+                    </div>
+                    {form.showInNav && (
+                        <div className="grid gap-4 md:grid-cols-3 pt-2">
+                            <div className="space-y-2">
+                                <Label>Nav Label (optional)</Label>
+                                <Input
+                                    value={form.navLabel}
+                                    onChange={(e) => setForm({ ...form, navLabel: e.target.value })}
+                                    placeholder={form.title || 'Page title'}
+                                />
+                            </div>
+                            <div className="space-y-2">
+                                <Label>Nav Order</Label>
+                                <Input
+                                    type="number"
+                                    value={form.navOrder}
+                                    onChange={(e) => setForm({ ...form, navOrder: parseInt(e.target.value) || 0 })}
+                                />
+                            </div>
+                            <div className="space-y-2">
+                                <Label>Icon (Lucide name)</Label>
+                                <Input
+                                    value={form.icon}
+                                    onChange={(e) => setForm({ ...form, icon: e.target.value })}
+                                    placeholder="e.g. FileText"
+                                />
+                            </div>
+                        </div>
+                    )}
+                </CardContent>
+            </Card>
+
+            {/* SEO */}
+            <Card>
+                <CardHeader>
+                    <CardTitle>SEO</CardTitle>
+                    <CardDescription>Search engine optimization settings</CardDescription>
+                </CardHeader>
+                <CardContent className="space-y-4">
+                    <div className="space-y-2">
+                        <Label>Page Title</Label>
+                        <Input
+                            value={form.seoTitle}
+                            onChange={(e) => setForm({ ...form, seoTitle: e.target.value })}
+                            placeholder={form.title || 'Page Title - Site Name'}
+                        />
+                    </div>
+                    <div className="space-y-2">
+                        <Label>Meta Description</Label>
+                        <Textarea
+                            value={form.seoDescription}
+                            onChange={(e) => setForm({ ...form, seoDescription: e.target.value })}
+                            placeholder="A compelling description for search engines..."
+                            rows={3}
+                        />
+                    </div>
+                    <div className="space-y-2">
+                        <Label>Social Image URL</Label>
+                        <Input
+                            value={form.seoImage}
+                            onChange={(e) => setForm({ ...form, seoImage: e.target.value })}
+                            placeholder="https://example.com/og-image.png"
+                        />
+                    </div>
+                </CardContent>
+            </Card>
+
+            {/* Custom CSS */}
+            <Card>
+                <CardHeader>
+                    <CardTitle>Custom CSS</CardTitle>
+                    <CardDescription>Add custom styles (advanced)</CardDescription>
+                </CardHeader>
+                <CardContent>
+                    <Textarea
+                        value={form.customCss}
+                        onChange={(e) => setForm({ ...form, customCss: e.target.value })}
+                        placeholder=".hero { background: linear-gradient(...); }"
+                        rows={5}
+                        className="font-mono text-sm"
+                    />
+                </CardContent>
+            </Card>
+
+            {/* Save */}
+            <div className="flex justify-end pt-4">
+                <Button onClick={handleSave} size="lg">
+                    {saved ? <Check className="mr-2 h-4 w-4" /> : <Save className="mr-2 h-4 w-4" />}
+                    {saved ? 'Saved!' : 'Save Settings'}
+                </Button>
+            </div>
+        </div>
+    );
+}
+
+// ── Section Tab ─────────────────────────────────────────────────────────────
+
+function SectionTab({
+    slotConfig,
+    pageId,
+    section,
+    features,
+    actions,
+    onCreateSection,
+    onUpdateSection,
+    onToggleSection,
+    onDeleteSection,
+    onRefresh,
+}: {
+    slotConfig: SlotConfig;
+    pageId: string;
+    section: PageSectionRow | null;
+    features: PageFeatureRow[];
+    actions: PageActionRow[];
+    onCreateSection: () => void;
+    onUpdateSection: (data: Partial<PageSectionRow>) => void;
+    onToggleSection: () => void;
+    onDeleteSection: () => void;
+    onRefresh: () => void;
+}) {
+    const createFeature = pageFeatureHooks.useCreate();
+    const deleteFeature = pageFeatureHooks.useDelete();
+    const createAction = pageActionHooks.useCreate();
+    const deleteAction = pageActionHooks.useDelete();
+
+    const [form, setForm] = useState({
+        title: section?.title || '',
+        subtitle: section?.subtitle || '',
+        body: section?.body || '',
+        icon: section?.icon || '',
+        githubUrl: section?.githubUrl || '',
+        variant: section?.variant || slotConfig.defaultVariant,
+    });
+
+    const [newFeature, setNewFeature] = useState({ title: '', description: '', icon: '' });
+    const [newAction, setNewAction] = useState({ label: '', href: '', variant: 'default', icon: '' });
+    const [saved, setSaved] = useState(false);
+
+    useEffect(() => {
+        if (section) {
+            setForm({
+                title: section.title || '',
+                subtitle: section.subtitle || '',
+                body: section.body || '',
+                icon: section.icon || '',
+                githubUrl: section.githubUrl || '',
+                variant: section.variant || slotConfig.defaultVariant,
+            });
+        }
+    }, [section, slotConfig.defaultVariant]);
+
+    const handleSave = () => {
+        onUpdateSection(form);
+        setSaved(true);
+        setTimeout(() => setSaved(false), 2000);
+    };
+
+    const handleAddFeature = async () => {
+        if (!newFeature.title.trim() || !section) return;
+        await createFeature.mutateAsync({
+            sectionId: section.id,
+            title: newFeature.title.trim(),
+            description: newFeature.description.trim(),
+            icon: newFeature.icon.trim() || undefined,
+            sortOrder: features.length,
+        });
+        setNewFeature({ title: '', description: '', icon: '' });
+        onRefresh();
+    };
+
+    const handleAddAction = async () => {
+        if (!newAction.label.trim() || !newAction.href.trim() || !section) return;
+        await createAction.mutateAsync({
+            sectionId: section.id,
+            label: newAction.label.trim(),
+            href: newAction.href.trim(),
+            variant: newAction.variant,
+            icon: newAction.icon.trim() || undefined,
+            sortOrder: actions.length,
+        });
+        setNewAction({ label: '', href: '', variant: 'default', icon: '' });
+        onRefresh();
+    };
+
+    const SlotIcon = slotConfig.icon;
+
+    // Section not created yet
+    if (!section) {
+        return (
+            <div className="flex flex-col items-center justify-center py-16 text-center">
+                <div className="w-16 h-16 rounded-full bg-muted flex items-center justify-center mb-4">
+                    <SlotIcon className="h-8 w-8 text-muted-foreground" />
+                </div>
+                <h3 className="text-lg font-medium mb-2">{slotConfig.label} Section</h3>
+                <p className="text-muted-foreground mb-6 max-w-md">{slotConfig.description}</p>
+                <Button onClick={onCreateSection}>
+                    <Plus className="mr-2 h-4 w-4" />
+                    Create {slotConfig.label} Section
+                </Button>
+            </div>
+        );
+    }
+
+    return (
+        <div className="space-y-6">
+            {/* Header with toggle */}
+            <div className="flex items-center justify-between">
+                <div className="flex items-center gap-3">
+                    <div
+                        className={`w-10 h-10 rounded-lg flex items-center justify-center ${section.enabled ? 'bg-primary/10' : 'bg-muted'}`}
+                    >
+                        <SlotIcon className={`h-5 w-5 ${section.enabled ? 'text-primary' : 'text-muted-foreground'}`} />
+                    </div>
+                    <div>
+                        <h3 className="font-medium">{slotConfig.label} Section</h3>
+                        <p className="text-sm text-muted-foreground">
+                            {section.enabled ? 'Visible on page' : 'Hidden from page'}
+                        </p>
+                    </div>
+                </div>
+                <div className="flex items-center gap-4">
+                    <div className="flex items-center gap-2">
+                        <Label htmlFor="enabled" className="text-sm">
+                            Enabled
+                        </Label>
+                        <Switch id="enabled" checked={section.enabled} onCheckedChange={onToggleSection} />
+                    </div>
+                    <Button
+                        variant="ghost"
+                        size="sm"
+                        className="text-destructive hover:text-destructive"
+                        onClick={onDeleteSection}
+                    >
+                        <Trash2 className="h-4 w-4" />
+                    </Button>
+                </div>
+            </div>
+
+            <Separator />
+
+            {/* Content Fields */}
+            <div className="grid gap-6 md:grid-cols-2">
+                <div className="space-y-2">
+                    <Label>Title</Label>
+                    <Input
+                        value={form.title}
+                        onChange={(e) => setForm({ ...form, title: e.target.value })}
+                        placeholder="Section title"
+                    />
+                </div>
+                <div className="space-y-2">
+                    <Label>Icon (Lucide name)</Label>
+                    <Input
+                        value={form.icon}
+                        onChange={(e) => setForm({ ...form, icon: e.target.value })}
+                        placeholder="e.g. Sparkles, Zap"
+                    />
+                </div>
+            </div>
+
+            <div className="space-y-2">
+                <Label>Subtitle</Label>
+                <Input
+                    value={form.subtitle}
+                    onChange={(e) => setForm({ ...form, subtitle: e.target.value })}
+                    placeholder="A short tagline or description"
+                />
+            </div>
+
+            <div className="space-y-2">
+                <Label>Body Content</Label>
+                <Textarea
+                    value={form.body}
+                    onChange={(e) => setForm({ ...form, body: e.target.value })}
+                    rows={4}
+                    placeholder="Main content for this section (supports markdown)"
+                />
+            </div>
+
+            {slotConfig.id === 'navbar' && (
+                <div className="space-y-2">
+                    <Label>GitHub URL</Label>
+                    <Input
+                        value={form.githubUrl}
+                        onChange={(e) => setForm({ ...form, githubUrl: e.target.value })}
+                        placeholder="https://github.com/your-org/your-repo"
+                    />
+                </div>
+            )}
+
+            {/* Features */}
+            {slotConfig.supportsFeatures && (
+                <Card>
+                    <CardHeader>
+                        <CardTitle className="text-base">Features</CardTitle>
+                        <CardDescription>Items displayed in this section</CardDescription>
+                    </CardHeader>
+                    <CardContent className="space-y-4">
+                        {features.length > 0 && (
+                            <div className="space-y-2">
+                                {features.map((f) => (
+                                    <div
+                                        key={f.id}
+                                        className="flex items-center gap-3 p-3 rounded-lg border bg-muted/30"
+                                    >
+                                        {f.icon && <Badge variant="secondary">{f.icon}</Badge>}
+                                        <div className="flex-1 min-w-0">
+                                            <p className="font-medium text-sm">{f.title}</p>
+                                            {f.description && (
+                                                <p className="text-xs text-muted-foreground truncate">
+                                                    {f.description}
+                                                </p>
+                                            )}
+                                        </div>
+                                        <Button
+                                            variant="ghost"
+                                            size="icon"
+                                            className="h-8 w-8 shrink-0"
+                                            onClick={async () => {
+                                                await deleteFeature.mutateAsync(f.id);
+                                                onRefresh();
+                                            }}
+                                        >
+                                            <Trash2 className="h-4 w-4 text-destructive" />
+                                        </Button>
+                                    </div>
+                                ))}
+                            </div>
+                        )}
+                        <Separator />
+                        <div className="space-y-3">
+                            <Label className="text-sm">Add Feature</Label>
+                            <div className="grid gap-3 md:grid-cols-3">
+                                <Input
+                                    placeholder="Title"
+                                    value={newFeature.title}
+                                    onChange={(e) => setNewFeature({ ...newFeature, title: e.target.value })}
+                                />
+                                <Input
+                                    placeholder="Description"
+                                    value={newFeature.description}
+                                    onChange={(e) => setNewFeature({ ...newFeature, description: e.target.value })}
+                                />
+                                <div className="flex gap-2">
+                                    <Input
+                                        placeholder="Icon"
+                                        value={newFeature.icon}
+                                        onChange={(e) => setNewFeature({ ...newFeature, icon: e.target.value })}
+                                        className="flex-1"
+                                    />
+                                    <Button onClick={handleAddFeature} disabled={!newFeature.title.trim()}>
+                                        <Plus className="h-4 w-4" />
+                                    </Button>
+                                </div>
+                            </div>
+                        </div>
+                    </CardContent>
+                </Card>
+            )}
+
+            {/* Actions */}
+            {slotConfig.supportsActions && (
+                <Card>
+                    <CardHeader>
+                        <CardTitle className="text-base">Buttons / Actions</CardTitle>
+                        <CardDescription>Call-to-action buttons in this section</CardDescription>
+                    </CardHeader>
+                    <CardContent className="space-y-4">
+                        {actions.length > 0 && (
+                            <div className="space-y-2">
+                                {actions.map((a) => (
+                                    <div
+                                        key={a.id}
+                                        className="flex items-center gap-3 p-3 rounded-lg border bg-muted/30"
+                                    >
+                                        <Badge variant="outline">{a.variant || 'default'}</Badge>
+                                        <div className="flex-1 min-w-0">
+                                            <p className="font-medium text-sm">{a.label}</p>
+                                            <p className="text-xs text-muted-foreground truncate">{a.href}</p>
+                                        </div>
+                                        <Button
+                                            variant="ghost"
+                                            size="icon"
+                                            className="h-8 w-8 shrink-0"
+                                            onClick={async () => {
+                                                await deleteAction.mutateAsync(a.id);
+                                                onRefresh();
+                                            }}
+                                        >
+                                            <Trash2 className="h-4 w-4 text-destructive" />
+                                        </Button>
+                                    </div>
+                                ))}
+                            </div>
+                        )}
+                        <Separator />
+                        <div className="space-y-3">
+                            <Label className="text-sm">Add Button</Label>
+                            <div className="grid gap-3 md:grid-cols-4">
+                                <Input
+                                    placeholder="Label"
+                                    value={newAction.label}
+                                    onChange={(e) => setNewAction({ ...newAction, label: e.target.value })}
+                                />
+                                <Input
+                                    placeholder="URL (e.g. /docs)"
+                                    value={newAction.href}
+                                    onChange={(e) => setNewAction({ ...newAction, href: e.target.value })}
+                                />
+                                <Select
+                                    value={newAction.variant}
+                                    onValueChange={(v) => setNewAction({ ...newAction, variant: v })}
+                                >
+                                    <SelectTrigger>
+                                        <SelectValue />
+                                    </SelectTrigger>
+                                    <SelectContent>
+                                        {ACTION_VARIANTS.map((v) => (
+                                            <SelectItem key={v.value} value={v.value}>
+                                                {v.label}
+                                            </SelectItem>
+                                        ))}
+                                    </SelectContent>
+                                </Select>
+                                <Button
+                                    onClick={handleAddAction}
+                                    disabled={!newAction.label.trim() || !newAction.href.trim()}
+                                >
+                                    <Plus className="h-4 w-4" />
+                                </Button>
+                            </div>
+                        </div>
+                    </CardContent>
+                </Card>
+            )}
+
+            {/* Save */}
+            <div className="flex justify-end pt-4">
+                <Button onClick={handleSave} size="lg">
+                    {saved ? <Check className="mr-2 h-4 w-4" /> : <Save className="mr-2 h-4 w-4" />}
+                    {saved ? 'Saved!' : 'Save Changes'}
+                </Button>
+            </div>
+        </div>
+    );
+}
+
+// ── Main Page Builder ───────────────────────────────────────────────────────
+
+export function AdminPageBuilderPage() {
+    const { pageId } = useParams({ from: '/admin/pages/$pageId' });
+
+    // Data hooks
+    const { data: pageData, isLoading: pageLoading, refetch: refetchPage } = pageHooks.useDetail(pageId);
+    const { data: sectionsData, refetch: refetchSections } = pageSectionHooks.useList(
+        { where: { pageId }, orderBy: 'sortOrder', orderDirection: 'asc' },
+        ADMIN_LIST_QUERY_CONFIG,
+    );
+    const { data: featuresData, refetch: refetchFeatures } = pageFeatureHooks.useList(
+        { orderBy: 'sortOrder', orderDirection: 'asc' },
+        ADMIN_LIST_QUERY_CONFIG,
+    );
+    const { data: actionsData, refetch: refetchActions } = pageActionHooks.useList(
+        { orderBy: 'sortOrder', orderDirection: 'asc' },
+        ADMIN_LIST_QUERY_CONFIG,
+    );
+
+    const updatePage = pageHooks.useUpdate();
+    const createSection = pageSectionHooks.useCreate();
+    const updateSection = pageSectionHooks.useUpdate();
+    const deleteSection = pageSectionHooks.useDelete();
+
+    // Type-safe data
+    const page = pageData as PageRow | undefined;
+    const sections = useMemo(() => {
+        const data = (Array.isArray(sectionsData) ? sectionsData : []) as PageSectionRow[];
+        return data.filter((s) => s.pageId === pageId);
+    }, [sectionsData, pageId]);
+    const features = useMemo(
+        () => (Array.isArray(featuresData) ? featuresData : []) as PageFeatureRow[],
+        [featuresData],
+    );
+    const actions = useMemo(() => (Array.isArray(actionsData) ? actionsData : []) as PageActionRow[], [actionsData]);
+
+    // Lookup maps
+    const sectionBySlot = useMemo(() => {
+        const map: Record<string, PageSectionRow> = {};
+        for (const s of sections) map[s.slot] = s;
+        return map;
+    }, [sections]);
+
+    const featuresBySectionId = useMemo(() => {
+        const map: Record<string, PageFeatureRow[]> = {};
+        for (const f of features) {
+            if (!map[f.sectionId]) map[f.sectionId] = [];
+            map[f.sectionId].push(f);
+        }
+        return map;
+    }, [features]);
+
+    const actionsBySectionId = useMemo(() => {
+        const map: Record<string, PageActionRow[]> = {};
+        for (const a of actions) {
+            if (!map[a.sectionId]) map[a.sectionId] = [];
+            map[a.sectionId].push(a);
+        }
+        return map;
+    }, [actions]);
+
+    // Refresh
+    const handleRefresh = useCallback(() => {
+        refetchSections();
+        refetchFeatures();
+        refetchActions();
+    }, [refetchSections, refetchFeatures, refetchActions]);
+
+    // Page update
+    const handleUpdatePage = async (data: Partial<PageRow>) => {
+        await updatePage.mutateAsync({ id: pageId, data });
+        refetchPage();
+    };
+
+    // Section CRUD
+    const handleCreateSection = async (slotId: string) => {
+        const slotConfig = getSlotConfig(slotId);
+        await createSection.mutateAsync({
+            pageId,
+            slot: slotId,
+            title: slotConfig?.label ?? slotId,
+            variant: slotConfig?.defaultVariant ?? 'default',
+            enabled: true,
+            sortOrder: sections.length,
+        });
+        handleRefresh();
+    };
+
+    const handleUpdateSection = async (id: string, data: Partial<PageSectionRow>) => {
+        await updateSection.mutateAsync({ id, data });
+        handleRefresh();
+    };
+
+    const handleToggleSection = async (section: PageSectionRow) => {
+        await updateSection.mutateAsync({ id: section.id, data: { enabled: !section.enabled } });
+        handleRefresh();
+    };
+
+    const handleDeleteSection = async (section: PageSectionRow) => {
+        if (!confirm(`Delete "${section.title || section.slot}" section?`)) return;
+        await deleteSection.mutateAsync(section.id);
+        handleRefresh();
+    };
+
+    if (pageLoading || !page) {
+        return (
+            <div className="flex items-center justify-center min-h-[400px]">
+                <div className="text-muted-foreground">Loading...</div>
+            </div>
+        );
+    }
+
+    return (
+        <div className="min-h-screen">
+            {/* Header */}
+            <div className="border-b bg-background/95 backdrop-blur supports-[backdrop-filter]:bg-background/60">
+                <div className="flex items-center justify-between px-6 py-4">
+                    <div className="flex items-center gap-3">
+                        <Link to="/admin/pages" className="p-2 rounded-lg hover:bg-muted">
+                            <ArrowLeft className="h-5 w-5" />
+                        </Link>
+                        <div>
+                            <h1 className="text-xl font-semibold">{page.title}</h1>
+                            <p className="text-sm text-muted-foreground">/{page.slug}</p>
+                        </div>
+                        <Badge variant={page.status === 'published' ? 'default' : 'secondary'}>{page.status}</Badge>
+                    </div>
+                    <a
+                        href={`${import.meta.env.VITE_HOMEPAGE_URL || 'http://localhost:3000'}/${page.slug === 'homepage' ? '' : page.slug}`}
+                        target="_blank"
+                        rel="noopener noreferrer"
+                    >
+                        <Button variant="outline">
+                            <ExternalLink className="mr-2 h-4 w-4" />
+                            Preview
+                        </Button>
+                    </a>
+                </div>
+            </div>
+
+            {/* Tabs */}
+            <Tabs defaultValue="settings" className="w-full">
+                <div className="border-b px-6 overflow-x-auto">
+                    <TabsList className="h-12 bg-transparent gap-2 flex-nowrap">
+                        <TabsTrigger value="settings" className="data-[state=active]:bg-muted gap-2">
+                            <Settings className="h-4 w-4" />
+                            Settings
+                        </TabsTrigger>
+                        {SLOT_TYPES.map((type) => {
+                            const section = sectionBySlot[type.id];
+                            return (
+                                <TabsTrigger
+                                    key={type.id}
+                                    value={type.id}
+                                    className="data-[state=active]:bg-muted gap-2 whitespace-nowrap"
+                                >
+                                    <type.icon className="h-4 w-4" />
+                                    {type.label}
+                                    {section && (
+                                        <span
+                                            className={`w-2 h-2 rounded-full ${section.enabled ? 'bg-green-500' : 'bg-muted-foreground/30'}`}
+                                        />
+                                    )}
+                                </TabsTrigger>
+                            );
+                        })}
+                    </TabsList>
+                </div>
+
+                <div className="p-6 max-w-4xl mx-auto">
+                    <TabsContent value="settings" className="mt-0">
+                        <SettingsTab page={page} onSave={handleUpdatePage} />
+                    </TabsContent>
+
+                    {SLOT_TYPES.map((type) => {
+                        const section = sectionBySlot[type.id] ?? null;
+                        const sectionFeatures = section ? (featuresBySectionId[section.id] ?? []) : [];
+                        const sectionActions = section ? (actionsBySectionId[section.id] ?? []) : [];
+
+                        return (
+                            <TabsContent key={type.id} value={type.id} className="mt-0">
+                                <SectionTab
+                                    slotConfig={type}
+                                    pageId={pageId}
+                                    section={section}
+                                    features={sectionFeatures}
+                                    actions={sectionActions}
+                                    onCreateSection={() => handleCreateSection(type.id)}
+                                    onUpdateSection={(data) => section && handleUpdateSection(section.id, data)}
+                                    onToggleSection={() => section && handleToggleSection(section)}
+                                    onDeleteSection={() => section && handleDeleteSection(section)}
+                                    onRefresh={handleRefresh}
+                                />
+                            </TabsContent>
+                        );
+                    })}
+                </div>
+            </Tabs>
+        </div>
+    );
+}
diff --git a/apps/ottabase-template-app-tanstack/src/pages/admin/pages/AdminPagesListPage.tsx b/apps/ottabase-template-app-tanstack/src/pages/admin/pages/AdminPagesListPage.tsx
new file mode 100644
index 000000000..e58162e50
--- /dev/null
+++ b/apps/ottabase-template-app-tanstack/src/pages/admin/pages/AdminPagesListPage.tsx
@@ -0,0 +1,299 @@
+/**
+ * Marketing Pages List
+ *
+ * Lists all marketing pages with ability to create, edit, and delete.
+ * Follows Notion/GitHub-style minimal design.
+ */
+import { ADMIN_LIST_QUERY_CONFIG } from '@/config/queryConfig';
+import { pageHooks, type PageRow } from '@/hooks/pageHooks';
+import {
+    Badge,
+    Button,
+    Card,
+    DropdownMenu,
+    DropdownMenuContent,
+    DropdownMenuItem,
+    DropdownMenuSeparator,
+    DropdownMenuTrigger,
+    Input,
+} from '@ottabase/ui-shadcn';
+import { Link, useNavigate } from '@tanstack/react-router';
+import {
+    Copy,
+    Edit,
+    ExternalLink,
+    LayoutDashboard,
+    LayoutGrid,
+    MoreVertical,
+    Plus,
+    Search,
+    Trash2,
+} from 'lucide-react';
+import { useMemo, useState } from 'react';
+
+// ── Page Row Component ──────────────────────────────────────────────────────
+
+function PageListItem({
+    page,
+    onDelete,
+    onDuplicate,
+}: {
+    page: PageRow;
+    onDelete: (page: PageRow) => void;
+    onDuplicate: (page: PageRow) => void;
+}) {
+    const navigate = useNavigate();
+
+    const statusColors = {
+        draft: 'bg-amber-500/10 text-amber-600 border-amber-200 dark:border-amber-800',
+        published: 'bg-emerald-500/10 text-emerald-600 border-emerald-200 dark:border-emerald-800',
+        archived: 'bg-zinc-500/10 text-zinc-600 border-zinc-200 dark:border-zinc-800',
+    };
+
+    const typeIcon = page.type === 'block' ? LayoutGrid : LayoutDashboard;
+    const TypeIcon = typeIcon;
+
+    return (
+        <div className="group flex items-center gap-4 px-4 py-3 hover:bg-muted/50 rounded-lg transition-colors">
+            {/* Icon */}
+            <div className="w-10 h-10 rounded-lg bg-muted flex items-center justify-center shrink-0">
+                <TypeIcon className="h-5 w-5 text-muted-foreground" />
+            </div>
+
+            {/* Info */}
+            <div className="flex-1 min-w-0">
+                <div className="flex items-center gap-2">
+                    <span className="font-medium truncate">{page.title}</span>
+                    {page.slug === 'homepage' && (
+                        <Badge variant="secondary" className="text-xs">
+                            Homepage
+                        </Badge>
+                    )}
+                </div>
+                <div className="flex items-center gap-2 text-sm text-muted-foreground">
+                    <span>/{page.slug}</span>
+                    {page.showInNav && (
+                        <>
+                            <span>•</span>
+                            <span>In nav</span>
+                        </>
+                    )}
+                </div>
+            </div>
+
+            {/* Status badge */}
+            <Badge variant="outline" className={statusColors[page.status]}>
+                {page.status}
+            </Badge>
+
+            {/* Type badge */}
+            <Badge variant="outline" className="capitalize">
+                {page.type}
+            </Badge>
+
+            {/* Actions */}
+            <div className="flex items-center gap-1 opacity-0 group-hover:opacity-100 transition-opacity">
+                <Button
+                    variant="ghost"
+                    size="icon"
+                    className="h-8 w-8"
+                    onClick={() => navigate({ to: '/admin/pages/$pageId', params: { pageId: page.id } })}
+                >
+                    <Edit className="h-4 w-4" />
+                </Button>
+                <DropdownMenu>
+                    <DropdownMenuTrigger asChild>
+                        <Button variant="ghost" size="icon" className="h-8 w-8">
+                            <MoreVertical className="h-4 w-4" />
+                        </Button>
+                    </DropdownMenuTrigger>
+                    <DropdownMenuContent align="end">
+                        <DropdownMenuItem asChild>
+                            <Link to="/admin/pages/$pageId" params={{ pageId: page.id }}>
+                                <Edit className="mr-2 h-4 w-4" />
+                                Edit
+                            </Link>
+                        </DropdownMenuItem>
+                        <DropdownMenuItem onClick={() => onDuplicate(page)}>
+                            <Copy className="mr-2 h-4 w-4" />
+                            Duplicate
+                        </DropdownMenuItem>
+                        <DropdownMenuSeparator />
+                        <DropdownMenuItem asChild>
+                            <a
+                                href={`${import.meta.env.VITE_HOMEPAGE_URL || 'http://localhost:3000'}/${page.slug === 'homepage' ? '' : page.slug}`}
+                                target="_blank"
+                                rel="noopener noreferrer"
+                            >
+                                <ExternalLink className="mr-2 h-4 w-4" />
+                                View Live
+                            </a>
+                        </DropdownMenuItem>
+                        <DropdownMenuSeparator />
+                        <DropdownMenuItem
+                            className="text-destructive focus:text-destructive"
+                            onClick={() => onDelete(page)}
+                        >
+                            <Trash2 className="mr-2 h-4 w-4" />
+                            Delete
+                        </DropdownMenuItem>
+                    </DropdownMenuContent>
+                </DropdownMenu>
+            </div>
+        </div>
+    );
+}
+
+// ── Main List Page ──────────────────────────────────────────────────────────
+
+export function AdminPagesListPage() {
+    const navigate = useNavigate();
+    const [search, setSearch] = useState('');
+
+    // Fetch pages
+    const {
+        data: pagesData,
+        isLoading,
+        refetch,
+    } = pageHooks.useList({ orderBy: 'createdAt', orderDirection: 'desc' }, ADMIN_LIST_QUERY_CONFIG);
+
+    const createPage = pageHooks.useCreate();
+    const deletePage = pageHooks.useDelete();
+
+    const pages = useMemo(() => {
+        const list = (Array.isArray(pagesData) ? pagesData : []) as PageRow[];
+        if (!search.trim()) return list;
+        const q = search.toLowerCase();
+        return list.filter((p) => p.title.toLowerCase().includes(q) || p.slug.toLowerCase().includes(q));
+    }, [pagesData, search]);
+
+    const handleCreatePage = async () => {
+        const slug = `page-${Date.now()}`;
+        const newPage = await createPage.mutateAsync({
+            slug,
+            title: 'New Page',
+            type: 'block',
+            status: 'draft',
+        });
+        refetch();
+        // Navigate to editor after creation
+        if (newPage && typeof newPage === 'object' && 'id' in newPage) {
+            navigate({ to: '/admin/pages/$pageId', params: { pageId: (newPage as PageRow).id } });
+        }
+    };
+
+    const handleDuplicate = async (page: PageRow) => {
+        const newSlug = `${page.slug}-copy-${Date.now()}`;
+        await createPage.mutateAsync({
+            slug: newSlug,
+            title: `${page.title} (Copy)`,
+            type: page.type,
+            status: 'draft',
+            themePreset: page.themePreset,
+            variantBySlotJson: page.variantBySlotJson,
+        });
+        refetch();
+    };
+
+    const handleDelete = async (page: PageRow) => {
+        if (page.slug === 'homepage') {
+            alert('Cannot delete the homepage. Edit it instead.');
+            return;
+        }
+        if (!confirm(`Delete "${page.title}"? This action cannot be undone.`)) return;
+        await deletePage.mutateAsync(page.id);
+        refetch();
+    };
+
+    const handleSeed = async () => {
+        const res = await fetch('/api/pages/seed', { method: 'POST' });
+        if (res.ok) refetch();
+    };
+
+    if (isLoading) {
+        return (
+            <div className="flex items-center justify-center min-h-[400px]">
+                <div className="text-muted-foreground">Loading...</div>
+            </div>
+        );
+    }
+
+    return (
+        <div className="min-h-screen">
+            {/* Header */}
+            <div className="border-b bg-background/95 backdrop-blur supports-[backdrop-filter]:bg-background/60">
+                <div className="flex items-center justify-between px-6 py-4">
+                    <div className="flex items-center gap-3">
+                        <div className="w-10 h-10 rounded-lg bg-primary/10 flex items-center justify-center">
+                            <LayoutDashboard className="h-5 w-5 text-primary" />
+                        </div>
+                        <div>
+                            <h1 className="text-xl font-semibold">Marketing Pages</h1>
+                            <p className="text-sm text-muted-foreground">
+                                {pages.length} page{pages.length !== 1 ? 's' : ''}
+                            </p>
+                        </div>
+                    </div>
+                    <div className="flex items-center gap-2">
+                        {pages.length === 0 && (
+                            <Button variant="outline" onClick={handleSeed}>
+                                Seed Demo
+                            </Button>
+                        )}
+                        <Button onClick={handleCreatePage}>
+                            <Plus className="mr-2 h-4 w-4" />
+                            New Page
+                        </Button>
+                    </div>
+                </div>
+            </div>
+
+            {/* Content */}
+            <div className="p-6 max-w-4xl mx-auto space-y-4">
+                {/* Search */}
+                <div className="relative">
+                    <Search className="absolute left-3 top-1/2 -translate-y-1/2 h-4 w-4 text-muted-foreground" />
+                    <Input
+                        placeholder="Search pages..."
+                        value={search}
+                        onChange={(e) => setSearch(e.target.value)}
+                        className="pl-10"
+                    />
+                </div>
+
+                {/* Pages list */}
+                {pages.length === 0 ? (
+                    <Card className="p-12 text-center">
+                        <div className="w-16 h-16 rounded-full bg-muted flex items-center justify-center mx-auto mb-4">
+                            <LayoutDashboard className="h-8 w-8 text-muted-foreground" />
+                        </div>
+                        <h3 className="text-lg font-medium mb-2">No marketing pages yet</h3>
+                        <p className="text-muted-foreground mb-6">
+                            Create your first marketing page or seed the homepage to get started.
+                        </p>
+                        <div className="flex items-center justify-center gap-3">
+                            <Button variant="outline" onClick={handleSeed}>
+                                Seed Homepage
+                            </Button>
+                            <Button onClick={handleCreatePage}>
+                                <Plus className="mr-2 h-4 w-4" />
+                                Create Page
+                            </Button>
+                        </div>
+                    </Card>
+                ) : (
+                    <Card className="divide-y">
+                        {pages.map((page) => (
+                            <PageListItem
+                                key={page.id}
+                                page={page}
+                                onDelete={handleDelete}
+                                onDuplicate={handleDuplicate}
+                            />
+                        ))}
+                    </Card>
+                )}
+            </div>
+        </div>
+    );
+}
diff --git a/apps/ottabase-template-app-tanstack/src/pages/admin/pages/MarketingPageBuilder.tsx b/apps/ottabase-template-app-tanstack/src/pages/admin/pages/MarketingPageBuilder.tsx
new file mode 100644
index 000000000..db0ad998b
--- /dev/null
+++ b/apps/ottabase-template-app-tanstack/src/pages/admin/pages/MarketingPageBuilder.tsx
@@ -0,0 +1,1253 @@
+/**
+ * Marketing Page Builder
+ *
+ * Drag-and-drop page builder for creating marketing pages.
+ * - Left sidebar: Block palette with draggable block types
+ * - Center: Canvas with sortable blocks
+ * - Right panel: Block editor when a block is selected
+ */
+import { ADMIN_LIST_QUERY_CONFIG } from '@/config/queryConfig';
+import {
+    pageActionHooks,
+    pageFeatureHooks,
+    pageHooks,
+    pageSectionHooks,
+    type PageActionRow,
+    type PageFeatureRow,
+    type PageRow,
+    type PageSectionRow,
+} from '@/hooks/pageHooks';
+import {
+    closestCenter,
+    DndContext,
+    DragEndEvent,
+    DragOverlay,
+    DragStartEvent,
+    MouseSensor,
+    TouchSensor,
+    useSensor,
+    useSensors,
+} from '@dnd-kit/core';
+import { arrayMove, SortableContext, useSortable, verticalListSortingStrategy } from '@dnd-kit/sortable';
+import { CSS } from '@dnd-kit/utilities';
+import {
+    Badge,
+    Button,
+    Card,
+    CardContent,
+    CardHeader,
+    CardTitle,
+    Dialog,
+    DialogContent,
+    DialogDescription,
+    DialogHeader,
+    DialogTitle,
+    Input,
+    Label,
+    ScrollArea,
+    Select,
+    SelectContent,
+    SelectItem,
+    SelectTrigger,
+    SelectValue,
+    Separator,
+    Sheet,
+    SheetContent,
+    SheetDescription,
+    SheetHeader,
+    SheetTitle,
+    Switch,
+    Textarea,
+    Tooltip,
+    TooltipContent,
+    TooltipProvider,
+    TooltipTrigger,
+} from '@ottabase/ui-shadcn';
+import { Link, useParams } from '@tanstack/react-router';
+import {
+    ArrowLeft,
+    Check,
+    ChevronRight,
+    ExternalLink,
+    Eye,
+    EyeOff,
+    GripVertical,
+    Palette,
+    Plus,
+    Save,
+    Settings,
+    Trash2,
+} from 'lucide-react';
+import { useCallback, useEffect, useMemo, useState } from 'react';
+import {
+    ACTION_VARIANTS,
+    BLOCK_TYPES,
+    getBlockVariants,
+    getSlotConfig,
+    PAGE_STATUS_OPTIONS,
+    THEME_PRESETS,
+    type SlotConfig,
+} from './pages-constants';
+
+// ── Types ───────────────────────────────────────────────────────────────────
+
+interface BlockWithData extends PageSectionRow {
+    features: PageFeatureRow[];
+    actions: PageActionRow[];
+}
+
+// ── Block Palette Item ──────────────────────────────────────────────────────
+
+function PaletteItem({
+    config,
+    onAdd,
+    disabled,
+}: {
+    config: SlotConfig;
+    onAdd: (blockType: string) => void;
+    disabled?: boolean;
+}) {
+    const Icon = config.icon;
+
+    return (
+        <TooltipProvider>
+            <Tooltip>
+                <TooltipTrigger asChild>
+                    <button
+                        type="button"
+                        onClick={() => onAdd(config.id)}
+                        disabled={disabled}
+                        className={`
+                            w-full flex items-center gap-3 p-3 rounded-lg border text-left
+                            transition-all group
+                            ${disabled ? 'opacity-50 cursor-not-allowed bg-muted/50' : 'hover:bg-accent hover:border-accent-foreground/20 cursor-grab active:cursor-grabbing'}
+                        `}
+                    >
+                        <div className="w-8 h-8 rounded-md bg-primary/10 flex items-center justify-center shrink-0 group-hover:bg-primary/20">
+                            <Icon className="h-4 w-4 text-primary" />
+                        </div>
+                        <div className="min-w-0 flex-1">
+                            <p className="font-medium text-sm truncate">{config.label}</p>
+                            <p className="text-xs text-muted-foreground truncate">{config.description}</p>
+                        </div>
+                        <Plus className="h-4 w-4 text-muted-foreground opacity-0 group-hover:opacity-100 transition-opacity" />
+                    </button>
+                </TooltipTrigger>
+                <TooltipContent side="right">
+                    <p>Click to add {config.label}</p>
+                </TooltipContent>
+            </Tooltip>
+        </TooltipProvider>
+    );
+}
+
+// ── Block Palette ───────────────────────────────────────────────────────────
+
+function BlockPalette({
+    onAddBlock,
+    existingBlocks,
+}: {
+    onAddBlock: (blockType: string) => void;
+    existingBlocks: string[];
+}) {
+    // Group blocks by category
+    const navigation = BLOCK_TYPES.filter((b) => ['navbar', 'footer'].includes(b.id));
+    const hero = BLOCK_TYPES.filter((b) => ['hero', 'cta'].includes(b.id));
+    const content = BLOCK_TYPES.filter((b) =>
+        ['features', 'about', 'testimonials', 'gallery', 'team', 'pricing', 'faq', 'video', 'code', 'custom'].includes(
+            b.id,
+        ),
+    );
+
+    // Some blocks should only appear once (navbar, footer)
+    const singleUseBlocks = ['navbar', 'footer'];
+
+    const isDisabled = (blockId: string) => {
+        return singleUseBlocks.includes(blockId) && existingBlocks.includes(blockId);
+    };
+
+    return (
+        <div className="w-72 border-r bg-muted/30 flex flex-col h-full">
+            <div className="p-4 border-b">
+                <h2 className="font-semibold">Blocks</h2>
+                <p className="text-xs text-muted-foreground mt-1">Click to add blocks to your page</p>
+            </div>
+            <ScrollArea className="flex-1 p-4">
+                <div className="space-y-6">
+                    <div>
+                        <h3 className="text-xs font-medium text-muted-foreground uppercase tracking-wider mb-2">
+                            Navigation
+                        </h3>
+                        <div className="space-y-2">
+                            {navigation.map((block) => (
+                                <PaletteItem
+                                    key={block.id}
+                                    config={block}
+                                    onAdd={onAddBlock}
+                                    disabled={isDisabled(block.id)}
+                                />
+                            ))}
+                        </div>
+                    </div>
+                    <div>
+                        <h3 className="text-xs font-medium text-muted-foreground uppercase tracking-wider mb-2">
+                            Hero & CTA
+                        </h3>
+                        <div className="space-y-2">
+                            {hero.map((block) => (
+                                <PaletteItem
+                                    key={block.id}
+                                    config={block}
+                                    onAdd={onAddBlock}
+                                    disabled={isDisabled(block.id)}
+                                />
+                            ))}
+                        </div>
+                    </div>
+                    <div>
+                        <h3 className="text-xs font-medium text-muted-foreground uppercase tracking-wider mb-2">
+                            Content
+                        </h3>
+                        <div className="space-y-2">
+                            {content.map((block) => (
+                                <PaletteItem
+                                    key={block.id}
+                                    config={block}
+                                    onAdd={onAddBlock}
+                                    disabled={isDisabled(block.id)}
+                                />
+                            ))}
+                        </div>
+                    </div>
+                </div>
+            </ScrollArea>
+        </div>
+    );
+}
+
+// ── Sortable Canvas Block ───────────────────────────────────────────────────
+
+function SortableBlock({
+    block,
+    config,
+    isSelected,
+    onSelect,
+    onToggle,
+    onDelete,
+}: {
+    block: BlockWithData;
+    config: SlotConfig;
+    isSelected: boolean;
+    onSelect: () => void;
+    onToggle: () => void;
+    onDelete: () => void;
+}) {
+    const { attributes, listeners, setNodeRef, transform, transition, isDragging } = useSortable({
+        id: block.id,
+    });
+
+    const style = {
+        transform: CSS.Transform.toString(transform),
+        transition,
+    };
+
+    const Icon = config.icon;
+
+    return (
+        <div
+            ref={setNodeRef}
+            style={style}
+            className={`
+                group relative border rounded-lg transition-all
+                ${isDragging ? 'opacity-50 shadow-lg' : ''}
+                ${isSelected ? 'ring-2 ring-primary border-primary' : 'hover:border-primary/50'}
+                ${!block.enabled ? 'opacity-60' : ''}
+            `}
+        >
+            <div className="flex items-stretch">
+                {/* Drag Handle */}
+                <button
+                    {...attributes}
+                    {...listeners}
+                    className="px-2 flex items-center justify-center border-r bg-muted/30 hover:bg-muted cursor-grab active:cursor-grabbing"
+                >
+                    <GripVertical className="h-4 w-4 text-muted-foreground" />
+                </button>
+
+                {/* Block Content (clickable to select) */}
+                <button type="button" onClick={onSelect} className="flex-1 flex items-center gap-4 p-4 text-left">
+                    <div
+                        className={`
+                            w-10 h-10 rounded-lg flex items-center justify-center shrink-0
+                            ${block.enabled ? 'bg-primary/10' : 'bg-muted'}
+                        `}
+                    >
+                        <Icon className={`h-5 w-5 ${block.enabled ? 'text-primary' : 'text-muted-foreground'}`} />
+                    </div>
+                    <div className="flex-1 min-w-0">
+                        <div className="flex items-center gap-2">
+                            <span className="font-medium">{block.title || config.label}</span>
+                            {!block.enabled && (
+                                <Badge variant="outline" className="text-xs">
+                                    Hidden
+                                </Badge>
+                            )}
+                        </div>
+                        <p className="text-sm text-muted-foreground truncate">{block.subtitle || config.description}</p>
+                        {/* Stats */}
+                        <div className="flex items-center gap-3 mt-1 text-xs text-muted-foreground">
+                            {config.supportsFeatures && <span>{block.features.length} feature(s)</span>}
+                            {config.supportsActions && <span>{block.actions.length} action(s)</span>}
+                            {block.variant !== 'default' && (
+                                <Badge variant="secondary" className="text-xs">
+                                    {block.variant}
+                                </Badge>
+                            )}
+                        </div>
+                    </div>
+                    <ChevronRight className="h-5 w-5 text-muted-foreground opacity-0 group-hover:opacity-100 transition-opacity" />
+                </button>
+
+                {/* Quick Actions */}
+                <div className="flex items-center gap-1 px-2 border-l bg-muted/20">
+                    <TooltipProvider>
+                        <Tooltip>
+                            <TooltipTrigger asChild>
+                                <Button variant="ghost" size="icon" className="h-8 w-8" onClick={onToggle}>
+                                    {block.enabled ? (
+                                        <Eye className="h-4 w-4" />
+                                    ) : (
+                                        <EyeOff className="h-4 w-4 text-muted-foreground" />
+                                    )}
+                                </Button>
+                            </TooltipTrigger>
+                            <TooltipContent>
+                                <p>{block.enabled ? 'Hide block' : 'Show block'}</p>
+                            </TooltipContent>
+                        </Tooltip>
+                    </TooltipProvider>
+                    <TooltipProvider>
+                        <Tooltip>
+                            <TooltipTrigger asChild>
+                                <Button
+                                    variant="ghost"
+                                    size="icon"
+                                    className="h-8 w-8 text-destructive hover:text-destructive"
+                                    onClick={onDelete}
+                                >
+                                    <Trash2 className="h-4 w-4" />
+                                </Button>
+                            </TooltipTrigger>
+                            <TooltipContent>
+                                <p>Delete block</p>
+                            </TooltipContent>
+                        </Tooltip>
+                    </TooltipProvider>
+                </div>
+            </div>
+        </div>
+    );
+}
+
+// ── Canvas ──────────────────────────────────────────────────────────────────
+
+function Canvas({
+    blocks,
+    selectedBlockId,
+    onSelectBlock,
+    onReorder,
+    onToggleBlock,
+    onDeleteBlock,
+}: {
+    blocks: BlockWithData[];
+    selectedBlockId: string | null;
+    onSelectBlock: (id: string) => void;
+    onReorder: (oldIndex: number, newIndex: number) => void;
+    onToggleBlock: (block: BlockWithData) => void;
+    onDeleteBlock: (block: BlockWithData) => void;
+}) {
+    const [activeId, setActiveId] = useState<string | null>(null);
+
+    const sensors = useSensors(
+        useSensor(MouseSensor, { activationConstraint: { distance: 8 } }),
+        useSensor(TouchSensor, { activationConstraint: { delay: 200, tolerance: 5 } }),
+    );
+
+    const handleDragStart = (event: DragStartEvent) => {
+        setActiveId(event.active.id as string);
+    };
+
+    const handleDragEnd = (event: DragEndEvent) => {
+        const { active, over } = event;
+        setActiveId(null);
+
+        if (over && active.id !== over.id) {
+            const oldIndex = blocks.findIndex((b) => b.id === active.id);
+            const newIndex = blocks.findIndex((b) => b.id === over.id);
+            onReorder(oldIndex, newIndex);
+        }
+    };
+
+    const activeBlock = activeId ? blocks.find((b) => b.id === activeId) : null;
+    const activeConfig = activeBlock ? getSlotConfig(activeBlock.slot) : null;
+
+    return (
+        <div className="flex-1 bg-background overflow-hidden flex flex-col">
+            <div className="border-b p-4 flex items-center justify-between">
+                <div>
+                    <h2 className="font-semibold">Page Layout</h2>
+                    <p className="text-sm text-muted-foreground">
+                        {blocks.length} block{blocks.length !== 1 ? 's' : ''} • Drag to reorder
+                    </p>
+                </div>
+            </div>
+
+            <ScrollArea className="flex-1 p-6">
+                {blocks.length === 0 ? (
+                    <div className="flex flex-col items-center justify-center h-64 text-center">
+                        <div className="w-16 h-16 rounded-full bg-muted flex items-center justify-center mb-4">
+                            <Plus className="h-8 w-8 text-muted-foreground" />
+                        </div>
+                        <h3 className="font-medium mb-2">No blocks yet</h3>
+                        <p className="text-sm text-muted-foreground max-w-sm">
+                            Click blocks from the palette on the left to start building your page.
+                        </p>
+                    </div>
+                ) : (
+                    <DndContext
+                        sensors={sensors}
+                        collisionDetection={closestCenter}
+                        onDragStart={handleDragStart}
+                        onDragEnd={handleDragEnd}
+                    >
+                        <SortableContext items={blocks.map((b) => b.id)} strategy={verticalListSortingStrategy}>
+                            <div className="space-y-3 max-w-3xl mx-auto">
+                                {blocks.map((block) => {
+                                    const config = getSlotConfig(block.slot);
+                                    if (!config) return null;
+                                    return (
+                                        <SortableBlock
+                                            key={block.id}
+                                            block={block}
+                                            config={config}
+                                            isSelected={selectedBlockId === block.id}
+                                            onSelect={() => onSelectBlock(block.id)}
+                                            onToggle={() => onToggleBlock(block)}
+                                            onDelete={() => onDeleteBlock(block)}
+                                        />
+                                    );
+                                })}
+                            </div>
+                        </SortableContext>
+                        <DragOverlay>
+                            {activeBlock && activeConfig && (
+                                <div className="border rounded-lg p-4 bg-background shadow-xl opacity-90">
+                                    <div className="flex items-center gap-3">
+                                        <activeConfig.icon className="h-5 w-5 text-primary" />
+                                        <span className="font-medium">{activeBlock.title || activeConfig.label}</span>
+                                    </div>
+                                </div>
+                            )}
+                        </DragOverlay>
+                    </DndContext>
+                )}
+            </ScrollArea>
+        </div>
+    );
+}
+
+// ── Block Editor Panel ──────────────────────────────────────────────────────
+
+function BlockEditor({
+    block,
+    onUpdate,
+    onClose,
+    onRefresh,
+}: {
+    block: BlockWithData;
+    onUpdate: (data: Partial<PageSectionRow>) => void;
+    onClose: () => void;
+    onRefresh: () => void;
+}) {
+    const config = getSlotConfig(block.slot);
+    const variants = getBlockVariants(block.slot);
+
+    const createFeature = pageFeatureHooks.useCreate();
+    const updateFeature = pageFeatureHooks.useUpdate();
+    const deleteFeature = pageFeatureHooks.useDelete();
+    const createAction = pageActionHooks.useCreate();
+    const updateAction = pageActionHooks.useUpdate();
+    const deleteAction = pageActionHooks.useDelete();
+
+    const [form, setForm] = useState({
+        title: block.title || '',
+        subtitle: block.subtitle || '',
+        body: block.body || '',
+        icon: block.icon || '',
+        imageUrl: block.imageUrl || '',
+        videoUrl: block.videoUrl || '',
+        githubUrl: block.githubUrl || '',
+        variant: block.variant || config?.defaultVariant || 'default',
+    });
+
+    const [newFeature, setNewFeature] = useState({ title: '', description: '', icon: '', imageUrl: '' });
+    const [newAction, setNewAction] = useState({ label: '', href: '', variant: 'default', icon: '' });
+    const [saved, setSaved] = useState(false);
+
+    useEffect(() => {
+        setForm({
+            title: block.title || '',
+            subtitle: block.subtitle || '',
+            body: block.body || '',
+            icon: block.icon || '',
+            imageUrl: block.imageUrl || '',
+            videoUrl: block.videoUrl || '',
+            githubUrl: block.githubUrl || '',
+            variant: block.variant || config?.defaultVariant || 'default',
+        });
+    }, [block, config?.defaultVariant]);
+
+    const handleSave = () => {
+        onUpdate(form);
+        setSaved(true);
+        setTimeout(() => setSaved(false), 2000);
+    };
+
+    const handleAddFeature = async () => {
+        if (!newFeature.title.trim()) return;
+        await createFeature.mutateAsync({
+            sectionId: block.id,
+            title: newFeature.title.trim(),
+            description: newFeature.description.trim() || undefined,
+            icon: newFeature.icon.trim() || undefined,
+            imageUrl: newFeature.imageUrl.trim() || undefined,
+            sortOrder: block.features.length,
+        });
+        setNewFeature({ title: '', description: '', icon: '', imageUrl: '' });
+        onRefresh();
+    };
+
+    const handleDeleteFeature = async (id: string) => {
+        await deleteFeature.mutateAsync(id);
+        onRefresh();
+    };
+
+    const handleAddAction = async () => {
+        if (!newAction.label.trim() || !newAction.href.trim()) return;
+        await createAction.mutateAsync({
+            sectionId: block.id,
+            label: newAction.label.trim(),
+            href: newAction.href.trim(),
+            variant: newAction.variant,
+            icon: newAction.icon.trim() || undefined,
+            sortOrder: block.actions.length,
+        });
+        setNewAction({ label: '', href: '', variant: 'default', icon: '' });
+        onRefresh();
+    };
+
+    const handleDeleteAction = async (id: string) => {
+        await deleteAction.mutateAsync(id);
+        onRefresh();
+    };
+
+    if (!config) return null;
+
+    const Icon = config.icon;
+
+    return (
+        <Sheet open onOpenChange={(open) => !open && onClose()}>
+            <SheetContent className="w-[500px] sm:max-w-[500px] overflow-y-auto">
+                <SheetHeader>
+                    <SheetTitle className="flex items-center gap-2">
+                        <Icon className="h-5 w-5 text-primary" />
+                        Edit {config.label}
+                    </SheetTitle>
+                    <SheetDescription>{config.description}</SheetDescription>
+                </SheetHeader>
+
+                <div className="space-y-6 mt-6">
+                    {/* Variant Selection */}
+                    {variants.length > 1 && (
+                        <div className="space-y-2">
+                            <Label>Layout Variant</Label>
+                            <Select value={form.variant} onValueChange={(v) => setForm({ ...form, variant: v })}>
+                                <SelectTrigger>
+                                    <SelectValue />
+                                </SelectTrigger>
+                                <SelectContent>
+                                    {variants.map((v) => (
+                                        <SelectItem key={v.value} value={v.value}>
+                                            {v.label}
+                                        </SelectItem>
+                                    ))}
+                                </SelectContent>
+                            </Select>
+                        </div>
+                    )}
+
+                    <Separator />
+
+                    {/* Content Fields */}
+                    <div className="space-y-4">
+                        <div className="space-y-2">
+                            <Label>Title</Label>
+                            <Input
+                                value={form.title}
+                                onChange={(e) => setForm({ ...form, title: e.target.value })}
+                                placeholder="Block title"
+                            />
+                        </div>
+
+                        <div className="space-y-2">
+                            <Label>Subtitle / Tagline</Label>
+                            <Input
+                                value={form.subtitle}
+                                onChange={(e) => setForm({ ...form, subtitle: e.target.value })}
+                                placeholder="Short description"
+                            />
+                        </div>
+
+                        <div className="space-y-2">
+                            <Label>Body Content</Label>
+                            <Textarea
+                                value={form.body}
+                                onChange={(e) => setForm({ ...form, body: e.target.value })}
+                                rows={4}
+                                placeholder="Main content (supports markdown)"
+                            />
+                        </div>
+
+                        <div className="grid grid-cols-2 gap-4">
+                            <div className="space-y-2">
+                                <Label>Icon (Lucide name)</Label>
+                                <Input
+                                    value={form.icon}
+                                    onChange={(e) => setForm({ ...form, icon: e.target.value })}
+                                    placeholder="e.g. Sparkles"
+                                />
+                            </div>
+                            <div className="space-y-2">
+                                <Label>Image URL</Label>
+                                <Input
+                                    value={form.imageUrl}
+                                    onChange={(e) => setForm({ ...form, imageUrl: e.target.value })}
+                                    placeholder="https://..."
+                                />
+                            </div>
+                        </div>
+
+                        {['video', 'hero'].includes(block.slot) && (
+                            <div className="space-y-2">
+                                <Label>Video URL</Label>
+                                <Input
+                                    value={form.videoUrl}
+                                    onChange={(e) => setForm({ ...form, videoUrl: e.target.value })}
+                                    placeholder="https://youtube.com/..."
+                                />
+                            </div>
+                        )}
+
+                        {block.slot === 'navbar' && (
+                            <div className="space-y-2">
+                                <Label>GitHub URL</Label>
+                                <Input
+                                    value={form.githubUrl}
+                                    onChange={(e) => setForm({ ...form, githubUrl: e.target.value })}
+                                    placeholder="https://github.com/..."
+                                />
+                            </div>
+                        )}
+                    </div>
+
+                    {/* Features */}
+                    {config.supportsFeatures && (
+                        <>
+                            <Separator />
+                            <div className="space-y-4">
+                                <h4 className="font-medium">Features / Items</h4>
+                                {block.features.length > 0 && (
+                                    <div className="space-y-2">
+                                        {block.features.map((f) => (
+                                            <div
+                                                key={f.id}
+                                                className="flex items-center gap-3 p-3 rounded-lg border bg-muted/30"
+                                            >
+                                                {f.icon && (
+                                                    <Badge variant="secondary" className="shrink-0">
+                                                        {f.icon}
+                                                    </Badge>
+                                                )}
+                                                <div className="flex-1 min-w-0">
+                                                    <p className="font-medium text-sm">{f.title}</p>
+                                                    {f.description && (
+                                                        <p className="text-xs text-muted-foreground truncate">
+                                                            {f.description}
+                                                        </p>
+                                                    )}
+                                                </div>
+                                                <Button
+                                                    variant="ghost"
+                                                    size="icon"
+                                                    className="h-8 w-8 shrink-0"
+                                                    onClick={() => handleDeleteFeature(f.id)}
+                                                >
+                                                    <Trash2 className="h-4 w-4 text-destructive" />
+                                                </Button>
+                                            </div>
+                                        ))}
+                                    </div>
+                                )}
+                                <Card>
+                                    <CardHeader className="py-3">
+                                        <CardTitle className="text-sm">Add Feature</CardTitle>
+                                    </CardHeader>
+                                    <CardContent className="space-y-3">
+                                        <Input
+                                            placeholder="Title"
+                                            value={newFeature.title}
+                                            onChange={(e) => setNewFeature({ ...newFeature, title: e.target.value })}
+                                        />
+                                        <Input
+                                            placeholder="Description"
+                                            value={newFeature.description}
+                                            onChange={(e) =>
+                                                setNewFeature({ ...newFeature, description: e.target.value })
+                                            }
+                                        />
+                                        <div className="flex gap-2">
+                                            <Input
+                                                placeholder="Icon"
+                                                value={newFeature.icon}
+                                                onChange={(e) => setNewFeature({ ...newFeature, icon: e.target.value })}
+                                                className="flex-1"
+                                            />
+                                            <Button
+                                                onClick={handleAddFeature}
+                                                disabled={!newFeature.title.trim()}
+                                                size="sm"
+                                            >
+                                                <Plus className="h-4 w-4" />
+                                            </Button>
+                                        </div>
+                                    </CardContent>
+                                </Card>
+                            </div>
+                        </>
+                    )}
+
+                    {/* Actions */}
+                    {config.supportsActions && (
+                        <>
+                            <Separator />
+                            <div className="space-y-4">
+                                <h4 className="font-medium">Buttons / Actions</h4>
+                                {block.actions.length > 0 && (
+                                    <div className="space-y-2">
+                                        {block.actions.map((a) => (
+                                            <div
+                                                key={a.id}
+                                                className="flex items-center gap-3 p-3 rounded-lg border bg-muted/30"
+                                            >
+                                                <Badge variant="outline" className="shrink-0">
+                                                    {a.variant || 'default'}
+                                                </Badge>
+                                                <div className="flex-1 min-w-0">
+                                                    <p className="font-medium text-sm">{a.label}</p>
+                                                    <p className="text-xs text-muted-foreground truncate">{a.href}</p>
+                                                </div>
+                                                <Button
+                                                    variant="ghost"
+                                                    size="icon"
+                                                    className="h-8 w-8 shrink-0"
+                                                    onClick={() => handleDeleteAction(a.id)}
+                                                >
+                                                    <Trash2 className="h-4 w-4 text-destructive" />
+                                                </Button>
+                                            </div>
+                                        ))}
+                                    </div>
+                                )}
+                                <Card>
+                                    <CardHeader className="py-3">
+                                        <CardTitle className="text-sm">Add Button</CardTitle>
+                                    </CardHeader>
+                                    <CardContent className="space-y-3">
+                                        <div className="grid grid-cols-2 gap-2">
+                                            <Input
+                                                placeholder="Label"
+                                                value={newAction.label}
+                                                onChange={(e) => setNewAction({ ...newAction, label: e.target.value })}
+                                            />
+                                            <Input
+                                                placeholder="URL (e.g. /docs)"
+                                                value={newAction.href}
+                                                onChange={(e) => setNewAction({ ...newAction, href: e.target.value })}
+                                            />
+                                        </div>
+                                        <div className="flex gap-2">
+                                            <Select
+                                                value={newAction.variant}
+                                                onValueChange={(v) => setNewAction({ ...newAction, variant: v })}
+                                            >
+                                                <SelectTrigger className="flex-1">
+                                                    <SelectValue />
+                                                </SelectTrigger>
+                                                <SelectContent>
+                                                    {ACTION_VARIANTS.map((v) => (
+                                                        <SelectItem key={v.value} value={v.value}>
+                                                            {v.label}
+                                                        </SelectItem>
+                                                    ))}
+                                                </SelectContent>
+                                            </Select>
+                                            <Button
+                                                onClick={handleAddAction}
+                                                disabled={!newAction.label.trim() || !newAction.href.trim()}
+                                                size="sm"
+                                            >
+                                                <Plus className="h-4 w-4" />
+                                            </Button>
+                                        </div>
+                                    </CardContent>
+                                </Card>
+                            </div>
+                        </>
+                    )}
+
+                    {/* Save Button */}
+                    <div className="pt-4">
+                        <Button onClick={handleSave} className="w-full">
+                            {saved ? <Check className="mr-2 h-4 w-4" /> : <Save className="mr-2 h-4 w-4" />}
+                            {saved ? 'Saved!' : 'Save Changes'}
+                        </Button>
+                    </div>
+                </div>
+            </SheetContent>
+        </Sheet>
+    );
+}
+
+// ── Page Settings Dialog ────────────────────────────────────────────────────
+
+function PageSettingsDialog({
+    page,
+    open,
+    onOpenChange,
+    onSave,
+}: {
+    page: PageRow;
+    open: boolean;
+    onOpenChange: (open: boolean) => void;
+    onSave: (data: Partial<PageRow>) => void;
+}) {
+    const [form, setForm] = useState({
+        title: page.title,
+        slug: page.slug,
+        status: page.status,
+        themePreset: page.themePreset ?? 'default',
+        seoTitle: page.seoTitle ?? '',
+        seoDescription: page.seoDescription ?? '',
+        seoImage: page.seoImage ?? '',
+        customCss: page.customCss ?? '',
+        showInNav: page.showInNav ?? false,
+        navOrder: page.navOrder ?? 0,
+        navLabel: page.navLabel ?? '',
+        icon: page.icon ?? '',
+    });
+
+    useEffect(() => {
+        setForm({
+            title: page.title,
+            slug: page.slug,
+            status: page.status,
+            themePreset: page.themePreset ?? 'default',
+            seoTitle: page.seoTitle ?? '',
+            seoDescription: page.seoDescription ?? '',
+            seoImage: page.seoImage ?? '',
+            customCss: page.customCss ?? '',
+            showInNav: page.showInNav ?? false,
+            navOrder: page.navOrder ?? 0,
+            navLabel: page.navLabel ?? '',
+            icon: page.icon ?? '',
+        });
+    }, [page]);
+
+    const handleSave = () => {
+        onSave(form);
+        onOpenChange(false);
+    };
+
+    return (
+        <Dialog open={open} onOpenChange={onOpenChange}>
+            <DialogContent className="max-w-2xl max-h-[90vh] overflow-y-auto">
+                <DialogHeader>
+                    <DialogTitle>Page Settings</DialogTitle>
+                    <DialogDescription>Configure page settings, SEO, and navigation options</DialogDescription>
+                </DialogHeader>
+
+                <div className="space-y-6 py-4">
+                    {/* Basic Info */}
+                    <div className="space-y-4">
+                        <h4 className="font-medium">Basic Information</h4>
+                        <div className="grid grid-cols-2 gap-4">
+                            <div className="space-y-2">
+                                <Label>Title</Label>
+                                <Input
+                                    value={form.title}
+                                    onChange={(e) => setForm({ ...form, title: e.target.value })}
+                                    placeholder="Page Title"
+                                />
+                            </div>
+                            <div className="space-y-2">
+                                <Label>Slug</Label>
+                                <Input
+                                    value={form.slug}
+                                    onChange={(e) => setForm({ ...form, slug: e.target.value })}
+                                    placeholder="page-slug"
+                                    disabled={page.slug === 'homepage'}
+                                />
+                            </div>
+                        </div>
+                        <div className="space-y-2">
+                            <Label>Status</Label>
+                            <Select
+                                value={form.status}
+                                onValueChange={(v: PageRow['status']) => setForm({ ...form, status: v })}
+                            >
+                                <SelectTrigger className="w-48">
+                                    <SelectValue />
+                                </SelectTrigger>
+                                <SelectContent>
+                                    {PAGE_STATUS_OPTIONS.map((opt) => (
+                                        <SelectItem key={opt.value} value={opt.value}>
+                                            {opt.label}
+                                        </SelectItem>
+                                    ))}
+                                </SelectContent>
+                            </Select>
+                        </div>
+                    </div>
+
+                    <Separator />
+
+                    {/* Theme */}
+                    <div className="space-y-4">
+                        <h4 className="font-medium flex items-center gap-2">
+                            <Palette className="h-4 w-4" />
+                            Theme
+                        </h4>
+                        <div className="grid grid-cols-4 gap-2">
+                            {THEME_PRESETS.map((preset) => (
+                                <button
+                                    key={preset.id}
+                                    type="button"
+                                    onClick={() => setForm({ ...form, themePreset: preset.id })}
+                                    className={`p-3 rounded-lg border text-left transition-all text-sm ${
+                                        form.themePreset === preset.id
+                                            ? 'border-primary bg-primary/5 ring-2 ring-primary'
+                                            : 'hover:bg-muted/50'
+                                    }`}
+                                >
+                                    <div className="font-medium">{preset.label}</div>
+                                    <p className="text-xs text-muted-foreground">{preset.description}</p>
+                                </button>
+                            ))}
+                        </div>
+                    </div>
+
+                    <Separator />
+
+                    {/* Navigation */}
+                    <div className="space-y-4">
+                        <h4 className="font-medium">Navigation</h4>
+                        <div className="flex items-center justify-between">
+                            <div>
+                                <Label>Show in navigation</Label>
+                                <p className="text-sm text-muted-foreground">Display link in site navigation</p>
+                            </div>
+                            <Switch
+                                checked={form.showInNav}
+                                onCheckedChange={(v) => setForm({ ...form, showInNav: v })}
+                            />
+                        </div>
+                        {form.showInNav && (
+                            <div className="grid grid-cols-3 gap-4 pt-2">
+                                <div className="space-y-2">
+                                    <Label>Nav Label</Label>
+                                    <Input
+                                        value={form.navLabel}
+                                        onChange={(e) => setForm({ ...form, navLabel: e.target.value })}
+                                        placeholder={form.title || 'Page title'}
+                                    />
+                                </div>
+                                <div className="space-y-2">
+                                    <Label>Order</Label>
+                                    <Input
+                                        type="number"
+                                        value={form.navOrder}
+                                        onChange={(e) => setForm({ ...form, navOrder: parseInt(e.target.value) || 0 })}
+                                    />
+                                </div>
+                                <div className="space-y-2">
+                                    <Label>Icon</Label>
+                                    <Input
+                                        value={form.icon}
+                                        onChange={(e) => setForm({ ...form, icon: e.target.value })}
+                                        placeholder="FileText"
+                                    />
+                                </div>
+                            </div>
+                        )}
+                    </div>
+
+                    <Separator />
+
+                    {/* SEO */}
+                    <div className="space-y-4">
+                        <h4 className="font-medium">SEO</h4>
+                        <div className="space-y-4">
+                            <div className="space-y-2">
+                                <Label>Page Title</Label>
+                                <Input
+                                    value={form.seoTitle}
+                                    onChange={(e) => setForm({ ...form, seoTitle: e.target.value })}
+                                    placeholder={form.title || 'Page Title - Site Name'}
+                                />
+                            </div>
+                            <div className="space-y-2">
+                                <Label>Meta Description</Label>
+                                <Textarea
+                                    value={form.seoDescription}
+                                    onChange={(e) => setForm({ ...form, seoDescription: e.target.value })}
+                                    placeholder="A compelling description for search engines..."
+                                    rows={2}
+                                />
+                            </div>
+                            <div className="space-y-2">
+                                <Label>Social Image URL</Label>
+                                <Input
+                                    value={form.seoImage}
+                                    onChange={(e) => setForm({ ...form, seoImage: e.target.value })}
+                                    placeholder="https://example.com/og-image.png"
+                                />
+                            </div>
+                        </div>
+                    </div>
+                </div>
+
+                <div className="flex justify-end gap-2">
+                    <Button variant="outline" onClick={() => onOpenChange(false)}>
+                        Cancel
+                    </Button>
+                    <Button onClick={handleSave}>
+                        <Save className="mr-2 h-4 w-4" />
+                        Save Settings
+                    </Button>
+                </div>
+            </DialogContent>
+        </Dialog>
+    );
+}
+
+// ── Main Page Builder ───────────────────────────────────────────────────────
+
+export function MarketingPageBuilder() {
+    const { pageId } = useParams({ from: '/admin/pages/$pageId' });
+
+    // State
+    const [selectedBlockId, setSelectedBlockId] = useState<string | null>(null);
+    const [settingsOpen, setSettingsOpen] = useState(false);
+
+    // Data hooks
+    const { data: pageData, isLoading: pageLoading, refetch: refetchPage } = pageHooks.useDetail(pageId);
+    const { data: sectionsData, refetch: refetchSections } = pageSectionHooks.useList(
+        { where: { pageId }, orderBy: 'sortOrder', orderDirection: 'asc' },
+        ADMIN_LIST_QUERY_CONFIG,
+    );
+    const { data: featuresData, refetch: refetchFeatures } = pageFeatureHooks.useList(
+        { orderBy: 'sortOrder', orderDirection: 'asc' },
+        ADMIN_LIST_QUERY_CONFIG,
+    );
+    const { data: actionsData, refetch: refetchActions } = pageActionHooks.useList(
+        { orderBy: 'sortOrder', orderDirection: 'asc' },
+        ADMIN_LIST_QUERY_CONFIG,
+    );
+
+    const updatePage = pageHooks.useUpdate();
+    const createSection = pageSectionHooks.useCreate();
+    const updateSection = pageSectionHooks.useUpdate();
+    const deleteSection = pageSectionHooks.useDelete();
+
+    // Type-safe data
+    const page = pageData as PageRow | undefined;
+    const sections = useMemo(() => {
+        const data = (Array.isArray(sectionsData) ? sectionsData : []) as PageSectionRow[];
+        return data.filter((s) => s.pageId === pageId).sort((a, b) => a.sortOrder - b.sortOrder);
+    }, [sectionsData, pageId]);
+    const features = useMemo(
+        () => (Array.isArray(featuresData) ? featuresData : []) as PageFeatureRow[],
+        [featuresData],
+    );
+    const actions = useMemo(() => (Array.isArray(actionsData) ? actionsData : []) as PageActionRow[], [actionsData]);
+
+    // Build blocks with their features and actions
+    const blocks = useMemo<BlockWithData[]>(() => {
+        return sections.map((section) => ({
+            ...section,
+            features: features.filter((f) => f.sectionId === section.id),
+            actions: actions.filter((a) => a.sectionId === section.id),
+        }));
+    }, [sections, features, actions]);
+
+    // Selected block
+    const selectedBlock = useMemo(() => {
+        if (!selectedBlockId) return null;
+        return blocks.find((b) => b.id === selectedBlockId) ?? null;
+    }, [blocks, selectedBlockId]);
+
+    // Refresh all data
+    const handleRefresh = useCallback(() => {
+        refetchSections();
+        refetchFeatures();
+        refetchActions();
+    }, [refetchSections, refetchFeatures, refetchActions]);
+
+    // Page update
+    const handleUpdatePage = async (data: Partial<PageRow>) => {
+        await updatePage.mutateAsync({ id: pageId, data });
+        refetchPage();
+    };
+
+    // Add block
+    const handleAddBlock = async (blockType: string) => {
+        const config = getSlotConfig(blockType);
+        if (!config) return;
+
+        await createSection.mutateAsync({
+            pageId,
+            slot: blockType,
+            title: config.label,
+            variant: config.defaultVariant,
+            enabled: true,
+            sortOrder: sections.length,
+        });
+        handleRefresh();
+    };
+
+    // Update block
+    const handleUpdateBlock = async (id: string, data: Partial<PageSectionRow>) => {
+        await updateSection.mutateAsync({ id, data });
+        handleRefresh();
+    };
+
+    // Toggle block visibility
+    const handleToggleBlock = async (block: BlockWithData) => {
+        await updateSection.mutateAsync({ id: block.id, data: { enabled: !block.enabled } });
+        handleRefresh();
+    };
+
+    // Delete block
+    const handleDeleteBlock = async (block: BlockWithData) => {
+        if (!confirm(`Delete "${block.title || block.slot}" block?`)) return;
+        await deleteSection.mutateAsync(block.id);
+        if (selectedBlockId === block.id) setSelectedBlockId(null);
+        handleRefresh();
+    };
+
+    // Reorder blocks
+    const handleReorder = async (oldIndex: number, newIndex: number) => {
+        const newBlocks = arrayMove(blocks, oldIndex, newIndex);
+        // Update sort order for affected blocks
+        for (let i = 0; i < newBlocks.length; i++) {
+            if (newBlocks[i].sortOrder !== i) {
+                await updateSection.mutateAsync({ id: newBlocks[i].id, data: { sortOrder: i } });
+            }
+        }
+        handleRefresh();
+    };
+
+    if (pageLoading || !page) {
+        return (
+            <div className="flex items-center justify-center min-h-[400px]">
+                <div className="text-muted-foreground">Loading...</div>
+            </div>
+        );
+    }
+
+    return (
+        <div className="h-screen flex flex-col">
+            {/* Header */}
+            <div className="border-b bg-background/95 backdrop-blur supports-[backdrop-filter]:bg-background/60 shrink-0">
+                <div className="flex items-center justify-between px-4 py-3">
+                    <div className="flex items-center gap-3">
+                        <Link to="/admin/pages" className="p-2 rounded-lg hover:bg-muted">
+                            <ArrowLeft className="h-5 w-5" />
+                        </Link>
+                        <div>
+                            <div className="flex items-center gap-2">
+                                <h1 className="text-lg font-semibold">{page.title}</h1>
+                                <Badge variant={page.status === 'published' ? 'default' : 'secondary'}>
+                                    {page.status}
+                                </Badge>
+                                {page.slug === 'homepage' && (
+                                    <Badge variant="outline" className="text-xs">
+                                        Homepage
+                                    </Badge>
+                                )}
+                            </div>
+                            <p className="text-sm text-muted-foreground">/{page.slug}</p>
+                        </div>
+                    </div>
+                    <div className="flex items-center gap-2">
+                        <Button variant="outline" size="sm" onClick={() => setSettingsOpen(true)}>
+                            <Settings className="mr-2 h-4 w-4" />
+                            Settings
+                        </Button>
+                        <a
+                            href={`${import.meta.env.VITE_HOMEPAGE_URL || 'http://localhost:3000'}/${page.slug === 'homepage' ? '' : page.slug}?preview=true`}
+                            target="_blank"
+                            rel="noopener noreferrer"
+                        >
+                            <Button variant="outline" size="sm">
+                                <ExternalLink className="mr-2 h-4 w-4" />
+                                Preview
+                            </Button>
+                        </a>
+                    </div>
+                </div>
+            </div>
+
+            {/* Main Content: Palette + Canvas */}
+            <div className="flex-1 flex overflow-hidden">
+                <BlockPalette onAddBlock={handleAddBlock} existingBlocks={blocks.map((b) => b.slot)} />
+                <Canvas
+                    blocks={blocks}
+                    selectedBlockId={selectedBlockId}
+                    onSelectBlock={setSelectedBlockId}
+                    onReorder={handleReorder}
+                    onToggleBlock={handleToggleBlock}
+                    onDeleteBlock={handleDeleteBlock}
+                />
+            </div>
+
+            {/* Block Editor Sheet */}
+            {selectedBlock && (
+                <BlockEditor
+                    block={selectedBlock}
+                    onUpdate={(data) => handleUpdateBlock(selectedBlock.id, data)}
+                    onClose={() => setSelectedBlockId(null)}
+                    onRefresh={handleRefresh}
+                />
+            )}
+
+            {/* Page Settings Dialog */}
+            <PageSettingsDialog
+                page={page}
+                open={settingsOpen}
+                onOpenChange={setSettingsOpen}
+                onSave={handleUpdatePage}
+            />
+        </div>
+    );
+}
diff --git a/apps/ottabase-template-app-tanstack/src/pages/admin/pages/index.ts b/apps/ottabase-template-app-tanstack/src/pages/admin/pages/index.ts
new file mode 100644
index 000000000..3513316b7
--- /dev/null
+++ b/apps/ottabase-template-app-tanstack/src/pages/admin/pages/index.ts
@@ -0,0 +1,7 @@
+/**
+ * Marketing Pages module exports
+ */
+export { AdminPageBuilderPage } from './AdminPageBuilderPage';
+export { AdminPagesListPage } from './AdminPagesListPage';
+export { MarketingPageBuilder } from './MarketingPageBuilder';
+export * from './pages-constants';
diff --git a/apps/ottabase-template-app-tanstack/src/pages/admin/pages/pages-constants.ts b/apps/ottabase-template-app-tanstack/src/pages/admin/pages/pages-constants.ts
new file mode 100644
index 000000000..f0e3dd5f0
--- /dev/null
+++ b/apps/ottabase-template-app-tanstack/src/pages/admin/pages/pages-constants.ts
@@ -0,0 +1,304 @@
+/**
+ * Marketing Pages Admin Constants
+ *
+ * Shared constants for the drag-and-drop Marketing Pages builder.
+ */
+
+import {
+    Code2,
+    Contact,
+    FileText,
+    Grid3X3,
+    ImageIcon,
+    LayoutList,
+    Megaphone,
+    Navigation,
+    Quote,
+    Rows3,
+    Sparkles,
+    Users,
+    Video,
+    type LucideIcon,
+} from 'lucide-react';
+
+// ── Section Slot Types ──────────────────────────────────────────────────────
+
+export interface SlotConfig {
+    id: string;
+    label: string;
+    icon: LucideIcon;
+    description: string;
+    supportsFeatures: boolean;
+    supportsActions: boolean;
+    defaultVariant: string;
+}
+
+/**
+ * Block types for the Marketing Pages drag-and-drop builder.
+ * Organized by category for the block palette.
+ */
+export const BLOCK_TYPES: SlotConfig[] = [
+    // Navigation
+    {
+        id: 'navbar',
+        label: 'Navigation Bar',
+        icon: Navigation,
+        description: 'Site navigation with logo and links',
+        supportsFeatures: false,
+        supportsActions: true,
+        defaultVariant: 'default',
+    },
+    // Hero Sections
+    {
+        id: 'hero',
+        label: 'Hero Section',
+        icon: Sparkles,
+        description: 'Bold headline with call-to-action buttons',
+        supportsFeatures: false,
+        supportsActions: true,
+        defaultVariant: 'centered',
+    },
+    // Content Blocks
+    {
+        id: 'features',
+        label: 'Features Grid',
+        icon: Grid3X3,
+        description: 'Showcase product features in a grid layout',
+        supportsFeatures: true,
+        supportsActions: false,
+        defaultVariant: 'grid',
+    },
+    {
+        id: 'cta',
+        label: 'Call to Action',
+        icon: Megaphone,
+        description: 'Prominent section with action buttons',
+        supportsFeatures: false,
+        supportsActions: true,
+        defaultVariant: 'default',
+    },
+    {
+        id: 'about',
+        label: 'About / Content',
+        icon: FileText,
+        description: 'Rich text content with optional features',
+        supportsFeatures: true,
+        supportsActions: true,
+        defaultVariant: 'default',
+    },
+    {
+        id: 'testimonials',
+        label: 'Testimonials',
+        icon: Quote,
+        description: 'Customer reviews and testimonials',
+        supportsFeatures: true,
+        supportsActions: false,
+        defaultVariant: 'carousel',
+    },
+    {
+        id: 'gallery',
+        label: 'Image Gallery',
+        icon: ImageIcon,
+        description: 'Visual showcase of images',
+        supportsFeatures: true,
+        supportsActions: false,
+        defaultVariant: 'grid',
+    },
+    {
+        id: 'team',
+        label: 'Team Members',
+        icon: Users,
+        description: 'Display team member profiles',
+        supportsFeatures: true,
+        supportsActions: false,
+        defaultVariant: 'grid',
+    },
+    {
+        id: 'pricing',
+        label: 'Pricing Table',
+        icon: LayoutList,
+        description: 'Product or service pricing plans',
+        supportsFeatures: true,
+        supportsActions: true,
+        defaultVariant: 'cards',
+    },
+    {
+        id: 'faq',
+        label: 'FAQ Section',
+        icon: Contact,
+        description: 'Frequently asked questions',
+        supportsFeatures: true,
+        supportsActions: false,
+        defaultVariant: 'accordion',
+    },
+    {
+        id: 'video',
+        label: 'Video Section',
+        icon: Video,
+        description: 'Embedded video with text',
+        supportsFeatures: false,
+        supportsActions: true,
+        defaultVariant: 'default',
+    },
+    {
+        id: 'code',
+        label: 'Code Block',
+        icon: Code2,
+        description: 'Code snippet with syntax highlighting',
+        supportsFeatures: false,
+        supportsActions: false,
+        defaultVariant: 'default',
+    },
+    {
+        id: 'custom',
+        label: 'Custom Block',
+        icon: FileText,
+        description: 'Flexible block for any content',
+        supportsFeatures: true,
+        supportsActions: true,
+        defaultVariant: 'default',
+    },
+    // Footer
+    {
+        id: 'footer',
+        label: 'Footer',
+        icon: Rows3,
+        description: 'Page footer with links and info',
+        supportsFeatures: false,
+        supportsActions: true,
+        defaultVariant: 'default',
+    },
+];
+
+// Legacy alias for backward compatibility
+export const SLOT_TYPES = BLOCK_TYPES;
+
+// Helper to get slot config by id
+export function getSlotConfig(slotId: string): SlotConfig | undefined {
+    return BLOCK_TYPES.find((s) => s.id === slotId);
+}
+
+// Block type variants (different layouts/styles for each block type)
+export const BLOCK_VARIANTS: Record<string, { value: string; label: string }[]> = {
+    hero: [
+        { value: 'centered', label: 'Centered' },
+        { value: 'split', label: 'Split (Image Right)' },
+        { value: 'split-reverse', label: 'Split (Image Left)' },
+        { value: 'fullscreen', label: 'Fullscreen' },
+        { value: 'video-bg', label: 'Video Background' },
+    ],
+    features: [
+        { value: 'grid', label: 'Grid (3 cols)' },
+        { value: 'grid-2', label: 'Grid (2 cols)' },
+        { value: 'grid-4', label: 'Grid (4 cols)' },
+        { value: 'list', label: 'List' },
+        { value: 'cards', label: 'Cards' },
+        { value: 'alternating', label: 'Alternating' },
+    ],
+    cta: [
+        { value: 'default', label: 'Default' },
+        { value: 'banner', label: 'Banner' },
+        { value: 'gradient', label: 'Gradient' },
+        { value: 'minimal', label: 'Minimal' },
+    ],
+    testimonials: [
+        { value: 'carousel', label: 'Carousel' },
+        { value: 'grid', label: 'Grid' },
+        { value: 'single', label: 'Single Quote' },
+        { value: 'masonry', label: 'Masonry' },
+    ],
+    gallery: [
+        { value: 'grid', label: 'Grid' },
+        { value: 'masonry', label: 'Masonry' },
+        { value: 'carousel', label: 'Carousel' },
+        { value: 'lightbox', label: 'Lightbox' },
+    ],
+    team: [
+        { value: 'grid', label: 'Grid' },
+        { value: 'cards', label: 'Cards' },
+        { value: 'list', label: 'List' },
+    ],
+    pricing: [
+        { value: 'cards', label: 'Cards' },
+        { value: 'table', label: 'Table' },
+        { value: 'comparison', label: 'Comparison' },
+    ],
+    faq: [
+        { value: 'accordion', label: 'Accordion' },
+        { value: 'list', label: 'List' },
+        { value: 'two-column', label: 'Two Column' },
+    ],
+    navbar: [
+        { value: 'default', label: 'Default' },
+        { value: 'centered', label: 'Centered Logo' },
+        { value: 'transparent', label: 'Transparent' },
+    ],
+    footer: [
+        { value: 'default', label: 'Default' },
+        { value: 'minimal', label: 'Minimal' },
+        { value: 'detailed', label: 'Multi-Column' },
+    ],
+    about: [
+        { value: 'default', label: 'Default' },
+        { value: 'with-image', label: 'With Image' },
+        { value: 'stats', label: 'With Stats' },
+    ],
+    video: [
+        { value: 'default', label: 'Default' },
+        { value: 'fullwidth', label: 'Full Width' },
+        { value: 'with-text', label: 'With Text' },
+    ],
+    code: [
+        { value: 'default', label: 'Default' },
+        { value: 'with-tabs', label: 'With Tabs' },
+    ],
+    custom: [
+        { value: 'default', label: 'Default' },
+        { value: 'card', label: 'Card' },
+        { value: 'full-width', label: 'Full Width' },
+    ],
+};
+
+// Get variants for a block type
+export function getBlockVariants(blockId: string): { value: string; label: string }[] {
+    return BLOCK_VARIANTS[blockId] || [{ value: 'default', label: 'Default' }];
+}
+
+// ── Theme Presets ───────────────────────────────────────────────────────────
+
+export const THEME_PRESETS = [
+    { id: 'default', label: 'Default', description: 'Clean and minimal' },
+    { id: 'neo', label: 'Neo', description: 'Modern and bold' },
+    { id: 'retro', label: 'Retro', description: 'Vintage vibes' },
+    { id: 'pastel', label: 'Pastel', description: 'Soft and gentle' },
+    { id: 'monochrome', label: 'Monochrome', description: 'Black and white' },
+    { id: 'gradient', label: 'Gradient', description: 'Colorful gradients' },
+    { id: 'glass', label: 'Glass', description: 'Glassmorphism style' },
+    { id: 'brutalist', label: 'Brutalist', description: 'Raw and bold' },
+] as const;
+
+// ── Action Variants ─────────────────────────────────────────────────────────
+
+export const ACTION_VARIANTS = [
+    { value: 'default', label: 'Primary' },
+    { value: 'secondary', label: 'Secondary' },
+    { value: 'outline', label: 'Outline' },
+    { value: 'ghost', label: 'Ghost' },
+    { value: 'link', label: 'Link' },
+    { value: 'destructive', label: 'Destructive' },
+] as const;
+
+// ── Page Status Options ─────────────────────────────────────────────────────
+
+export const PAGE_STATUS_OPTIONS = [
+    { value: 'draft', label: 'Draft', description: 'Not visible to public' },
+    { value: 'published', label: 'Published', description: 'Visible to public' },
+    { value: 'archived', label: 'Archived', description: 'Hidden but preserved' },
+] as const;
+
+// ── Page Type Options ───────────────────────────────────────────────────────
+
+export const PAGE_TYPE_OPTIONS = [
+    { value: 'block', label: 'Block', description: 'Section-based page builder' },
+    { value: 'content', label: 'Content', description: 'Rich text from CMS' },
+] as const;
diff --git a/apps/ottabase-template-app-tanstack/src/router.tsx b/apps/ottabase-template-app-tanstack/src/router.tsx
index e8dae7739..f1776d8ed 100644
--- a/apps/ottabase-template-app-tanstack/src/router.tsx
+++ b/apps/ottabase-template-app-tanstack/src/router.tsx
@@ -942,6 +942,27 @@ const adminHomepageRoute = new Route({
     ),
 });
 
+// Marketing Pages admin routes (drag-and-drop page builder)
+const adminPagesRoute = new Route({
+    getParentRoute: () => rootRoute,
+    path: '/admin/pages',
+    component: lazyRouteComponent(() =>
+        import('@/pages/admin/pages').then((m) => ({
+            default: () => renderAdminRoute(<m.AdminPagesListPage />),
+        })),
+    ),
+});
+
+const adminPageBuilderRoute = new Route({
+    getParentRoute: () => rootRoute,
+    path: '/admin/pages/$pageId',
+    component: lazyRouteComponent(() =>
+        import('@/pages/admin/pages').then((m) => ({
+            default: () => renderAdminRoute(<m.MarketingPageBuilder />),
+        })),
+    ),
+});
+
 // Organizations routes
 const organizationsRoute = new Route({
     getParentRoute: () => rootRoute,
@@ -1174,6 +1195,8 @@ const coreRoutes = [
     adminChangelogNewRoute,
     adminChangelogEditRoute,
     adminHomepageRoute,
+    adminPagesRoute,
+    adminPageBuilderRoute,
     adminDevMailRoute,
     adminQueueRoute,
     adminCronRoute,
diff --git a/apps/ottabase-template-app-tanstack/worker/lib/db-utils.ts b/apps/ottabase-template-app-tanstack/worker/lib/db-utils.ts
index b6cf82dee..d153dc5d7 100644
--- a/apps/ottabase-template-app-tanstack/worker/lib/db-utils.ts
+++ b/apps/ottabase-template-app-tanstack/worker/lib/db-utils.ts
@@ -42,6 +42,10 @@ import { HomepageAction } from '../../ottabase/models/HomepageAction';
 import { HomepageDisplaySettings } from '../../ottabase/models/HomepageDisplaySettings';
 import { HomepageFeature } from '../../ottabase/models/HomepageFeature';
 import { HomepageSection } from '../../ottabase/models/HomepageSection';
+import { Page } from '../../ottabase/models/Page';
+import { PageAction } from '../../ottabase/models/PageAction';
+import { PageFeature } from '../../ottabase/models/PageFeature';
+import { PageSection } from '../../ottabase/models/PageSection';
 import { Todo } from '../../ottabase/models/Todo';
 import { changelogPolicy } from '../../ottabase/models/changelogPolicy';
 import {
@@ -51,6 +55,7 @@ import {
     homepageSectionPolicy,
 } from '../../ottabase/models/homepagePolicy';
 import { mediaLibraryPolicy } from '../../ottabase/models/mediaLibraryPolicy';
+import { pageActionPolicy, pageFeaturePolicy, pagePolicy, pageSectionPolicy } from '../../ottabase/models/pagePolicy';
 import type { CloudflareEnv } from '../cloudflare-env';
 import { readJson } from './utils';
 
@@ -136,12 +141,22 @@ export function initDbConnection(env: CloudflareEnv): void {
     const brandModels = [BrandKit, LayoutTemplate, LayoutRouteMapping, MenuSlotAssignment];
     registerPolicy(mediaLibraryPolicy);
     registerPolicy(changelogPolicy);
+    // Legacy homepage policies
     registerPolicy(homepageSectionPolicy);
     registerPolicy(homepageFeaturePolicy);
     registerPolicy(homepageActionPolicy);
     registerPolicy(homepageDisplaySettingsPolicy);
+    // New flexible page system policies
+    registerPolicy(pagePolicy);
+    registerPolicy(pageSectionPolicy);
+    registerPolicy(pageFeaturePolicy);
+    registerPolicy(pageActionPolicy);
 
-    const appModels = [Todo, ChangelogEntry, HomepageSection, HomepageFeature, HomepageAction, HomepageDisplaySettings];
+    // Legacy homepage models (kept for migration)
+    const legacyModels = [HomepageSection, HomepageFeature, HomepageAction, HomepageDisplaySettings];
+    // New flexible page system models
+    const pageModels = [Page, PageSection, PageFeature, PageAction];
+    const appModels = [Todo, ChangelogEntry, ...legacyModels, ...pageModels];
 
     registerModels([...coreModels, ...ottablogModels, ...packageModels, ...brandModels, ...appModels]);
 
diff --git a/apps/ottabase-template-app-tanstack/worker/routes/pages.ts b/apps/ottabase-template-app-tanstack/worker/routes/pages.ts
new file mode 100644
index 000000000..375c08407
--- /dev/null
+++ b/apps/ottabase-template-app-tanstack/worker/routes/pages.ts
@@ -0,0 +1,599 @@
+// ============================================================
+// Pages public API routes
+// ============================================================
+// GET /api/pages/:slug — returns page content by slug
+// GET /api/pages/nav — returns nav-enabled pages for menus
+// POST /api/pages/seed — seeds default homepage content
+//
+// This is the flexible page system that replaces the hardcoded
+// homepage routes. Pages can be "block" type (sections-based)
+// or "content" type (links to ottablog Post for rich text).
+// ============================================================
+
+import { createD1Driver } from '@ottabase/db/drizzle-d1';
+import { Post } from '@ottabase/ottablog';
+import { registerConnection } from '@ottabase/ottaorm';
+import { errorResponse } from '@ottabase/utils/http-errors';
+import { jsonResponse } from '@ottabase/utils/http-response';
+import type { CloudflareEnv } from '../../cloudflare-env';
+import { Page } from '../../ottabase/models/Page';
+import { PageAction } from '../../ottabase/models/PageAction';
+import { PageFeature } from '../../ottabase/models/PageFeature';
+import { PageSection } from '../../ottabase/models/PageSection';
+
+export interface PagesRouteContext {
+    request: Request;
+    env: CloudflareEnv;
+    url: URL;
+}
+
+function ensureD1(env: CloudflareEnv): Response | null {
+    if (!env.OBCF_D1) {
+        return errorResponse('D1 database binding not configured', 500, {
+            code: 'CONFIG_ERROR',
+        });
+    }
+    return null;
+}
+
+// ── Type definitions for API responses ──────────────────────────────────────
+
+export interface PageSectionPayload {
+    id: string;
+    slot: string;
+    title: string | null;
+    subtitle: string | null;
+    body: string | null;
+    variant: string | null;
+    githubUrl: string | null;
+    icon: string | null;
+    imageUrl: string | null;
+    enabled: boolean;
+    cssClasses: string | null;
+    metadata: Record<string, unknown> | null;
+    sortOrder: number;
+    features: Array<{
+        id: string;
+        title: string;
+        description: string;
+        icon: string | null;
+        imageUrl: string | null;
+        href: string | null;
+    }>;
+    actions: Array<{
+        id: string;
+        label: string;
+        href: string;
+        variant: string | null;
+        icon: string | null;
+        external: boolean;
+    }>;
+}
+
+export interface PageDisplayPayload {
+    variantBySlot: Record<string, string> | null;
+    themePreset: string | null;
+    fallbackThemePresetId: string | null;
+    customCss: string | null;
+    seoTitle: string | null;
+    seoDescription: string | null;
+    seoImage: string | null;
+}
+
+export interface PageDataPayload {
+    page: {
+        id: string;
+        slug: string;
+        title: string;
+        type: 'block' | 'content';
+        status: 'draft' | 'published' | 'archived';
+        showInNav: boolean;
+        navOrder: number;
+        navLabel: string | null;
+        icon: string | null;
+    };
+    sections: PageSectionPayload[];
+    display: PageDisplayPayload;
+    // For content-type pages, includes the linked Post content
+    content: {
+        title: string;
+        body: string;
+        excerpt: string | null;
+    } | null;
+}
+
+export interface NavPagePayload {
+    slug: string;
+    title: string;
+    navLabel: string | null;
+    navOrder: number;
+    icon: string | null;
+}
+
+/**
+ * GET /api/pages/:slug
+ *
+ * Returns full page content by slug for the frontend consumer.
+ * For "block" pages: includes sections, features, actions.
+ * For "content" pages: includes linked ottablog Post content.
+ */
+export async function handlePageBySlug(context: PagesRouteContext, slug: string): Promise<Response> {
+    const { env, url } = context;
+    const d1Error = ensureD1(env);
+    if (d1Error) return d1Error;
+    registerConnection('default', createD1Driver(env.OBCF_D1));
+
+    const appId = url.searchParams.get('appId') || null;
+    const preview = url.searchParams.get('preview') === 'true';
+
+    try {
+        // Find the page by slug
+        // In preview mode, allow draft/archived pages; otherwise only published
+        const pageWhere: Record<string, unknown> = { slug };
+        if (!preview) {
+            pageWhere.status = 'published';
+        }
+        if (appId) pageWhere.appId = appId;
+
+        const pages = await Page.where(pageWhere);
+        if (pages.length === 0) {
+            return errorResponse(`Page not found: ${slug}`, 404, { code: 'PAGE_NOT_FOUND' });
+        }
+
+        const page = pages[0];
+        const pageId = page.get('id') as string;
+        const pageType = page.get('type') as 'block' | 'content';
+
+        // Build page metadata
+        const pageData = {
+            id: pageId,
+            slug: page.get('slug') as string,
+            title: page.get('title') as string,
+            type: pageType,
+            status: page.get('status') as 'draft' | 'published' | 'archived',
+            showInNav: (page.get('showInNav') as boolean) ?? false,
+            navOrder: (page.get('navOrder') as number) ?? 0,
+            navLabel: (page.get('navLabel') as string) ?? null,
+            icon: (page.get('icon') as string) ?? null,
+        };
+
+        // Build display settings from the page itself
+        const display: PageDisplayPayload = {
+            variantBySlot: (page.get('variantBySlotJson') as Record<string, string>) ?? null,
+            themePreset: (page.get('themePreset') as string) ?? null,
+            fallbackThemePresetId: (page.get('fallbackThemePresetId') as string) ?? null,
+            customCss: (page.get('customCss') as string) ?? null,
+            seoTitle: (page.get('seoTitle') as string) ?? null,
+            seoDescription: (page.get('seoDescription') as string) ?? null,
+            seoImage: (page.get('seoImage') as string) ?? null,
+        };
+
+        // For content-type pages, load the linked Post
+        let content: PageDataPayload['content'] = null;
+        if (pageType === 'content') {
+            const postId = page.get('postId') as string | null;
+            if (postId) {
+                try {
+                    const post = await Post.find(postId);
+                    if (post) {
+                        content = {
+                            title: post.get('title') as string,
+                            body: post.get('body') as string,
+                            excerpt: (post.get('excerpt') as string) ?? null,
+                        };
+                    }
+                } catch (err) {
+                    console.error(`[pages/:slug] Failed to load linked post ${postId}:`, err);
+                }
+            }
+        }
+
+        // For block-type pages, load sections with features/actions
+        let sections: PageSectionPayload[] = [];
+        if (pageType === 'block') {
+            const sectionRecords = await PageSection.where(
+                { pageId, enabled: true },
+                { orderBy: 'sortOrder', orderDirection: 'asc' },
+            );
+
+            const sectionIds = sectionRecords.map((s) => s.get('id') as string);
+
+            let allFeatures: InstanceType<typeof PageFeature>[] = [];
+            let allActions: InstanceType<typeof PageAction>[] = [];
+
+            if (sectionIds.length > 0) {
+                allFeatures = (await PageFeature.where(
+                    { sectionId: sectionIds },
+                    { orderBy: 'sortOrder', orderDirection: 'asc' },
+                )) as InstanceType<typeof PageFeature>[];
+
+                allActions = (await PageAction.where(
+                    { sectionId: sectionIds },
+                    { orderBy: 'sortOrder', orderDirection: 'asc' },
+                )) as InstanceType<typeof PageAction>[];
+            }
+
+            // Group by sectionId
+            const featuresBySectionId = new Map<string, PageSectionPayload['features']>();
+            for (const f of allFeatures) {
+                const sid = f.get('sectionId') as string;
+                if (!featuresBySectionId.has(sid)) featuresBySectionId.set(sid, []);
+                featuresBySectionId.get(sid)!.push({
+                    id: f.get('id') as string,
+                    title: f.get('title') as string,
+                    description: f.get('description') as string,
+                    icon: (f.get('icon') as string) ?? null,
+                    imageUrl: (f.get('imageUrl') as string) ?? null,
+                    href: (f.get('href') as string) ?? null,
+                });
+            }
+
+            const actionsBySectionId = new Map<string, PageSectionPayload['actions']>();
+            for (const a of allActions) {
+                const sid = a.get('sectionId') as string;
+                if (!actionsBySectionId.has(sid)) actionsBySectionId.set(sid, []);
+                actionsBySectionId.get(sid)!.push({
+                    id: a.get('id') as string,
+                    label: a.get('label') as string,
+                    href: a.get('href') as string,
+                    variant: (a.get('variant') as string) ?? null,
+                    icon: (a.get('icon') as string) ?? null,
+                    external: (a.get('external') as boolean) ?? false,
+                });
+            }
+
+            sections = sectionRecords.map((s) => {
+                const id = s.get('id') as string;
+                return {
+                    id,
+                    slot: s.get('slot') as string,
+                    title: (s.get('title') as string) ?? null,
+                    subtitle: (s.get('subtitle') as string) ?? null,
+                    body: (s.get('body') as string) ?? null,
+                    variant: (s.get('variant') as string) ?? null,
+                    githubUrl: (s.get('githubUrl') as string) ?? null,
+                    icon: (s.get('icon') as string) ?? null,
+                    imageUrl: (s.get('imageUrl') as string) ?? null,
+                    enabled: (s.get('enabled') as boolean) ?? true,
+                    cssClasses: (s.get('cssClasses') as string) ?? null,
+                    metadata: (s.get('metadata') as Record<string, unknown>) ?? null,
+                    sortOrder: (s.get('sortOrder') as number) ?? 0,
+                    features: featuresBySectionId.get(id) ?? [],
+                    actions: actionsBySectionId.get(id) ?? [],
+                };
+            });
+        }
+
+        const payload: PageDataPayload = {
+            page: pageData,
+            sections,
+            display,
+            content,
+        };
+
+        return jsonResponse(payload);
+    } catch (err: unknown) {
+        console.error('[pages/:slug] Failed:', err);
+        return errorResponse((err as Error).message ?? 'Failed to load page', 500);
+    }
+}
+
+/**
+ * GET /api/pages/nav
+ *
+ * Returns pages marked for navigation (showInNav=true).
+ * Used for building nav menus in the frontend.
+ */
+export async function handleNavPages(context: PagesRouteContext): Promise<Response> {
+    const { env, url } = context;
+    const d1Error = ensureD1(env);
+    if (d1Error) return d1Error;
+    registerConnection('default', createD1Driver(env.OBCF_D1));
+
+    const appId = url.searchParams.get('appId') || null;
+
+    try {
+        const where: Record<string, unknown> = { showInNav: true, status: 'published' };
+        if (appId) where.appId = appId;
+
+        const pages = await Page.where(where, { orderBy: 'navOrder', orderDirection: 'asc' });
+
+        const navPages: NavPagePayload[] = pages.map((p) => ({
+            slug: p.get('slug') as string,
+            title: p.get('title') as string,
+            navLabel: (p.get('navLabel') as string) ?? null,
+            navOrder: (p.get('navOrder') as number) ?? 0,
+            icon: (p.get('icon') as string) ?? null,
+        }));
+
+        return jsonResponse({ pages: navPages });
+    } catch (err: unknown) {
+        console.error('[pages/nav] Failed:', err);
+        return errorResponse((err as Error).message ?? 'Failed to load nav pages', 500);
+    }
+}
+
+// ── Default seed content for homepage ───────────────────────────────────────
+
+const SEED_SECTIONS = [
+    {
+        slot: 'navbar',
+        title: 'Ottabase',
+        subtitle: null,
+        body: null,
+        variant: 'default',
+        githubUrl: 'https://github.com/thinkdj/ottabase',
+        icon: 'Navigation',
+        imageUrl: null,
+        enabled: true,
+        sortOrder: 0,
+    },
+    {
+        slot: 'hero',
+        title: 'Ottabase Homepage',
+        subtitle: 'Ship a themed, edge-deployed homepage on Cloudflare Workers in minutes.',
+        body: null,
+        variant: 'centered',
+        githubUrl: null,
+        icon: 'Sparkles',
+        imageUrl: null,
+        enabled: true,
+        sortOrder: 1,
+    },
+    {
+        slot: 'features',
+        title: 'Why Ottabase?',
+        subtitle: null,
+        body: null,
+        variant: 'grid',
+        githubUrl: null,
+        icon: 'Grid3X3',
+        imageUrl: null,
+        enabled: true,
+        sortOrder: 2,
+    },
+    {
+        slot: 'cta',
+        title: 'Ready to Ship?',
+        subtitle: 'Clone the template, customize the brand, and deploy to Cloudflare Workers in minutes.',
+        body: null,
+        variant: 'default',
+        githubUrl: null,
+        icon: 'Megaphone',
+        imageUrl: null,
+        enabled: true,
+        sortOrder: 3,
+    },
+    {
+        slot: 'about',
+        title: 'About Ottabase',
+        subtitle: 'A modern full-stack framework for edge-first applications.',
+        body: null,
+        variant: 'default',
+        githubUrl: 'https://github.com/thinkdj/ottabase',
+        icon: 'FileText',
+        imageUrl: null,
+        enabled: true,
+        sortOrder: 4,
+    },
+    {
+        slot: 'footer',
+        title: 'Ottabase',
+        subtitle: 'Built with Next.js & Cloudflare Workers',
+        body: null,
+        variant: 'default',
+        githubUrl: null,
+        icon: 'Rows3',
+        imageUrl: null,
+        enabled: true,
+        sortOrder: 5,
+    },
+];
+
+const SEED_FEATURES = [
+    { title: 'Cloudflare Workers', description: 'Edge-deployed via OpenNext. No origin server needed.', icon: 'Globe' },
+    { title: 'Brand Engine', description: '8 theme presets with live switching and dark mode.', icon: 'Palette' },
+    { title: 'Next.js 16', description: 'App Router, RSC, and streaming out of the box.', icon: 'Zap' },
+    { title: 'TypeScript', description: 'End-to-end type safety across client and server.', icon: 'Shield' },
+    {
+        title: 'OttaORM',
+        description: 'Fat model system with auto-migrations, relationships, and CRUD.',
+        icon: 'Database',
+    },
+    {
+        title: 'Admin Dashboard',
+        description: 'Full admin UI for content, users, and settings management.',
+        icon: 'LayoutDashboard',
+    },
+];
+
+const SEED_HERO_ACTIONS = [
+    { label: 'About', href: '/about', variant: 'default', icon: null, external: false, sortOrder: 0 },
+    { label: 'Theme Demo', href: '/theme-demo', variant: 'secondary', icon: 'Palette', external: false, sortOrder: 1 },
+    {
+        label: 'GitHub',
+        href: 'https://github.com/thinkdj/ottabase',
+        variant: 'outline',
+        icon: 'Github',
+        external: true,
+        sortOrder: 2,
+    },
+];
+
+const SEED_CTA_ACTIONS = [
+    {
+        label: 'Get Started',
+        href: 'https://github.com/thinkdj/ottabase',
+        variant: 'default',
+        icon: 'Rocket',
+        external: true,
+        sortOrder: 0,
+    },
+    { label: 'Explore Themes', href: '/theme-demo', variant: 'outline', icon: null, external: false, sortOrder: 1 },
+];
+
+/**
+ * POST /api/pages/seed
+ *
+ * Seeds default homepage content. Creates a "homepage" page with slug "homepage"
+ * and all the standard sections, features, and actions.
+ * Skips seeding if the homepage already exists. Idempotent.
+ */
+export async function handlePagesSeed(context: PagesRouteContext): Promise<Response> {
+    const { env, url, request } = context;
+
+    if (request.method !== 'POST') {
+        return errorResponse('Method not allowed', 405);
+    }
+
+    const d1Error = ensureD1(env);
+    if (d1Error) return d1Error;
+    registerConnection('default', createD1Driver(env.OBCF_D1));
+
+    const appId = url.searchParams.get('appId') || null;
+
+    try {
+        // Check if homepage already exists
+        const pageWhere: Record<string, unknown> = { slug: 'homepage' };
+        if (appId) pageWhere.appId = appId;
+
+        const existing = await Page.where(pageWhere);
+        if (existing.length > 0) {
+            return jsonResponse({
+                success: true,
+                seeded: false,
+                message: 'Homepage page already exists. Skipping seed.',
+            });
+        }
+
+        // Create the homepage page
+        const homepage = await Page.create({
+            slug: 'homepage',
+            title: 'Homepage',
+            type: 'block',
+            status: 'published',
+            themePreset: 'neo',
+            variantBySlotJson: {
+                navbar: 'default',
+                hero: 'centered',
+                features: 'grid',
+                cta: 'default',
+                footer: 'default',
+                about: 'default',
+            },
+            showInNav: false, // Homepage itself not shown in nav
+            navOrder: 0,
+            ...(appId ? { appId } : {}),
+        });
+
+        const pageId = homepage.get('id') as string;
+
+        // Create sections
+        const sectionMap: Record<string, string> = {}; // slot → id
+        for (const s of SEED_SECTIONS) {
+            const record = await PageSection.create({
+                pageId,
+                ...s,
+                cssClasses: null,
+                metadata: null,
+                ...(appId ? { appId } : {}),
+            });
+            sectionMap[s.slot] = record.get('id') as string;
+        }
+
+        // Create features for the "features" section
+        const featuresSectionId = sectionMap.features;
+        if (featuresSectionId) {
+            for (let i = 0; i < SEED_FEATURES.length; i++) {
+                await PageFeature.create({
+                    sectionId: featuresSectionId,
+                    title: SEED_FEATURES[i].title,
+                    description: SEED_FEATURES[i].description,
+                    icon: SEED_FEATURES[i].icon,
+                    imageUrl: null,
+                    href: null,
+                    sortOrder: i,
+                    ...(appId ? { appId } : {}),
+                });
+            }
+        }
+
+        // Create hero actions
+        const heroSectionId = sectionMap.hero;
+        if (heroSectionId) {
+            for (const a of SEED_HERO_ACTIONS) {
+                await PageAction.create({
+                    sectionId: heroSectionId,
+                    ...a,
+                    ...(appId ? { appId } : {}),
+                });
+            }
+        }
+
+        // Create CTA actions
+        const ctaSectionId = sectionMap.cta;
+        if (ctaSectionId) {
+            for (const a of SEED_CTA_ACTIONS) {
+                await PageAction.create({
+                    sectionId: ctaSectionId,
+                    ...a,
+                    ...(appId ? { appId } : {}),
+                });
+            }
+        }
+
+        return jsonResponse({
+            success: true,
+            seeded: true,
+            pageId,
+            sections: Object.keys(sectionMap).length,
+            features: SEED_FEATURES.length,
+            actions: SEED_HERO_ACTIONS.length + SEED_CTA_ACTIONS.length,
+        });
+    } catch (err: unknown) {
+        console.error('[pages/seed] Failed:', err);
+        return errorResponse((err as Error).message ?? 'Seed failed', 500);
+    }
+}
+
+/**
+ * GET /api/pages
+ *
+ * Returns a list of all pages (for admin purposes).
+ * Note: This is admin-accessible via generic OttaORM CRUD, but we provide
+ * a public-friendly version here that only shows published pages.
+ */
+export async function handlePagesList(context: PagesRouteContext): Promise<Response> {
+    const { env, url } = context;
+    const d1Error = ensureD1(env);
+    if (d1Error) return d1Error;
+    registerConnection('default', createD1Driver(env.OBCF_D1));
+
+    const appId = url.searchParams.get('appId') || null;
+    const includeAll = url.searchParams.get('all') === 'true'; // Admin flag
+
+    try {
+        const where: Record<string, unknown> = {};
+        if (appId) where.appId = appId;
+        if (!includeAll) where.status = 'published';
+
+        const pages = await Page.where(where, { orderBy: 'createdAt', orderDirection: 'desc' });
+
+        const list = pages.map((p) => ({
+            id: p.get('id') as string,
+            slug: p.get('slug') as string,
+            title: p.get('title') as string,
+            type: p.get('type') as string,
+            status: p.get('status') as string,
+            showInNav: (p.get('showInNav') as boolean) ?? false,
+            navOrder: (p.get('navOrder') as number) ?? 0,
+            createdAt: p.get('createdAt') as string,
+            updatedAt: p.get('updatedAt') as string,
+        }));
+
+        return jsonResponse({ pages: list });
+    } catch (err: unknown) {
+        console.error('[pages] Failed:', err);
+        return errorResponse((err as Error).message ?? 'Failed to load pages', 500);
+    }
+}
diff --git a/apps/ottabase-template-app-tanstack/worker/routes/router.ts b/apps/ottabase-template-app-tanstack/worker/routes/router.ts
index 68c5cd1d9..3862eced7 100644
--- a/apps/ottabase-template-app-tanstack/worker/routes/router.ts
+++ b/apps/ottabase-template-app-tanstack/worker/routes/router.ts
@@ -66,9 +66,8 @@ import {
     handleBlogTagBySlug,
     handleExposedPages,
 } from './blog';
-import { handleChangelogEntriesList, handleChangelogEntryBySlug } from './changelog';
 import { handleBrandApi } from './brand';
-import { handleHomepageData, handleHomepageSeed } from './homepage';
+import { handleChangelogEntriesList, handleChangelogEntryBySlug } from './changelog';
 import {
     handleAIChat,
     handleAIGatewayChat,
@@ -90,8 +89,10 @@ import {
 import { handleCoreAnalytics } from './core-analytics';
 import { handleAuditLogs, handleDemo, handleDemoError } from './demo';
 import { handleEmailProviders, handleEmailTest } from './email';
+import { handleHomepageData, handleHomepageSeed } from './homepage';
 import { handleOttaormCrud } from './ottaorm-crud';
 import { handleModelsMetadata, handleOttaormInit } from './ottaorm-init';
+import { handleNavPages, handlePageBySlug, handlePagesList, handlePagesSeed } from './pages';
 import {
     handleReferralStats,
     handleReferralTrack,
@@ -183,15 +184,43 @@ async function handleGetRoutes(context: ApiRouteContext): Promise<Response | nul
     }
 
     // Homepage public data (sections + display settings + exposed pages)
+    // Legacy: prefer /api/pages/homepage for new integrations
     if (route === '/api/homepage/data') {
         return handleHomepageData(context);
     }
 
     // Homepage seed (creates demo content)
+    // Legacy: prefer /api/pages/seed for new integrations
     if (route === '/api/homepage/seed') {
         return handleHomepageSeed(context);
     }
 
+    // ── New flexible pages system ──────────────────────────────────────
+    // GET /api/pages — list all pages
+    if (route === '/api/pages' && request.method === 'GET') {
+        return handlePagesList(context);
+    }
+
+    // GET /api/pages/nav — nav-enabled pages for menus
+    if (route === '/api/pages/nav') {
+        return handleNavPages(context);
+    }
+
+    // POST /api/pages/seed — seed default homepage
+    if (route === '/api/pages/seed') {
+        return handlePagesSeed(context);
+    }
+
+    // GET /api/pages/:slug — page by slug (homepage, about, etc.)
+    const pageBySlugMatch = route.match(/^\/api\/pages\/([^/]+)$/);
+    if (pageBySlugMatch && request.method === 'GET') {
+        const slug = decodeURIComponent(pageBySlugMatch[1]);
+        // Skip reserved routes
+        if (slug !== 'nav' && slug !== 'seed') {
+            return handlePageBySlug(context, slug);
+        }
+    }
+
     if (route === '/api/system/kill-switches') {
         return jsonResponse({
             ...getKillSwitchStatus(context.env),
diff --git a/packages/homepage-contract/src/index.ts b/packages/homepage-contract/src/index.ts
index 1bf69bdd5..310de5713 100644
--- a/packages/homepage-contract/src/index.ts
+++ b/packages/homepage-contract/src/index.ts
@@ -1,37 +1,75 @@
 /**
  * @ottabase/homepage-contract
  *
- * Shared Zod schemas and TypeScript types for the homepage data contract.
+ * Shared Zod schemas and TypeScript types for the homepage/pages data contract.
  * Used by the TanStack worker (producer) and the Next.js app (consumer).
  *
+ * Contains both legacy homepage schemas and new flexible page system schemas.
+ *
  * @example
  * ```ts
+ * // Legacy homepage API
  * import { HomepageDataSchema, type HomepageDataPayload } from '@ottabase/homepage-contract';
- *
- * // Validate API response
  * const result = HomepageDataSchema.safeParse(raw);
  *
- * // Type-safe usage
- * const payload: HomepageDataPayload = result.data;
+ * // New flexible page system
+ * import { PageDataSchema, type PageDataPayload } from '@ottabase/homepage-contract';
+ * const page = PageDataSchema.safeParse(raw);
  * ```
  */
 
+// ============================================================================
+// LEGACY HOMEPAGE SCHEMAS (kept for backward compatibility)
+// ============================================================================
+
 // Zod schemas (runtime validation)
 export {
-    ExposedPageSchema,
-    FeatureSchema,
     ActionSchema,
-    SectionSchema,
     DisplaySchema,
+    ExposedPageSchema,
+    FeatureSchema,
     HomepageDataSchema,
+    SectionSchema,
 } from './schemas';
 
 // TypeScript types (inferred from schemas — no drift)
 export type {
     ExposedPage,
-    HomepageFeaturePayload,
     HomepageActionPayload,
-    HomepageSectionPayload,
-    HomepageDisplayPayload,
     HomepageDataPayload,
+    HomepageDisplayPayload,
+    HomepageFeaturePayload,
+    HomepageSectionPayload,
+} from './types';
+
+// ============================================================================
+// NEW FLEXIBLE PAGE SYSTEM SCHEMAS
+// ============================================================================
+
+// Zod schemas (runtime validation)
+export {
+    NavPageSchema,
+    NavPagesSchema,
+    PageActionSchema,
+    PageContentSchema,
+    PageDataSchema,
+    PageDisplaySchema,
+    PageFeatureSchema,
+    PageMetaSchema,
+    PageSectionSchema,
+    PagesListSchema,
+} from './schemas';
+
+// TypeScript types (inferred from schemas — no drift)
+export type {
+    NavPagePayload,
+    NavPagesPayload,
+    PageActionPayload,
+    PageContentPayload,
+    PageDataPayload,
+    PageDisplayPayload,
+    PageFeaturePayload,
+    PageMetaPayload,
+    PageSectionPayload,
+    PagesListPayload,
 } from './types';
diff --git a/packages/homepage-contract/src/schemas.ts b/packages/homepage-contract/src/schemas.ts
index 39b8db3fc..5545b2413 100644
--- a/packages/homepage-contract/src/schemas.ts
+++ b/packages/homepage-contract/src/schemas.ts
@@ -1,12 +1,18 @@
 /**
  * @ottabase/homepage-contract — Zod schemas
  *
- * Single source of truth for the homepage data API contract.
+ * Single source of truth for the homepage/pages data API contract.
  * Used by the TanStack worker (producer) and the Next.js app (consumer).
+ *
+ * Contains both legacy homepage schemas and new flexible page system schemas.
  */
 
 import { z } from 'zod';
 
+// ============================================================================
+// LEGACY HOMEPAGE SCHEMAS (kept for backward compatibility)
+// ============================================================================
+
 // ── Leaf schemas ────────────────────────────────────────────────────────────
 
 export const ExposedPageSchema = z.object({
@@ -66,3 +72,128 @@ export const HomepageDataSchema = z.object({
     display: DisplaySchema,
     exposedPages: z.array(ExposedPageSchema).default([]),
 });
+
+// ============================================================================
+// NEW FLEXIBLE PAGE SYSTEM SCHEMAS
+// ============================================================================
+
+// ── Page feature (within a section) ─────────────────────────────────────────
+
+export const PageFeatureSchema = z.object({
+    id: z.string(),
+    title: z.string(),
+    description: z.string(),
+    icon: z.string().nullable().optional(),
+    imageUrl: z.string().nullable().optional(),
+    href: z.string().nullable().optional(),
+});
+
+// ── Page action (CTA button within a section) ───────────────────────────────
+
+export const PageActionSchema = z.object({
+    id: z.string(),
+    label: z.string(),
+    href: z.string(),
+    variant: z.string().nullable().optional(),
+    icon: z.string().nullable().optional(),
+    external: z.boolean().optional().default(false),
+});
+
+// ── Page section (block within a page) ──────────────────────────────────────
+
+export const PageSectionSchema = z.object({
+    id: z.string(),
+    slot: z.string(),
+    title: z.string().nullable(),
+    subtitle: z.string().nullable(),
+    body: z.string().nullable(),
+    variant: z.string().nullable().optional(),
+    githubUrl: z.string().nullable().optional(),
+    icon: z.string().nullable().optional(),
+    imageUrl: z.string().nullable().optional(),
+    enabled: z.boolean().default(true),
+    cssClasses: z.string().nullable().optional(),
+    metadata: z.record(z.unknown()).nullable().optional(),
+    sortOrder: z.number().default(0),
+    features: z.array(PageFeatureSchema).default([]),
+    actions: z.array(PageActionSchema).default([]),
+});
+
+// ── Page display settings ───────────────────────────────────────────────────
+
+export const PageDisplaySchema = z.object({
+    variantBySlot: z.record(z.string()).nullable(),
+    themePreset: z.string().nullable(),
+    fallbackThemePresetId: z.string().nullable().optional(),
+    customCss: z.string().nullable().optional(),
+    seoTitle: z.string().nullable().optional(),
+    seoDescription: z.string().nullable().optional(),
+    seoImage: z.string().nullable().optional(),
+});
+
+// ── Page metadata ───────────────────────────────────────────────────────────
+
+export const PageMetaSchema = z.object({
+    id: z.string(),
+    slug: z.string(),
+    title: z.string(),
+    type: z.enum(['block', 'content']),
+    status: z.enum(['draft', 'published', 'archived']),
+    showInNav: z.boolean().default(false),
+    navOrder: z.number().default(0),
+    navLabel: z.string().nullable().optional(),
+    icon: z.string().nullable().optional(),
+});
+
+// ── Page content (for content-type pages, links to ottablog Post) ───────────
+
+export const PageContentSchema = z
+    .object({
+        title: z.string(),
+        body: z.string(),
+        excerpt: z.string().nullable().optional(),
+    })
+    .nullable();
+
+// ── Full page data payload (from GET /api/pages/:slug) ──────────────────────
+
+export const PageDataSchema = z.object({
+    page: PageMetaSchema,
+    sections: z.array(PageSectionSchema).default([]),
+    display: PageDisplaySchema,
+    content: PageContentSchema,
+});
+
+// ── Nav page (from GET /api/pages/nav) ──────────────────────────────────────
+
+export const NavPageSchema = z.object({
+    slug: z.string(),
+    title: z.string(),
+    navLabel: z.string().nullable().optional(),
+    navOrder: z.number().default(0),
+    icon: z.string().nullable().optional(),
+});
+
+// ── Pages list response ─────────────────────────────────────────────────────
+
+export const PagesListSchema = z.object({
+    pages: z.array(
+        z.object({
+            id: z.string(),
+            slug: z.string(),
+            title: z.string(),
+            type: z.enum(['block', 'content']),
+            status: z.enum(['draft', 'published', 'archived']),
+            showInNav: z.boolean().default(false),
+            navOrder: z.number().default(0),
+            createdAt: z.string(),
+            updatedAt: z.string(),
+        }),
+    ),
+});
+
+// ── Nav pages response ──────────────────────────────────────────────────────
+
+export const NavPagesSchema = z.object({
+    pages: z.array(NavPageSchema),
+});
diff --git a/packages/homepage-contract/src/types.ts b/packages/homepage-contract/src/types.ts
index 959fc11e3..f8623758b 100644
--- a/packages/homepage-contract/src/types.ts
+++ b/packages/homepage-contract/src/types.ts
@@ -2,18 +2,35 @@
  * @ottabase/homepage-contract — TypeScript types
  *
  * All types are inferred from the Zod schemas so there is no drift.
+ * Contains both legacy homepage types and new flexible page system types.
  */
 
 import type { z } from 'zod';
 import type {
-    ExposedPageSchema,
-    FeatureSchema,
     ActionSchema,
-    SectionSchema,
     DisplaySchema,
+    // Legacy homepage schemas
+    ExposedPageSchema,
+    FeatureSchema,
     HomepageDataSchema,
+    NavPageSchema,
+    NavPagesSchema,
+    PageActionSchema,
+    PageContentSchema,
+    PageDataSchema,
+    PageDisplaySchema,
+    // New flexible page system schemas
+    PageFeatureSchema,
+    PageMetaSchema,
+    PageSectionSchema,
+    PagesListSchema,
+    SectionSchema,
 } from './schemas';
 
+// ============================================================================
+// LEGACY HOMEPAGE TYPES (kept for backward compatibility)
+// ============================================================================
+
 /** Exposed page link for homepage navbar */
 export type ExposedPage = z.infer<typeof ExposedPageSchema>;
 
@@ -31,3 +48,37 @@ export type HomepageDisplayPayload = z.infer<typeof DisplaySchema>;
 
 /** Full homepage data payload from GET /api/homepage/data */
 export type HomepageDataPayload = z.infer<typeof HomepageDataSchema>;
+
+// ============================================================================
+// NEW FLEXIBLE PAGE SYSTEM TYPES
+// ============================================================================
+
+/** Feature item within a page section */
+export type PageFeaturePayload = z.infer<typeof PageFeatureSchema>;
+
+/** Action button (CTA) within a page section */
+export type PageActionPayload = z.infer<typeof PageActionSchema>;
+
+/** Page section (block within a page) */
+export type PageSectionPayload = z.infer<typeof PageSectionSchema>;
+
+/** Page display settings (variants, theme, SEO) */
+export type PageDisplayPayload = z.infer<typeof PageDisplaySchema>;
+
+/** Page metadata */
+export type PageMetaPayload = z.infer<typeof PageMetaSchema>;
+
+/** Page content (for content-type pages linking to ottablog Post) */
+export type PageContentPayload = z.infer<typeof PageContentSchema>;
+
+/** Full page data payload from GET /api/pages/:slug */
+export type PageDataPayload = z.infer<typeof PageDataSchema>;
+
+/** Nav page item from GET /api/pages/nav */
+export type NavPagePayload = z.infer<typeof NavPageSchema>;
+
+/** Pages list response from GET /api/pages */
+export type PagesListPayload = z.infer<typeof PagesListSchema>;
+
+/** Nav pages response from GET /api/pages/nav */
+export type NavPagesPayload = z.infer<typeof NavPagesSchema>;
diff --git a/pnpm-lock.yaml b/pnpm-lock.yaml
index 9570253ec..8f0c091ad 100644
--- a/pnpm-lock.yaml
+++ b/pnpm-lock.yaml
@@ -471,6 +471,15 @@ importers:
       '@auth/core':
         specifier: 'catalog:'
         version: 0.34.3(nodemailer@7.0.12)
+      '@dnd-kit/core':
+        specifier: ^6.3.1
+        version: 6.3.1(react-dom@19.2.4(react@19.2.4))(react@19.2.4)
+      '@dnd-kit/sortable':
+        specifier: ^10.0.0
+        version: 10.0.0(@dnd-kit/core@6.3.1(react-dom@19.2.4(react@19.2.4))(react@19.2.4))(react@19.2.4)
+      '@dnd-kit/utilities':
+        specifier: ^3.2.2
+        version: 3.2.2(react@19.2.4)
       '@hookform/resolvers':
         specifier: 'catalog:'
         version: 3.10.0(react-hook-form@7.70.0(react@19.2.4))
@@ -3860,6 +3869,28 @@ packages:
   '@date-fns/tz@1.4.1':
     resolution: {integrity: sha512-P5LUNhtbj6YfI3iJjw5EL9eUAG6OitD0W3fWQcpQjDRc/QIsL0tRNuO1PcDvPccWL1fSTXXdE1ds+l95DV/OFA==}
 
+  '@dnd-kit/accessibility@3.1.1':
+    resolution: {integrity: sha512-2P+YgaXF+gRsIihwwY1gCsQSYnu9Zyj2py8kY5fFvUM1qm2WA2u639R6YNVfU4GWr+ZM5mqEsfHZZLoRONbemw==}
+    peerDependencies:
+      react: '>=16.8.0'
+
+  '@dnd-kit/core@6.3.1':
+    resolution: {integrity: sha512-xkGBRQQab4RLwgXxoqETICr6S5JlogafbhNsidmrkVv2YRs5MLwpjoF2qpiGjQt8S9AoxtIV603s0GIUpY5eYQ==}
+    peerDependencies:
+      react: '>=16.8.0'
+      react-dom: '>=16.8.0'
+
+  '@dnd-kit/sortable@10.0.0':
+    resolution: {integrity: sha512-+xqhmIIzvAYMGfBYYnbKuNicfSsk4RksY2XdmJhT+HAC01nix6fHCztU68jooFiMUB01Ky3F0FyOvhG/BZrWkg==}
+    peerDependencies:
+      '@dnd-kit/core': ^6.3.0
+      react: '>=16.8.0'
+
+  '@dnd-kit/utilities@3.2.2':
+    resolution: {integrity: sha512-+MKAJEOfaBe5SmV6t34p80MMKhjvUz0vRrvVJbPT0WElzaOJ/1xs+D+KDv+tD/NE5ujfrChEcshd4fLn0wpiqg==}
+    peerDependencies:
+      react: '>=16.8.0'
+
   '@dotenvx/dotenvx@1.31.0':
     resolution: {integrity: sha512-GeDxvtjiRuoyWVU9nQneId879zIyNdL05bS7RKiqMkfBSKpHMWHLoRyRqjYWLaXmX/llKO1hTlqHDmatkQAjPA==}
     hasBin: true
@@ -14426,6 +14457,31 @@ snapshots:
 
   '@date-fns/tz@1.4.1': {}
 
+  '@dnd-kit/accessibility@3.1.1(react@19.2.4)':
+    dependencies:
+      react: 19.2.4
+      tslib: 2.8.1
+
+  '@dnd-kit/core@6.3.1(react-dom@19.2.4(react@19.2.4))(react@19.2.4)':
+    dependencies:
+      '@dnd-kit/accessibility': 3.1.1(react@19.2.4)
+      '@dnd-kit/utilities': 3.2.2(react@19.2.4)
+      react: 19.2.4
+      react-dom: 19.2.4(react@19.2.4)
+      tslib: 2.8.1
+
+  '@dnd-kit/sortable@10.0.0(@dnd-kit/core@6.3.1(react-dom@19.2.4(react@19.2.4))(react@19.2.4))(react@19.2.4)':
+    dependencies:
+      '@dnd-kit/core': 6.3.1(react-dom@19.2.4(react@19.2.4))(react@19.2.4)
+      '@dnd-kit/utilities': 3.2.2(react@19.2.4)
+      react: 19.2.4
+      tslib: 2.8.1
+
+  '@dnd-kit/utilities@3.2.2(react@19.2.4)':
+    dependencies:
+      react: 19.2.4
+      tslib: 2.8.1
+
   '@dotenvx/dotenvx@1.31.0':
     dependencies:
       commander: 11.1.0

From d9a7d1576a4f4677e3d3008c65979bf9bedf0fcc Mon Sep 17 00:00:00 2001
From: Deepak Thomas <think.dj@gmail.com>
Date: Tue, 31 Mar 2026 22:59:40 +0530
Subject: [PATCH 19/19] SPECS MD: Add Marketing Pages feature specification

Add comprehensive marketing pages design docs: a full feature specification and an optimized version (docs/MARKETING_PAGES_FEATURE_SPEC.md, docs/MARKETING_PAGES_FEATURE_SPEC_OPTIMIZED.md). The spec covers architecture, DB schema (pages, page_sections, page_features, page_actions), OttaORM models and hooks, public/admin APIs, contract package (Zod + TS types), admin drag-and-drop builder, Next.js frontend rendering/SlotRenderer, variant components, routing, and implementation/checklist details.
---
 docs/MARKETING_PAGES_FEATURE_SPEC.md          | 4117 +++++++++++++++++
 .../MARKETING_PAGES_FEATURE_SPEC_OPTIMIZED.md | 1116 +++++
 2 files changed, 5233 insertions(+)
 create mode 100644 docs/MARKETING_PAGES_FEATURE_SPEC.md
 create mode 100644 docs/MARKETING_PAGES_FEATURE_SPEC_OPTIMIZED.md

diff --git a/docs/MARKETING_PAGES_FEATURE_SPEC.md b/docs/MARKETING_PAGES_FEATURE_SPEC.md
new file mode 100644
index 000000000..ad696aa16
--- /dev/null
+++ b/docs/MARKETING_PAGES_FEATURE_SPEC.md
@@ -0,0 +1,4117 @@
+# Marketing Pages System — Complete Feature Specification
+
+> **Purpose**: End-to-end technical and UX specification for building a drag-and-drop marketing page builder with
+> database-driven block rendering.
+
+---
+
+## Table of Contents
+
+| Section  | Title                                                                             | What It Covers                          |
+| -------- | --------------------------------------------------------------------------------- | --------------------------------------- |
+| 1        | [Executive Summary](#1-executive-summary)                                         | Overview, key capabilities              |
+| 2        | [Architecture Overview](#2-architecture-overview)                                 | System diagram, data flow               |
+| 3        | [Database Schema](#3-database-schema)                                             | 4 tables, columns, indexes              |
+| 4        | [OttaORM Models](#4-ottaorm-models)                                               | Model classes, static methods           |
+| 5        | [API Routes](#5-api-routes)                                                       | Public & admin endpoints                |
+| 6        | [Contract Package](#6-contract-package)                                           | Zod schemas, TypeScript types           |
+| 7        | [Admin UI — Page Builder](#7-admin-ui--page-builder)                              | Builder layout, components              |
+| 8        | [Next.js Frontend Rendering](#8-nextjs-frontend-rendering)                        | Dynamic routes, SlotRenderer            |
+| **8.5**  | **[Block Registry System](#85-block-registry-system)**                            | **Dynamic block registration**          |
+| **8.6**  | **[Component Discovery API](#86-component-discovery-api)**                        | **Apps expose custom blocks via API**   |
+| **8.7**  | **[Split-Pane Preview Architecture](#87-split-pane-preview-architecture)**        | **Real-time preview for builders**      |
+| **8.8**  | **[Extensibility & Custom Blocks](#88-extensibility--custom-blocks)**             | **How apps register custom components** |
+| 9        | [UX Flows](#9-ux-flows)                                                           | User journeys (create, edit, publish)   |
+| 10       | [Implementation Checklist](#10-implementation-checklist)                          | Phase-by-phase task list                |
+| **10.5** | **[UX/DX Enhancements](#105-uxdx-enhancements)**                                  | **Inline editing, undo/redo, hotkeys**  |
+| **10.6** | **[Quick UX Wins](#106-quick-ux-wins-highest-impact-low-effort)**                 | **2-3 hour improvements**               |
+| 11       | [File Paths Summary](#11-file-paths-summary)                                      | Every file location                     |
+| 12       | [Key Technical Decisions](#12-key-technical-decisions)                            | Decision rationale table                |
+| 13       | [Future Enhancements](#13-future-enhancements)                                    | Roadmap ideas                           |
+| **14**   | **[Problem Statement & Why This Exists](#14-problem-statement--why-this-exists)** | **Motivation, success criteria**        |
+| **15**   | **[Design Principles](#15-design-principles)**                                    | **Core architectural philosophy**       |
+| **16**   | **[State Management Strategy](#16-state-management-strategy)**                    | **Data flow, mutation strategies**      |
+| **17**   | **[Error Handling Matrix](#17-error-handling-matrix)**                            | **All error codes, validation rules**   |
+| **18**   | **[Performance Considerations](#18-performance-considerations)**                  | **Caching, lazy loading, targets**      |
+| **19**   | **[Security Considerations](#19-security-considerations)**                        | **Auth, RBAC, sanitization**            |
+| **20**   | **[Testing Strategy](#20-testing-strategy)**                                      | **Unit, integration, E2E tests**        |
+| **21**   | **[Debugging Guide](#21-debugging-guide)**                                        | **Common issues, logging, SQL**         |
+| **22**   | **[Adding New Block Types](#22-adding-new-block-types)**                          | **Step-by-step migration guide**        |
+| **23**   | **[Keyboard Shortcuts & Accessibility](#23-keyboard-shortcuts--accessibility)**   | **A11y requirements**                   |
+| **24**   | **[Cache Invalidation Strategy](#24-cache-invalidation-strategy)**                | **When/how to invalidate**              |
+| **25**   | **[Rollback & Recovery Procedures](#25-rollback--recovery-procedures)**           | **Undo, restore, backup**               |
+| **26**   | **[Multi-Tenant Considerations](#26-multi-tenant-considerations)**                | **App isolation, templates**            |
+| **27**   | **[Analytics Integration](#27-analytics-integration)**                            | **Tracking page views, clicks**         |
+| **28**   | **[API Reference](#28-api-reference-openapi-summary)**                            | **All endpoints, examples**             |
+| **29**   | **[Glossary](#29-glossary)**                                                      | **Term definitions**                    |
+
+---
+
+## 1. Executive Summary
+
+Build a flexible, database-driven marketing page system that allows non-technical users to create and manage landing
+pages via a drag-and-drop interface. Pages are composed of reusable **blocks** (hero, features, CTA, etc.) that support
+multiple **variants** (centered, split, grid, etc.).
+
+### Key Capabilities
+
+- **Admin UI**: Drag-and-drop page builder with block palette, sortable canvas, and inline editing
+- **Block System**: 15+ block types with multiple visual variants each
+- **Preview Mode**: Live preview of draft pages before publishing
+- **Multi-tenant**: Each page scoped to an `appId` for SaaS deployments
+- **SEO Ready**: Per-page metadata (title, description, OG image)
+- **Type-Safe**: Shared contract package with Zod validation + TypeScript types
+
+---
+
+## 2. Architecture Overview
+
+```
+┌─────────────────────────────────────────────────────────────────────────────┐
+│                              ADMIN UI (TanStack)                            │
+│  ┌─────────────────┐  ┌─────────────────────────┐  ┌────────────────────┐   │
+│  │  Block Library  │  │       Canvas            │  │   Block Editor     │   │
+│  │  (15+ blocks)   │  │  (sortable, DnD)        │  │  (sheet panel)     │   │
+│  └─────────────────┘  └─────────────────────────┘  └────────────────────┘   │
+└────────────────────────────────────┬────────────────────────────────────────┘
+                                     │ OttaORM CRUD Hooks
+                                     ▼
+┌─────────────────────────────────────────────────────────────────────────────┐
+│                          WORKER API (Cloudflare)                            │
+│  ┌─────────────────────────────────────────────────────────────────────┐    │
+│  │  /api/ottaorm/{pages,page_sections,page_features,page_actions}      │    │
+│  │  /api/pages/:slug — Public page data (sections + features + actions)│    │
+│  │  /api/pages/nav — Nav-enabled pages                                 │    │
+│  │  /api/pages/seed — Idempotent homepage seed                         │    │
+│  └─────────────────────────────────────────────────────────────────────┘    │
+└────────────────────────────────────┬────────────────────────────────────────┘
+                                     │ D1 SQLite
+                                     ▼
+┌─────────────────────────────────────────────────────────────────────────────┐
+│                              DATABASE (4 tables)                            │
+│  pages → page_sections → page_features                                      │
+│                        → page_actions                                       │
+└────────────────────────────────────┬────────────────────────────────────────┘
+                                     │
+          ┌──────────────────────────┴──────────────────────────┐
+          │                                                     │
+          ▼                                                     ▼
+┌─────────────────────────┐                       ┌──────────────────────────┐
+│  Contract Package       │                       │  Next.js Homepage        │
+│  @ottabase/homepage-    │                       │  apps/nextjs-homepage/   │
+│  contract               │                       │                          │
+│  - Zod schemas          │  ────imports────▶     │  /api fetch              │
+│  - TypeScript types     │                       │  SlotRenderer            │
+│  - No drift guarantee   │                       │  Variant Components      │
+└─────────────────────────┘                       └──────────────────────────┘
+```
+
+---
+
+## 3. Database Schema
+
+### 3.1 `pages` Table
+
+Main page entity with metadata, SEO, theming, and nav configuration.
+
+```typescript
+// File: ottabase/models/Page.schema.ts
+export const pagesTable = sqliteTable('pages', {
+    // Identity
+    id: text('id').primaryKey().$defaultFn(() => crypto.randomUUID()),
+    slug: text('slug').notNull().unique(), // URL path: "homepage", "pricing", "about"
+    title: text('title').notNull(),
+
+    // Type & Status
+    type: text('type').$type<'block' | 'content'>().notNull().default('block'),
+    status: text('status').$type<'draft' | 'published' | 'archived'>().notNull().default('draft'),
+
+    // For content-type pages (links to ottablog Post)
+    postId: text('post_id'), // FK to posts table
+
+    // Theme & Styling
+    themePreset: text('theme_preset'), // "default", "dark", "minimal"
+    fallbackThemePresetId: text('fallback_theme_preset_id'), // Fallback theme if primary not found
+    customCss: text('custom_css'),
+    variantBySlotJson: text('variant_by_slot_json', { mode: 'json' }).$type<Record<string, string>>(),
+    // Example: { "hero": "split", "features": "cards", "footer": "minimal" }
+
+    // SEO
+    seoTitle: text('seo_title'),
+    seoDescription: text('seo_description'),
+    seoKeywords: text('seo_keywords'),
+
+    // Navigation
+    showInNav: integer('show_in_nav', { mode: 'boolean' }).notNull().default(false),
+    navOrder: integer('nav_order').notNull().default(100), // Lower = earlier
+    navLabel: text('nav_label'), // Defaults to title if null
+    icon: text('icon'), // Lucide icon name
+
+    // Extensibility
+    metadata: text('metadata', { mode: 'json' }).$type<Record<string, unknown>>(),
+    appId: text('app_id'), // Multi-tenant
+
+    // Timestamps
+    createdAt: integer('created_at').$defaultFn(() => Date.now()).notNull(),
+    updatedAt: integer('updated_at').$defaultFn(() => Date.now()).$onUpdateFn(() => Date.now()).notNull(),
+});
+
+// Indexes
+index('pages_slug_idx').on(table.slug),
+index('pages_status_idx').on(table.status),
+index('pages_nav_idx').on(table.showInNav, table.navOrder),
+index('pages_app_idx').on(table.appId),
+```
+
+### 3.2 `page_sections` Table
+
+Building blocks within pages. Each section = one block in the builder.
+
+```typescript
+// File: ottabase/models/PageSection.schema.ts
+export type SlotType =
+    | 'navbar'
+    | 'hero'
+    | 'features'
+    | 'cta'
+    | 'footer'
+    | 'about'
+    | 'pricing'
+    | 'testimonials'
+    | 'gallery'
+    | 'team'
+    | 'faq'
+    | 'video'
+    | 'code'
+    | 'contact'
+    | 'custom';
+
+export const pageSectionsTable = sqliteTable('page_sections', {
+    id: text('id')
+        .primaryKey()
+        .$defaultFn(() => crypto.randomUUID()),
+
+    // Parent page (CASCADE delete)
+    pageId: text('page_id')
+        .notNull()
+        .references(() => pagesTable.id, { onDelete: 'cascade' }),
+
+    // Block type determines rendering component
+    slot: text('slot').$type<SlotType>().notNull(),
+
+    // Content
+    title: text('title'),
+    subtitle: text('subtitle'),
+    body: text('body'), // Markdown or HTML
+
+    // Visual
+    icon: text('icon'), // Lucide icon name
+    imageUrl: text('image_url'),
+    videoUrl: text('video_url'),
+    githubUrl: text('github_url'), // For nav/footer
+    logoUrl: text('logo_url'),
+
+    // Variant selection (e.g., "centered", "split", "grid")
+    variant: text('variant'),
+
+    // Styling
+    cssClasses: text('css_classes'),
+    backgroundColor: text('background_color'),
+
+    // Control
+    enabled: integer('enabled', { mode: 'boolean' }).notNull().default(true),
+    sortOrder: integer('sort_order').notNull().default(0),
+
+    metadata: text('metadata', { mode: 'json' }).$type<Record<string, unknown>>(),
+    createdAt: integer('created_at')
+        .$defaultFn(() => Date.now())
+        .notNull(),
+    updatedAt: integer('updated_at')
+        .$defaultFn(() => Date.now())
+        .$onUpdateFn(() => Date.now())
+        .notNull(),
+});
+```
+
+### 3.3 `page_features` Table
+
+Feature items within sections (for features grid, pricing cards, FAQ items, team members, etc.).
+
+```typescript
+// File: ottabase/models/PageFeature.schema.ts
+export const pageFeaturesTable = sqliteTable('page_features', {
+    id: text('id')
+        .primaryKey()
+        .$defaultFn(() => crypto.randomUUID()),
+
+    // Parent section (CASCADE delete)
+    sectionId: text('section_id')
+        .notNull()
+        .references(() => pageSectionsTable.id, { onDelete: 'cascade' }),
+
+    // Content
+    title: text('title').notNull(),
+    description: text('description'),
+
+    // Visual
+    icon: text('icon'),
+    imageUrl: text('image_url'),
+
+    // Link (optional)
+    href: text('href'),
+    external: integer('external', { mode: 'boolean' }).default(false),
+
+    sortOrder: integer('sort_order').notNull().default(0),
+
+    createdAt: integer('created_at')
+        .$defaultFn(() => Date.now())
+        .notNull(),
+    updatedAt: integer('updated_at')
+        .$defaultFn(() => Date.now())
+        .$onUpdateFn(() => Date.now())
+        .notNull(),
+});
+```
+
+### 3.4 `page_actions` Table
+
+CTA buttons within sections (hero buttons, CTA section buttons, etc.).
+
+```typescript
+// File: ottabase/models/PageAction.schema.ts
+export type ActionVariant = 'default' | 'primary' | 'secondary' | 'outline' | 'ghost' | 'destructive' | 'link';
+
+export const pageActionsTable = sqliteTable('page_actions', {
+    id: text('id')
+        .primaryKey()
+        .$defaultFn(() => crypto.randomUUID()),
+
+    // Parent section (CASCADE delete)
+    sectionId: text('section_id')
+        .notNull()
+        .references(() => pageSectionsTable.id, { onDelete: 'cascade' }),
+
+    // Button content
+    label: text('label').notNull(),
+    href: text('href').notNull(),
+
+    // Styling
+    variant: text('variant').$type<ActionVariant>().default('default'),
+    icon: text('icon'),
+
+    external: integer('external', { mode: 'boolean' }).default(false),
+    sortOrder: integer('sort_order').notNull().default(0),
+
+    createdAt: integer('created_at')
+        .$defaultFn(() => Date.now())
+        .notNull(),
+    updatedAt: integer('updated_at')
+        .$defaultFn(() => Date.now())
+        .$onUpdateFn(() => Date.now())
+        .notNull(),
+});
+```
+
+### 3.5 Entity Relationship
+
+```
+pages (1) ─────────< page_sections (many)
+                         │
+                         ├────< page_features (many)
+                         │
+                         └────< page_actions (many)
+
+Cascade deletes: Deleting a page deletes all its sections.
+                 Deleting a section deletes all its features & actions.
+```
+
+---
+
+## 4. OttaORM Models
+
+### 4.1 Page Model
+
+```typescript
+// File: ottabase/models/Page.ts
+import { BaseModel } from '@ottabase/ottaorm';
+import { pagesTable } from './Page.schema';
+
+export class Page extends BaseModel {
+    static entity = 'pages';
+    static table = pagesTable;
+    static primaryKey = 'id';
+
+    static casts = {
+        showInNav: 'boolean',
+        createdAt: 'integer',
+        updatedAt: 'integer',
+    };
+
+    // ── Static Methods ──
+
+    static async getHomepage(): Promise<Page | null> {
+        const results = await this.where({ slug: 'homepage', status: 'published' });
+        return results[0] || null;
+    }
+
+    static async getNavPages(): Promise<Page[]> {
+        return this.where({ showInNav: true, status: 'published' }).orderBy('navOrder', 'asc');
+    }
+
+    static async getBySlug(slug: string): Promise<Page | null> {
+        const results = await this.where({ slug });
+        return results[0] || null;
+    }
+
+    // ── Computed Properties ──
+
+    get isHomepage(): boolean {
+        return this.get('slug') === 'homepage';
+    }
+
+    get displayNavLabel(): string {
+        return this.get('navLabel') || this.get('title') || '';
+    }
+}
+```
+
+### 4.2 PageSection Model
+
+```typescript
+// File: ottabase/models/PageSection.ts
+import { BaseModel } from '@ottabase/ottaorm';
+import { pageSectionsTable } from './PageSection.schema';
+
+export class PageSection extends BaseModel {
+    static entity = 'page_sections';
+    static table = pageSectionsTable;
+    static primaryKey = 'id';
+
+    static casts = {
+        enabled: 'boolean',
+        sortOrder: 'integer',
+        createdAt: 'integer',
+        updatedAt: 'integer',
+    };
+
+    static async getForPage(pageId: string): Promise<PageSection[]> {
+        return this.where({ pageId }).orderBy('sortOrder', 'asc');
+    }
+
+    static async getEnabledForPage(pageId: string): Promise<PageSection[]> {
+        return this.where({ pageId, enabled: true }).orderBy('sortOrder', 'asc');
+    }
+}
+```
+
+### 4.3 PageAction & PageFeature Models
+
+```typescript
+// File: ottabase/models/PageAction.ts
+export class PageAction extends BaseModel {
+    static entity = 'page_actions';
+    static table = pageActionsTable;
+    static primaryKey = 'id';
+
+    static async getForSection(sectionId: string): Promise<PageAction[]> {
+        return this.where({ sectionId }).orderBy('sortOrder', 'asc');
+    }
+}
+
+// File: ottabase/models/PageFeature.ts
+export class PageFeature extends BaseModel {
+    static entity = 'page_features';
+    static table = pageFeaturesTable;
+    static primaryKey = 'id';
+
+    static async getForSection(sectionId: string): Promise<PageFeature[]> {
+        return this.where({ sectionId }).orderBy('sortOrder', 'asc');
+    }
+}
+```
+
+### 4.4 Model Registration
+
+```typescript
+// File: worker/lib/db-utils.ts
+import { Page, PageSection, PageAction, PageFeature } from '../../ottabase/models';
+
+registerModels([
+    // ... other models
+    Page,
+    PageSection,
+    PageAction,
+    PageFeature,
+]);
+```
+
+---
+
+## 5. API Routes
+
+### 5.1 Public API — `/api/pages/:slug`
+
+Returns complete page data for frontend rendering.
+
+```typescript
+// File: worker/routes/pages.ts
+
+interface PageDataPayload {
+    page: {
+        id: string;
+        slug: string;
+        title: string;
+        type: 'block' | 'content';
+        status: 'draft' | 'published' | 'archived';
+        showInNav: boolean;
+        navOrder: number;
+        navLabel: string | null;
+        icon: string | null;
+    };
+    sections: Array<{
+        id: string;
+        slot: string;
+        title: string | null;
+        subtitle: string | null;
+        body: string | null;
+        variant: string | null;
+        githubUrl: string | null;
+        icon: string | null;
+        imageUrl: string | null;
+        enabled: boolean;
+        cssClasses: string | null;
+        metadata: Record<string, unknown> | null;
+        sortOrder: number;
+        features: Array<{
+            id: string;
+            title: string;
+            description: string;
+            icon: string | null;
+            imageUrl: string | null;
+            href: string | null;
+        }>;
+        actions: Array<{
+            id: string;
+            label: string;
+            href: string;
+            variant: string | null;
+            icon: string | null;
+            external: boolean;
+        }>;
+    }>;
+    display: {
+        variantBySlot: Record<string, string> | null;
+        themePreset: string | null;
+        fallbackThemePresetId: string | null;
+        customCss: string | null;
+        seoTitle: string | null;
+        seoDescription: string | null;
+        seoImage: string | null;
+    };
+    content: { title: string; body: string; excerpt: string | null } | null;
+}
+
+// Route handler
+export async function handlePageBySlug(context: PagesRouteContext, slug: string): Promise<Response> {
+    const preview = url.searchParams.get('preview') === 'true';
+
+    // Find page (published only, unless preview mode)
+    const pageWhere: Record<string, unknown> = { slug };
+    if (!preview) pageWhere.status = 'published';
+
+    const pages = await Page.where(pageWhere);
+    if (pages.length === 0) {
+        return errorResponse(`Page not found: ${slug}`, 404);
+    }
+
+    const page = pages[0];
+    const pageId = page.get('id');
+
+    // Fetch sections with features and actions
+    const sections = await PageSection.getForPage(pageId);
+    const sectionPayloads = await Promise.all(
+        sections.map(async (section) => {
+            const sectionId = section.get('id');
+            const [features, actions] = await Promise.all([
+                PageFeature.getForSection(sectionId),
+                PageAction.getForSection(sectionId),
+            ]);
+            return {
+                id: sectionId,
+                slot: section.get('slot'),
+                // ... all other fields
+                features: features.map((f) => ({
+                    /* ... */
+                })),
+                actions: actions.map((a) => ({
+                    /* ... */
+                })),
+            };
+        }),
+    );
+
+    return jsonResponse({
+        page: {
+            /* ... */
+        },
+        sections: sectionPayloads,
+        display: {
+            /* ... */
+        },
+        content: null,
+    });
+}
+```
+
+### 5.2 Nav API — `/api/pages/nav`
+
+Returns pages marked for navigation.
+
+```typescript
+export async function handleNavPages(context: PagesRouteContext): Promise<Response> {
+    const pages = await Page.getNavPages();
+    return jsonResponse({
+        pages: pages.map((p) => ({
+            slug: p.get('slug'),
+            title: p.get('title'),
+            navLabel: p.get('navLabel'),
+            navOrder: p.get('navOrder'),
+            icon: p.get('icon'),
+        })),
+    });
+}
+```
+
+### 5.3 Seed API — `POST /api/pages/seed`
+
+Idempotent seeding of default homepage.
+
+```typescript
+export async function handleSeedHomepage(context: PagesRouteContext): Promise<Response> {
+    // Check if homepage exists
+    const existing = await Page.getBySlug('homepage');
+    if (existing) {
+        return jsonResponse({ message: 'Homepage already exists', skipped: true });
+    }
+
+    // Create homepage with default blocks
+    const page = await Page.create({
+        slug: 'homepage',
+        title: 'Welcome to Ottabase',
+        type: 'block',
+        status: 'published',
+        showInNav: true,
+        navOrder: 0,
+    });
+
+    // Create default sections: navbar, hero, features, cta, about, footer
+    const sections = [
+        { slot: 'navbar', title: 'Ottabase', variant: 'default', sortOrder: 0 },
+        {
+            slot: 'hero',
+            title: 'Build faster with Ottabase',
+            subtitle: 'Modern platform...',
+            variant: 'centered',
+            sortOrder: 1,
+        },
+        { slot: 'features', title: 'Features', variant: 'grid', sortOrder: 2 },
+        { slot: 'cta', title: 'Ready to get started?', variant: 'default', sortOrder: 3 },
+        { slot: 'about', title: 'About Ottabase', variant: 'default', sortOrder: 4 },
+        { slot: 'footer', title: 'Ottabase', variant: 'default', sortOrder: 5 },
+    ];
+
+    for (const sectionData of sections) {
+        const section = await PageSection.create({ pageId: page.get('id'), ...sectionData });
+
+        // Add default features for 'features' section
+        if (sectionData.slot === 'features') {
+            await PageFeature.create({
+                sectionId: section.get('id'),
+                title: 'Cloudflare Workers',
+                description: 'Edge deployment',
+                icon: 'Zap',
+            });
+            // ... more features
+        }
+
+        // Add default actions for 'hero' and 'cta' sections
+        if (sectionData.slot === 'hero' || sectionData.slot === 'cta') {
+            await PageAction.create({
+                sectionId: section.get('id'),
+                label: 'Get Started',
+                href: '/docs',
+                variant: 'default',
+            });
+        }
+    }
+
+    return jsonResponse({ message: 'Homepage seeded', pageId: page.get('id') });
+}
+```
+
+### 5.4 Route Registration
+
+```typescript
+// File: worker/routes/router.ts
+router.get('/api/pages/nav', (ctx) => handleNavPages(ctx));
+router.get<{ slug: string }>('/api/pages/:slug', (ctx) => handlePageBySlug(ctx, ctx.params.slug));
+router.post('/api/pages/seed', (ctx) => handleSeedHomepage(ctx));
+```
+
+---
+
+## 6. Contract Package
+
+### 6.1 Package Structure
+
+```
+packages/homepage-contract/
+├── src/
+│   ├── schemas.ts    # Zod schemas for runtime validation
+│   ├── types.ts      # TypeScript types inferred from Zod
+│   └── index.ts      # Re-exports
+├── package.json
+└── tsconfig.json
+```
+
+### 6.2 Zod Schemas
+
+```typescript
+// File: packages/homepage-contract/src/schemas.ts
+import { z } from 'zod';
+
+export const PageActionPayloadSchema = z.object({
+    id: z.string(),
+    label: z.string(),
+    href: z.string(),
+    variant: z.string().nullable(),
+    icon: z.string().nullable(),
+    external: z.boolean(),
+});
+
+export const PageFeaturePayloadSchema = z.object({
+    id: z.string(),
+    title: z.string(),
+    description: z.string(),
+    icon: z.string().nullable(),
+    imageUrl: z.string().nullable(),
+    href: z.string().nullable(),
+});
+
+export const PageSectionPayloadSchema = z.object({
+    id: z.string(),
+    slot: z.string(),
+    title: z.string().nullable(),
+    subtitle: z.string().nullable(),
+    body: z.string().nullable(),
+    variant: z.string().nullable(),
+    githubUrl: z.string().nullable(),
+    icon: z.string().nullable(),
+    imageUrl: z.string().nullable(),
+    enabled: z.boolean(),
+    cssClasses: z.string().nullable(),
+    metadata: z.record(z.unknown()).nullable(),
+    sortOrder: z.number(),
+    features: z.array(PageFeaturePayloadSchema),
+    actions: z.array(PageActionPayloadSchema),
+});
+
+export const PageDisplayPayloadSchema = z.object({
+    variantBySlot: z.record(z.string()).nullable(),
+    themePreset: z.string().nullable(),
+    fallbackThemePresetId: z.string().nullable(),
+    customCss: z.string().nullable(),
+    seoTitle: z.string().nullable(),
+    seoDescription: z.string().nullable(),
+    seoImage: z.string().nullable(),
+});
+
+export const PageDataPayloadSchema = z.object({
+    page: z.object({
+        id: z.string(),
+        slug: z.string(),
+        title: z.string(),
+        type: z.enum(['block', 'content']),
+        status: z.enum(['draft', 'published', 'archived']),
+        showInNav: z.boolean(),
+        navOrder: z.number(),
+        navLabel: z.string().nullable(),
+        icon: z.string().nullable(),
+    }),
+    sections: z.array(PageSectionPayloadSchema),
+    display: PageDisplayPayloadSchema,
+    content: z
+        .object({
+            title: z.string(),
+            body: z.string(),
+            excerpt: z.string().nullable(),
+        })
+        .nullable(),
+});
+```
+
+### 6.3 Type Inference
+
+```typescript
+// File: packages/homepage-contract/src/types.ts
+import type { z } from 'zod';
+import type {
+    PageActionPayloadSchema,
+    PageDataPayloadSchema,
+    PageDisplayPayloadSchema,
+    PageFeaturePayloadSchema,
+    PageSectionPayloadSchema,
+} from './schemas';
+
+export type PageActionPayload = z.infer<typeof PageActionPayloadSchema>;
+export type PageFeaturePayload = z.infer<typeof PageFeaturePayloadSchema>;
+export type PageSectionPayload = z.infer<typeof PageSectionPayloadSchema>;
+export type PageDisplayPayload = z.infer<typeof PageDisplayPayloadSchema>;
+export type PageDataPayload = z.infer<typeof PageDataPayloadSchema>;
+```
+
+---
+
+## 7. Admin UI — Page Builder
+
+### 7.1 Page Structure
+
+```
+src/pages/admin/pages/
+├── index.ts                    # Route exports
+├── AdminPagesListPage.tsx      # Pages list with CRUD
+├── MarketingPageBuilder.tsx    # Drag-and-drop builder
+├── AdminPageBuilderPage.tsx    # Route component (loads builder)
+└── pages-constants.ts          # Block definitions, variants
+```
+
+### 7.2 Pages List View
+
+**File**: `AdminPagesListPage.tsx`
+
+**UX Requirements**:
+
+- Minimal design (GitHub/Notion style)
+- Search/filter by title or slug
+- Status badges: Draft (amber), Published (green), Archived (gray)
+- Actions: Edit, Preview, Duplicate, Delete
+- Quick-create button with default "New Page"
+
+**Components**:
+
+```tsx
+function AdminPagesListPage() {
+    const { data: pages } = pageHooks.useList();
+    const createMutation = pageHooks.useCreate();
+    const deleteMutation = pageHooks.useDelete();
+
+    return (
+        <div className="max-w-4xl mx-auto p-6">
+            <header className="flex justify-between mb-6">
+                <h1>Marketing Pages</h1>
+                <Button onClick={() => createMutation.mutate({ title: 'New Page', slug: `page-${Date.now()}` })}>
+                    <Plus /> New Page
+                </Button>
+            </header>
+
+            <Input placeholder="Search pages..." />
+
+            <div className="space-y-2">
+                {pages?.map((page) => (
+                    <PageListItem key={page.id} page={page} />
+                ))}
+            </div>
+        </div>
+    );
+}
+```
+
+### 7.3 Marketing Page Builder
+
+**File**: `MarketingPageBuilder.tsx` (actual implementation in
+`apps/ottabase-template-app-tanstack/src/pages/admin/pages/`)
+
+**Layout**: Tab-based editor with three main sections:
+
+1. **Settings Tab** — Page metadata, SEO, theme, navigation
+2. **Sections Tab** — Drag-and-drop block canvas with palette
+3. **Publishing Tab** — Status, preview, publish actions
+
+**Sections Tab Layout** (the main builder view):
+
+```
+┌──────────────────────────────────────────────────────────────────────────┐
+│  Header: Back | Page Title (editable) | Status | Settings | Preview     │
+├─────────────┬────────────────────────────────────────┬───────────────────┤
+│             │                                        │                   │
+│   Block     │              Canvas                    │  Block Editor     │
+│   Library   │         (sortable blocks)              │  (sheet panel)    │
+│             │                                        │                   │
+│  ─────────  │  ┌──────────────────────────────────┐  │  Opens when       │
+│  Navigation │  │  [Navbar Block]              ☰   │  │  block selected   │
+│  ─────────  │  └──────────────────────────────────┘  │                   │
+│  Navbar     │  ┌──────────────────────────────────┐  │  Contains:        │
+│             │  │  [Hero Block]                 ☰   │  │  - Title/subtitle │
+│  ─────────  │  └──────────────────────────────────┘  │  - Variant picker │
+│  Hero       │  ┌──────────────────────────────────┐  │  - Features list  │
+│  ─────────  │  │  [Features Block]             ☰   │  │  - Actions list  │
+│  Content    │  └──────────────────────────────────┘  │  - Advanced       │
+│  ─────────  │                                        │                   │
+│  Features   │                                        │                   │
+│  CTA        │                                        │                   │
+│  About      │                                        │                   │
+│  ...        │                                        │                   │
+└─────────────┴────────────────────────────────────────┴───────────────────┘
+```
+
+**Key Components**:
+
+```tsx
+// Block Library - Left sidebar with draggable block types (also referred to as "palette")
+function BlockLibrary({ onAddBlock, existingBlocks }) {
+    return (
+        <ScrollArea className="w-64 border-r p-4">
+            <h3>Add Block</h3>
+            {BLOCK_TYPES.map(block => (
+                <PaletteItem
+                    key={block.id}
+                    config={block}
+                    onAdd={onAddBlock}
+                    disabled={block.singleton && existingBlocks.includes(block.id)}
+                />
+            ))}
+        </ScrollArea>
+    );
+}
+
+// Canvas - Center area with sortable blocks (draggable from library or reorder existing)
+function Canvas({ blocks, selectedBlockId, onSelectBlock, onReorder }) {
+    return (
+        <DndContext onDragEnd={handleDragEnd}>
+            <SortableContext items={blocks.map(b => b.id)} strategy={verticalListSortingStrategy}>
+                <div className="flex-1 p-6 space-y-4">
+                    {blocks.map(block => (
+                        <SortableBlockCard
+                            key={block.id}
+                            block={block}
+                            isSelected={block.id === selectedBlockId}
+                            onSelect={() => onSelectBlock(block.id)}
+                        />
+                    ))}
+                </div>
+            </SortableContext>
+        </DndContext>
+    );
+}
+
+// Block Editor - Right panel (sheet) for editing selected block
+function BlockEditor({ block, onUpdate, onClose }) {
+    return (
+        <Sheet open={!!block} onOpenChange={() => onClose()}>
+            <SheetContent className="w-[400px]">
+                <SheetHeader>
+                    <SheetTitle>Edit {block.slot}</SheetTitle>
+                </SheetHeader>
+
+                <div className="space-y-4 py-4">
+                    <Input label="Title" value={block.title} onChange={...} />
+                    <Textarea label="Subtitle" value={block.subtitle} onChange={...} />
+                    <Select label="Variant" options={getBlockVariants(block.slot)} value={block.variant} />
+
+                    {block.supportsFeatures && (
+                        <FeaturesEditor features={block.features} onChange={...} />
+                    )}
+
+                    {block.supportsActions && (
+                        <ActionsEditor actions={block.actions} onChange={...} />
+                    )}
+                </div>
+            </SheetContent>
+        </Sheet>
+    );
+}
+```
+
+### 7.4 Block Types Configuration
+
+**File**: `pages-constants.ts`
+
+```typescript
+export interface SlotConfig {
+    id: string; // Internal slot name
+    label: string; // Display name
+    icon: LucideIcon; // Palette icon
+    description: string; // Tooltip
+    supportsFeatures: boolean;
+    supportsActions: boolean;
+    singleton?: boolean; // Only one per page (navbar, footer)
+    defaultVariant: string;
+}
+
+export const BLOCK_TYPES: SlotConfig[] = [
+    // Navigation
+    {
+        id: 'navbar',
+        label: 'Navigation Bar',
+        icon: Navigation,
+        supportsFeatures: false,
+        supportsActions: true,
+        singleton: true,
+        defaultVariant: 'default',
+    },
+
+    // Hero
+    {
+        id: 'hero',
+        label: 'Hero Section',
+        icon: Sparkles,
+        supportsFeatures: false,
+        supportsActions: true,
+        defaultVariant: 'centered',
+    },
+
+    // Content
+    {
+        id: 'features',
+        label: 'Features Grid',
+        icon: Grid3X3,
+        supportsFeatures: true,
+        supportsActions: false,
+        defaultVariant: 'grid',
+    },
+    {
+        id: 'cta',
+        label: 'Call to Action',
+        icon: Megaphone,
+        supportsFeatures: false,
+        supportsActions: true,
+        defaultVariant: 'default',
+    },
+    {
+        id: 'about',
+        label: 'About / Content',
+        icon: FileText,
+        supportsFeatures: true,
+        supportsActions: true,
+        defaultVariant: 'default',
+    },
+    {
+        id: 'testimonials',
+        label: 'Testimonials',
+        icon: Quote,
+        supportsFeatures: true,
+        supportsActions: false,
+        defaultVariant: 'carousel',
+    },
+    {
+        id: 'gallery',
+        label: 'Image Gallery',
+        icon: ImageIcon,
+        supportsFeatures: true,
+        supportsActions: false,
+        defaultVariant: 'grid',
+    },
+    {
+        id: 'team',
+        label: 'Team Members',
+        icon: Users,
+        supportsFeatures: true,
+        supportsActions: false,
+        defaultVariant: 'grid',
+    },
+    {
+        id: 'pricing',
+        label: 'Pricing Table',
+        icon: LayoutList,
+        supportsFeatures: true,
+        supportsActions: true,
+        defaultVariant: 'cards',
+    },
+    {
+        id: 'faq',
+        label: 'FAQ Section',
+        icon: Contact,
+        supportsFeatures: true,
+        supportsActions: false,
+        defaultVariant: 'accordion',
+    },
+    {
+        id: 'video',
+        label: 'Video Section',
+        icon: Video,
+        supportsFeatures: false,
+        supportsActions: true,
+        defaultVariant: 'default',
+    },
+    {
+        id: 'code',
+        label: 'Code Block',
+        icon: Code2,
+        supportsFeatures: false,
+        supportsActions: false,
+        defaultVariant: 'default',
+    },
+    {
+        id: 'contact',
+        label: 'Contact Form',
+        icon: Contact,
+        supportsFeatures: false,
+        supportsActions: true,
+        defaultVariant: 'default',
+    },
+    {
+        id: 'custom',
+        label: 'Custom HTML',
+        icon: Code2,
+        supportsFeatures: false,
+        supportsActions: false,
+        defaultVariant: 'default',
+    },
+
+    // Footer
+    {
+        id: 'footer',
+        label: 'Footer',
+        icon: Rows3,
+        supportsFeatures: false,
+        supportsActions: true,
+        singleton: true,
+        defaultVariant: 'default',
+    },
+];
+
+export const BLOCK_VARIANTS: Record<string, { id: string; label: string }[]> = {
+    hero: [
+        { id: 'centered', label: 'Centered' },
+        { id: 'split', label: 'Split (Image Right)' },
+        { id: 'minimal', label: 'Minimal' },
+    ],
+    features: [
+        { id: 'grid', label: 'Grid (3 columns)' },
+        { id: 'cards', label: 'Cards' },
+        { id: 'list', label: 'List' },
+    ],
+    cta: [
+        { id: 'default', label: 'Default' },
+        { id: 'banner', label: 'Banner' },
+        { id: 'minimal', label: 'Minimal' },
+    ],
+    navbar: [
+        { id: 'default', label: 'Default' },
+        { id: 'centered', label: 'Centered' },
+        { id: 'minimal', label: 'Minimal' },
+    ],
+    footer: [
+        { id: 'default', label: 'Default' },
+        { id: 'minimal', label: 'Minimal' },
+        { id: 'columns', label: 'Multi-Column' },
+    ],
+    about: [
+        { id: 'default', label: 'Default' },
+        { id: 'minimal', label: 'Minimal' },
+        { id: 'detailed', label: 'Detailed' },
+    ],
+};
+
+export const ACTION_VARIANTS = [
+    { id: 'default', label: 'Primary' },
+    { id: 'secondary', label: 'Secondary' },
+    { id: 'outline', label: 'Outline' },
+    { id: 'ghost', label: 'Ghost' },
+    { id: 'link', label: 'Link' },
+];
+
+export const PAGE_STATUS_OPTIONS = [
+    { id: 'draft', label: 'Draft', color: 'amber' },
+    { id: 'published', label: 'Published', color: 'emerald' },
+    { id: 'archived', label: 'Archived', color: 'zinc' },
+];
+```
+
+### 7.5 CRUD Hooks & Model Registration
+
+**File**: `src/hooks/pageHooks.ts`
+
+```typescript
+import { createModelHooks } from '@ottabase/ottaorm/client';
+import type { PageRow, NewPageRow } from '../../ottabase/models/Page.schema';
+
+// OttaORM auto-generated hooks for CRUD operations
+export const pageHooks = createModelHooks<PageRow, NewPageRow>({ entityName: 'pages' });
+export const pageSectionHooks = createModelHooks({ entityName: 'page_sections' });
+export const pageFeatureHooks = createModelHooks({ entityName: 'page_features' });
+export const pageActionHooks = createModelHooks({ entityName: 'page_actions' });
+
+// Provides: useList, useDetail, useCreate, useUpdate, useDelete, useInfiniteList
+export type { PageRow, PageSectionRow, PageFeatureRow, PageActionRow };
+```
+
+**Usage in Builder**:
+
+```typescript
+function AdminPageBuilderPage() {
+    const { data: page } = pageHooks.useDetail(pageId);
+    const { data: sections } = pageSectionHooks.useList({ filters: { pageId } });
+    const updatePage = pageHooks.useUpdate();
+    const updateSection = pageSectionHooks.useUpdate();
+    const createFeature = pageFeatureHooks.useCreate();
+    const deleteFeature = pageFeatureHooks.useDelete();
+
+    // Update page title
+    const handleTitleChange = (newTitle: string) => {
+        updatePage.mutate({ id: pageId, title: newTitle });
+    };
+
+    // Add feature to section
+    const handleAddFeature = (sectionId: string, featureData: NewPageFeatureRow) => {
+        createFeature.mutate({ ...featureData, sectionId });
+    };
+}
+```
+
+**Model Registry**:
+
+Models are registered in `worker/lib/db-utils.ts` for automatic CRUD API endpoints:
+
+```typescript
+// worker/lib/db-utils.ts
+const pageModels = [Page, PageSection, PageFeature, PageAction];
+registerModels([...coreModels, ...pageModels]);
+```
+
+This enables:
+
+- `GET /api/ottaorm/pages` — List pages
+- `POST /api/ottaorm/pages` — Create page
+- `PATCH /api/ottaorm/pages/:id` — Update page
+- `DELETE /api/ottaorm/pages/:id` — Delete page
+- Same for `page_sections`, `page_features`, `page_actions`
+
+### 7.6 Router Registration (TanStack App)
+
+**File**: `src/router.tsx`
+
+Admin pages are registered as nested routes in the TanStack Router:
+
+```typescript
+// src/router.tsx
+import { AdminPagesListPage } from './pages/admin/pages/AdminPagesListPage';
+import { AdminPageBuilderPage } from './pages/admin/pages/AdminPageBuilderPage';
+
+const adminRoute = createRoute({
+    getParentRoute: () => rootRoute,
+    path: 'admin',
+    component: AdminLayout,
+});
+
+const adminPagesRoute = createRoute({
+    getParentRoute: () => adminRoute,
+    path: 'pages',
+    component: AdminPagesListPage,
+});
+
+const adminPageBuilderRoute = createRoute({
+    getParentRoute: () => adminPagesRoute,
+    path: '$pageId',
+    component: AdminPageBuilderPage,
+});
+
+// Creates routes:
+// /admin/pages → Pages list view
+// /admin/pages/:pageId → Page builder
+```
+
+**Navigation**:
+
+```typescript
+// Link to pages list
+<Link to={adminPagesRoute.to()}>Pages</Link>
+
+// Link to specific page builder
+<Link to={adminPageBuilderRoute.to({ pageId: 'page-123' })}>
+    Edit Page
+</Link>
+```
+
+### 7.7 Page Settings Dialog
+
+```tsx
+function PageSettingsDialog({ page, open, onOpenChange, onSave }) {
+    return (
+        <Dialog open={open} onOpenChange={onOpenChange}>
+            <DialogContent className="max-w-2xl">
+                <DialogHeader>
+                    <DialogTitle>Page Settings</DialogTitle>
+                </DialogHeader>
+
+                <Tabs defaultValue="general">
+                    <TabsList>
+                        <TabsTrigger value="general">General</TabsTrigger>
+                        <TabsTrigger value="seo">SEO</TabsTrigger>
+                        <TabsTrigger value="nav">Navigation</TabsTrigger>
+                        <TabsTrigger value="theme">Theme</TabsTrigger>
+                    </TabsList>
+
+                    <TabsContent value="general">
+                        <Input label="Title" value={page.title} />
+                        <Input label="Slug" value={page.slug} />
+                        <Select label="Status" options={PAGE_STATUS_OPTIONS} value={page.status} />
+                    </TabsContent>
+
+                    <TabsContent value="seo">
+                        <Input label="SEO Title" value={page.seoTitle} />
+                        <Textarea label="SEO Description" value={page.seoDescription} />
+                        <Input label="SEO Keywords" value={page.seoKeywords} />
+                    </TabsContent>
+
+                    <TabsContent value="nav">
+                        <Switch label="Show in Navigation" checked={page.showInNav} />
+                        <Input label="Nav Order" type="number" value={page.navOrder} />
+                        <Input label="Nav Label" value={page.navLabel} />
+                        <Input label="Icon" value={page.icon} />
+                    </TabsContent>
+
+                    <TabsContent value="theme">
+                        <Select label="Theme Preset" options={THEME_PRESETS} value={page.themePreset} />
+                        <Select label="Fallback Theme" options={THEME_PRESETS} value={page.fallbackThemePresetId} />
+                        <Textarea label="Custom CSS" value={page.customCss} />
+                    </TabsContent>
+                </Tabs>
+
+                <DialogFooter>
+                    <Button variant="outline" onClick={() => onOpenChange(false)}>
+                        Cancel
+                    </Button>
+                    <Button onClick={onSave}>Save</Button>
+                </DialogFooter>
+            </DialogContent>
+        </Dialog>
+    );
+}
+```
+
+---
+
+## 8. Next.js Frontend Rendering
+
+### 8.1 Dynamic Route
+
+**File**: `app/[slug]/page.tsx`
+
+```tsx
+import { Metadata } from 'next';
+import { notFound } from 'next/navigation';
+import { fetchPageByPageSlug } from '../../lib/api';
+import { MarketingPageContent } from './marketing-page-content';
+
+interface PageProps {
+    params: Promise<{ slug: string }>;
+    searchParams: Promise<{ preview?: string }>;
+}
+
+export async function generateMetadata({ params, searchParams }: PageProps): Promise<Metadata> {
+    const { slug } = await params;
+    const { preview } = await searchParams;
+    const isPreview = preview === 'true';
+
+    if (slug === 'homepage') return { title: 'Home' };
+
+    const pageData = await fetchPageByPageSlug(slug, isPreview);
+    if (!pageData) return { title: 'Not Found' };
+
+    return {
+        title: pageData.display.seoTitle || pageData.page.title,
+        description: pageData.display.seoDescription || undefined,
+        openGraph: pageData.display.seoImage ? { images: [{ url: pageData.display.seoImage }] } : undefined,
+    };
+}
+
+export default async function MarketingPage({ params, searchParams }: PageProps) {
+    const { slug } = await params;
+    const { preview } = await searchParams;
+    const isPreview = preview === 'true';
+
+    // Homepage handled by (site)/page.tsx
+    if (slug === 'homepage') notFound();
+
+    const pageData = await fetchPageByPageSlug(slug, isPreview);
+    if (!pageData) notFound();
+
+    // Only show published pages unless in preview mode
+    if (!isPreview && pageData.page.status !== 'published') notFound();
+
+    return <MarketingPageContent pageData={pageData} isPreview={isPreview} />;
+}
+```
+
+### 8.2 Marketing Page Content Component
+
+**File**: `app/[slug]/marketing-page-content.tsx`
+
+```tsx
+'use client';
+
+import type { PageDataPayload, PageSectionPayload } from '@ottabase/homepage-contract';
+import { SlotRenderer } from '../../components/SlotRenderer';
+import type { HeroData, HeroAction } from '../../components/variants/hero';
+import type { FeaturesData } from '../../components/variants/features';
+import type { CTAData, CTAAction } from '../../components/variants/cta';
+import type { AboutData } from '../../components/variants/about';
+import type { NavbarData } from '../../components/variants/navbar';
+import type { FooterData } from '../../components/variants/footer';
+
+interface MarketingPageContentProps {
+    pageData: PageDataPayload;
+    isPreview?: boolean;
+}
+
+type ButtonVariant = 'default' | 'secondary' | 'outline' | 'ghost';
+
+function toButtonVariant(v: string | null | undefined): ButtonVariant {
+    const valid: ButtonVariant[] = ['default', 'secondary', 'outline', 'ghost'];
+    return valid.includes(v as ButtonVariant) ? (v as ButtonVariant) : 'default';
+}
+
+function transformSection(section: PageSectionPayload): { slot: string; data: unknown } | null {
+    const { slot, title, subtitle, body, githubUrl, features, actions } = section;
+
+    switch (slot) {
+        case 'hero':
+            return {
+                slot: 'hero',
+                data: {
+                    title: title || 'Welcome',
+                    subtitle: subtitle || body || undefined,
+                    actions: actions.map(
+                        (a): HeroAction => ({
+                            label: a.label,
+                            href: a.href,
+                            variant: toButtonVariant(a.variant),
+                        }),
+                    ),
+                } satisfies HeroData,
+            };
+
+        case 'features':
+            return {
+                slot: 'features',
+                data: {
+                    title: title || 'Features',
+                    features: features.map((f) => ({
+                        title: f.title,
+                        description: f.description || '',
+                        icon: f.icon || undefined,
+                    })),
+                } satisfies FeaturesData,
+            };
+
+        case 'cta':
+            return {
+                slot: 'cta',
+                data: {
+                    title: title || 'Get Started',
+                    description: subtitle || body || undefined,
+                    actions: actions.map(
+                        (a): CTAAction => ({
+                            label: a.label,
+                            href: a.href,
+                            variant: toButtonVariant(a.variant),
+                        }),
+                    ),
+                } satisfies CTAData,
+            };
+
+        case 'about':
+            return {
+                slot: 'about',
+                data: {
+                    title: title || 'About',
+                    description: subtitle || body || undefined,
+                    githubUrl: githubUrl || undefined,
+                } satisfies AboutData,
+            };
+
+        case 'navbar':
+            return {
+                slot: 'navbar',
+                data: { title: title || 'Ottabase', githubUrl: githubUrl || undefined } satisfies NavbarData,
+            };
+
+        case 'footer':
+            return {
+                slot: 'footer',
+                data: { siteName: title || 'Ottabase', tagline: subtitle || body || undefined } satisfies FooterData,
+            };
+
+        default:
+            // Fallback: render as CTA
+            return {
+                slot: 'cta',
+                data: {
+                    title: title || slot.charAt(0).toUpperCase() + slot.slice(1),
+                    description: subtitle || body || undefined,
+                    actions: actions.map(
+                        (a): CTAAction => ({
+                            label: a.label,
+                            href: a.href,
+                            variant: toButtonVariant(a.variant),
+                        }),
+                    ),
+                } satisfies CTAData,
+            };
+    }
+}
+
+export function MarketingPageContent({ pageData, isPreview = false }: MarketingPageContentProps) {
+    const { sections, page } = pageData;
+
+    const enabledSections = sections.filter((s) => s.enabled !== false).sort((a, b) => a.sortOrder - b.sortOrder);
+
+    const navbarSection = enabledSections.find((s) => s.slot === 'navbar');
+    const footerSection = enabledSections.find((s) => s.slot === 'footer');
+    const contentSections = enabledSections.filter((s) => s.slot !== 'navbar' && s.slot !== 'footer');
+
+    return (
+        <div className="min-h-screen flex flex-col">
+            {/* Preview Banner */}
+            {isPreview && (
+                <div className="bg-amber-500 text-black px-4 py-2 text-center text-sm font-medium">
+                    Preview Mode — This page is {page.status}. Only you can see this preview.
+                </div>
+            )}
+
+            {/* Navbar */}
+            {navbarSection && <SlotRenderer slot="navbar" data={transformSection(navbarSection)?.data as NavbarData} />}
+
+            {/* Content Sections */}
+            <main className="flex-1">
+                {contentSections.map((section) => {
+                    const transformed = transformSection(section);
+                    if (!transformed) return null;
+
+                    return <SlotRenderer key={section.id} slot={transformed.slot} data={transformed.data} />;
+                })}
+            </main>
+
+            {/* Footer */}
+            {footerSection && <SlotRenderer slot="footer" data={transformSection(footerSection)?.data as FooterData} />}
+        </div>
+    );
+}
+```
+
+### 8.3 Slot Renderer
+
+**File**: `components/SlotRenderer.tsx`
+
+```tsx
+import dynamic from 'next/dynamic';
+import type { HeroData } from './variants/hero';
+import type { FeaturesData } from './variants/features';
+import type { CTAData } from './variants/cta';
+import type { NavbarData } from './variants/navbar';
+import type { FooterData } from './variants/footer';
+import type { AboutData } from './variants/about';
+
+// Discriminated union for type safety
+type SlotRendererProps =
+    | { slot: 'hero'; data: HeroData; variant?: string }
+    | { slot: 'features'; data: FeaturesData; variant?: string }
+    | { slot: 'cta'; data: CTAData; variant?: string }
+    | { slot: 'navbar'; data: NavbarData; variant?: string }
+    | { slot: 'footer'; data: FooterData; variant?: string }
+    | { slot: 'about'; data: AboutData; variant?: string };
+
+// Lazy-load variant components
+const VARIANT_COMPONENTS = {
+    hero: {
+        centered: dynamic(() => import('./variants/hero/HeroCentered')),
+        split: dynamic(() => import('./variants/hero/HeroSplit')),
+        minimal: dynamic(() => import('./variants/hero/HeroMinimal')),
+    },
+    features: {
+        grid: dynamic(() => import('./variants/features/FeaturesGrid')),
+        cards: dynamic(() => import('./variants/features/FeaturesCards')),
+        list: dynamic(() => import('./variants/features/FeaturesList')),
+    },
+    cta: {
+        default: dynamic(() => import('./variants/cta/CTADefault')),
+        banner: dynamic(() => import('./variants/cta/CTABanner')),
+        minimal: dynamic(() => import('./variants/cta/CTAMinimal')),
+    },
+    navbar: {
+        default: dynamic(() => import('./variants/navbar/NavbarDefault')),
+        centered: dynamic(() => import('./variants/navbar/NavbarCentered')),
+        minimal: dynamic(() => import('./variants/navbar/NavbarMinimal')),
+    },
+    footer: {
+        default: dynamic(() => import('./variants/footer/FooterDefault')),
+        minimal: dynamic(() => import('./variants/footer/FooterMinimal')),
+        columns: dynamic(() => import('./variants/footer/FooterColumns')),
+    },
+    about: {
+        default: dynamic(() => import('./variants/about/AboutDefault')),
+        minimal: dynamic(() => import('./variants/about/AboutMinimal')),
+        detailed: dynamic(() => import('./variants/about/AboutDetailed')),
+    },
+};
+
+const DEFAULT_VARIANTS: Record<string, string> = {
+    hero: 'centered',
+    features: 'grid',
+    cta: 'default',
+    navbar: 'default',
+    footer: 'default',
+    about: 'default',
+};
+
+export function SlotRenderer(props: SlotRendererProps) {
+    const { slot, data, variant } = props;
+
+    const variants = VARIANT_COMPONENTS[slot];
+    const variantId = variant || DEFAULT_VARIANTS[slot] || 'default';
+    const Component = variants?.[variantId] || variants?.['default'];
+
+    if (!Component) {
+        console.warn(`No component found for slot="${slot}" variant="${variantId}"`);
+        return null;
+    }
+
+    return <Component data={data} />;
+}
+```
+
+### 8.4 Variant Component Example
+
+**File**: `components/variants/hero/HeroCentered.tsx`
+
+```tsx
+import Link from 'next/link';
+import { Button } from '@/components/ui/button';
+import type { HeroData, HeroAction } from './types';
+
+export default function HeroCentered({ data }: { data: HeroData }) {
+    return (
+        <section className="relative py-20 md:py-32">
+            <div className="container mx-auto px-4 text-center">
+                <h1 className="text-4xl md:text-6xl font-bold tracking-tight mb-6">{data.title}</h1>
+
+                {data.subtitle && (
+                    <p className="text-xl text-muted-foreground max-w-2xl mx-auto mb-8">{data.subtitle}</p>
+                )}
+
+                {data.actions && data.actions.length > 0 && (
+                    <div className="flex flex-wrap justify-center gap-4">
+                        {data.actions.map((action, i) => (
+                            <Button key={i} variant={action.variant || 'default'} asChild>
+                                <Link href={action.href}>{action.label}</Link>
+                            </Button>
+                        ))}
+                    </div>
+                )}
+            </div>
+        </section>
+    );
+}
+```
+
+### 8.5 API Client
+
+**File**: `lib/api.ts`
+
+```typescript
+import type { PageDataPayload, NavPagePayload } from '@ottabase/homepage-contract';
+
+const API_URL = process.env.NEXT_PUBLIC_API_URL || 'http://localhost:3004';
+
+export async function fetchPageByPageSlug(slug: string, preview = false): Promise<PageDataPayload | null> {
+    if (!API_URL) return null;
+
+    try {
+        const url = new URL(`${API_URL}/api/pages/${encodeURIComponent(slug)}`);
+        if (preview) url.searchParams.set('preview', 'true');
+
+        const res = await fetch(url.toString(), {
+            next: { revalidate: preview ? 0 : 60 }, // No cache in preview mode
+        });
+
+        if (!res.ok) return null;
+        return await res.json();
+    } catch {
+        return null;
+    }
+}
+
+export async function fetchNavPages(): Promise<NavPagePayload[]> {
+    if (!API_URL) return [];
+
+    try {
+        const res = await fetch(`${API_URL}/api/pages/nav`, {
+            next: { revalidate: 60 },
+        });
+
+        if (!res.ok) return [];
+        const data = await res.json();
+        return Array.isArray(data.pages) ? data.pages : [];
+    } catch {
+        return [];
+    }
+}
+```
+
+---
+
+## 8.5 Block Registry System
+
+### Why This Matters
+
+**Goal**: SaaS founders can register custom components without code deployment or DB migrations.
+
+**Current Limitation**: Slot types are hardcoded enums. Adding a custom block requires:
+
+1. DB migration
+2. Code change + redeploy
+3. Admin UI manual refresh
+
+**Solution**: Dynamic registry system that apps populate at startup.
+
+### Architecture
+
+#### 1. Block Definition Interface
+
+```typescript
+// @ottabase/block-registry (new package)
+export interface FieldDefinition {
+    type: 'text' | 'textarea' | 'image' | 'select' | 'number' | 'list' | 'object-array';
+    label: string;
+    placeholder?: string;
+    required?: boolean;
+    maxLength?: number;
+    options?: (string | { label: string; value: string })[];
+    schema?: FieldDefinition; // For lists/objects
+    responsive?: {
+        desktop?: Partial<FieldDefinition>;
+        mobile?: Partial<FieldDefinition>;
+    };
+}
+
+export interface VariantDefinition {
+    id: string;
+    label: string;
+    description?: string;
+}
+
+export interface BlockDefinition {
+    id: string; // 'hero', 'org:testimonial-wall'
+    label: string; // Display name
+    icon?: string; // Lucide icon name
+    description?: string; // Tooltip
+    category: 'layout' | 'content' | 'cta' | 'custom' | 'social' | 'form';
+
+    // Schema
+    fields: Record<string, FieldDefinition>;
+    variants: VariantDefinition[];
+    defaultVariant: string;
+
+    // Rendering hints
+    supportsFeatures: boolean;
+    supportsActions: boolean;
+
+    // Constraints
+    singleton?: boolean; // Only one per page (navbar, footer)
+    minWidth?: number; // CSS pixels
+    maxWidth?: number;
+
+    // Metadata
+    previewUrl?: string; // e.g., '/preview/hero?variant=centered'
+    componentName?: string; // For frontend
+    sourceApp?: string; // Which app registered this
+}
+```
+
+#### 2. Registration API
+
+```typescript
+// In each Next.js app (at startup, e.g., in app layout or middleware)
+import { BlockRegistry } from '@ottabase/block-registry';
+
+const registry = BlockRegistry.getInstance();
+
+// Register built-in blocks
+registry.register({
+    id: 'hero',
+    label: 'Hero Section',
+    category: 'layout',
+    fields: {
+        title: { type: 'text', required: true, maxLength: 100 },
+        subtitle: { type: 'text', maxLength: 200 },
+        backgroundImage: { type: 'image' },
+        actions: { type: 'list', schema: { type: 'action' } },
+    },
+    variants: [
+        { id: 'centered', label: 'Centered' },
+        { id: 'split', label: 'Split Layout' },
+        { id: 'minimal', label: 'Minimal' },
+    ],
+    defaultVariant: 'centered',
+    supportsFeatures: false,
+    supportsActions: true,
+});
+
+// Register custom app blocks
+registry.register({
+    id: 'acme:testimonial-carousel',
+    label: 'Testimonial Carousel (ACME)',
+    category: 'custom',
+    icon: 'MessageSquare',
+    fields: {
+        testimonials: {
+            type: 'object-array',
+            schema: {
+                name: { type: 'text', required: true },
+                role: { type: 'text' },
+                quote: { type: 'textarea', required: true },
+                image: { type: 'image' },
+                rating: { type: 'select', options: ['1', '2', '3', '4', '5'] },
+            },
+        },
+        columns: { type: 'select', options: ['2', '3', '4'], defaultValue: '3' },
+        autoPlay: { type: 'select', options: ['true', 'false'] },
+    },
+    variants: [
+        { id: 'grid', label: 'Grid' },
+        { id: 'carousel', label: 'Carousel' },
+    ],
+    defaultVariant: 'carousel',
+    supportsFeatures: false,
+    supportsActions: false,
+});
+```
+
+#### 3. Schema Validation from Registry
+
+```typescript
+// At runtime, generate Zod schemas from registry
+import { buildBlockSchema } from '@ottabase/block-registry';
+
+export function generatePageSectionSchema(registry: BlockRegistry) {
+    const blockSchemas = {};
+
+    for (const block of registry.getAll()) {
+        blockSchemas[block.id] = buildBlockSchema(block.fields);
+    }
+
+    return z
+        .object({
+            id: z.string(),
+            slot: z.string(), // Any registered block ID
+            title: z.string().optional(),
+            data: z.record(z.unknown()), // Dynamic fields validated by slot
+            variant: z.string(),
+            enabled: z.boolean(),
+            sortOrder: z.number(),
+        })
+        .refine((data) => {
+            const block = registry.get(data.slot);
+            if (!block) return false;
+
+            // Validate data against block schema
+            const schema = blockSchemas[block.id];
+            return schema.safeParse(data.data).success;
+        });
+}
+```
+
+**Benefit**: Adding a custom block requires NO database changes, NO code deployment (if already running), just API call.
+
+---
+
+## 8.6 Component Discovery API
+
+### Why This Matters
+
+**Problem**: Admin UI has no way to discover custom blocks registered by Next.js apps.
+
+**Goal**: Admin UI auto-discovers and displays all available blocks (built-in + custom).
+
+### Architecture
+
+#### 1. App Exposes Block Registry Endpoint
+
+```typescript
+// apps/my-homepage/app/api/blocks/route.ts
+import { BlockRegistry } from '@ottabase/block-registry';
+
+export async function GET(request: Request) {
+    const registry = BlockRegistry.getInstance();
+
+    return Response.json({
+        blocks: registry.getAll().map((block) => ({
+            id: block.id,
+            label: block.label,
+            icon: block.icon,
+            description: block.description,
+            category: block.category,
+            variants: block.variants,
+            defaultVariant: block.defaultVariant,
+            supportsFeatures: block.supportsFeatures,
+            supportsActions: block.supportsActions,
+            singleton: block.singleton,
+            previewUrl: block.previewUrl, // e.g., '/preview/hero?variant=centered'
+            componentName: block.componentName,
+            sourceApp: block.sourceApp,
+        })),
+        timestamp: Date.now(),
+    });
+}
+```
+
+#### 2. Admin UI Fetches & Caches
+
+```typescript
+// src/lib/blockRegistry.ts (admin UI)
+import { BlockRegistry } from '@ottabase/block-registry';
+
+export async function fetchRegisteredBlocks(homePageUrl: string) {
+    const registry = BlockRegistry.getInstance();
+
+    try {
+        const response = await fetch(`${homePageUrl}/api/blocks`);
+        const data = await response.json();
+
+        // Register all blocks
+        for (const block of data.blocks) {
+            registry.register(block);
+        }
+
+        return registry;
+    } catch (error) {
+        console.error('Failed to fetch blocks:', error);
+        return registry; // Return cached registry
+    }
+}
+
+// Usage in admin builder initialization
+export async function initializeBuilder(pageId: string, homePageUrl: string) {
+    const registry = await fetchRegisteredBlocks(homePageUrl);
+    const page = await fetchPage(pageId);
+
+    return { registry, page };
+}
+```
+
+#### 3. Admin UI Block Palette Updates Dynamically
+
+```tsx
+// src/components/BlockPalette.tsx
+import { useBuilder } from '@/hooks/useBuilder';
+
+export function BlockPalette() {
+    const { registry } = useBuilder();
+
+    const blocks = registry.getAll();
+    const grouped = groupBy(blocks, 'category');
+
+    return (
+        <div className="space-y-4">
+            {Object.entries(grouped).map(([category, categoryBlocks]) => (
+                <div key={category}>
+                    <h4 className="text-sm font-semibold capitalize">{category}</h4>
+                    <div className="space-y-2">
+                        {categoryBlocks.map((block) => (
+                            <div key={block.id} className="group relative">
+                                {/* Show variants inline */}
+                                {block.variants.length > 1 && (
+                                    <div className="opacity-0 group-hover:opacity-100 absolute top-0 right-0 flex gap-1 p-2 bg-gray-100 rounded">
+                                        {block.variants.map((v) => (
+                                            <button
+                                                key={v.id}
+                                                onClick={() => addBlock(block.id, v.id)}
+                                                className="text-xs px-2 py-1 bg-white rounded hover:bg-blue-100"
+                                            >
+                                                {v.label}
+                                            </button>
+                                        ))}
+                                    </div>
+                                )}
+
+                                <button
+                                    onClick={() => addBlock(block.id, block.defaultVariant)}
+                                    className="w-full text-left px-3 py-2 rounded hover:bg-blue-50 transition"
+                                >
+                                    {block.icon && <Icon name={block.icon} className="inline mr-2" />}
+                                    <span className="text-sm">{block.label}</span>
+                                    {block.singleton && <Badge>Only one</Badge>}
+                                </button>
+                            </div>
+                        ))}
+                    </div>
+                </div>
+            ))}
+        </div>
+    );
+}
+```
+
+**Benefit**: Add a new block to your Next.js app → it automatically appears in the admin builder palette within seconds.
+
+---
+
+## 8.7 Split-Pane Preview Architecture
+
+### Why This Matters
+
+**Problem**: Current builder requires clicking "Preview" to see changes in a new tab. Users can't see what they're
+building in real-time.
+
+**Goal**: Live, side-by-side preview that updates instantly as user edits.
+
+### Architecture
+
+#### 1. Split Layout Component
+
+```tsx
+// src/pages/admin/pages/AdminPageBuilderPage.tsx
+export function AdminPageBuilderPage() {
+    return (
+        <div className="flex h-screen gap-4 p-4 bg-gray-50">
+            {/* Left: Builder (70%) */}
+            <div className="flex-[0.7] flex flex-col space-y-4 overflow-auto">
+                <BuilderHeader />
+
+                <Tabs defaultValue="sections">
+                    <TabsList>
+                        <TabsTrigger value="sections">Sections</TabsTrigger>
+                        <TabsTrigger value="settings">Settings</TabsTrigger>
+                        <TabsTrigger value="seo">SEO</TabsTrigger>
+                    </TabsList>
+
+                    <TabsContent value="sections">
+                        <BlockCanvas />
+                    </TabsContent>
+                </Tabs>
+            </div>
+
+            {/* Right: Live Preview (30%) */}
+            <div className="flex-[0.3] bg-white rounded-lg shadow-lg overflow-hidden flex flex-col">
+                <LivePreviewHeader />
+                <LivePreviewPane />
+            </div>
+        </div>
+    );
+}
+```
+
+#### 2. Live Preview Component
+
+```tsx
+// src/components/LivePreviewPane.tsx
+import { useBuilder } from '@/hooks/useBuilder';
+import { SlotRenderer } from '@/components/SlotRenderer';
+
+export function LivePreviewPane() {
+    const { page, sections, display, previewMode } = useBuilder();
+    const [viewport, setViewport] = useState<'mobile' | 'tablet' | 'desktop'>('desktop');
+
+    const viewportWidths = {
+        mobile: 375,
+        tablet: 768,
+        desktop: 1200,
+    };
+
+    return (
+        <div className="flex flex-col h-full bg-gray-100">
+            {/* Viewport Selector */}
+            <div className="flex gap-2 p-3 border-b bg-white">
+                {(['mobile', 'tablet', 'desktop'] as const).map((mode) => (
+                    <button
+                        key={mode}
+                        onClick={() => setViewport(mode)}
+                        className={`px-3 py-1 text-sm rounded ${
+                            viewport === mode ? 'bg-blue-500 text-white' : 'bg-gray-200'
+                        }`}
+                    >
+                        {mode.charAt(0).toUpperCase() + mode.slice(1)} ({viewportWidths[mode]}px)
+                    </button>
+                ))}
+            </div>
+
+            {/* Preview Canvas */}
+            <div className="flex-1 overflow-auto bg-gray-100 flex items-start justify-center p-4">
+                <div
+                    className="bg-white shadow-lg"
+                    style={{
+                        width: `${viewportWidths[viewport]}px`,
+                        minHeight: '100%',
+                    }}
+                >
+                    {/* Draft Banner */}
+                    {page.status === 'draft' && (
+                        <div className="bg-amber-100 text-amber-900 px-4 py-2 text-sm font-medium">
+                            Draft Preview — Changes are not live
+                        </div>
+                    )}
+
+                    {/* Rendered Blocks */}
+                    <div className="preview-container">
+                        {sections
+                            .filter((s) => s.enabled)
+                            .sort((a, b) => a.sortOrder - b.sortOrder)
+                            .map((section) => (
+                                <SlotRenderer
+                                    key={section.id}
+                                    slot={section.slot}
+                                    data={transformSectionData(section)}
+                                    variant={section.variant}
+                                    isPreview={true}
+                                />
+                            ))}
+                    </div>
+                </div>
+            </div>
+        </div>
+    );
+}
+```
+
+#### 3. Real-Time Sync via TanStack Query
+
+```typescript
+// src/hooks/useBuilder.ts
+export function useBuilder() {
+    const pageId = useParams().pageId;
+
+    // Fetch page data
+    const { data: page } = pageHooks.useDetail(pageId);
+
+    // Fetch sections
+    const { data: sections } = pageSectionHooks.useList(
+        { filters: { pageId } },
+        {
+            refetchOnWindowFocus: true,
+            refetchInterval: 1000, // Update preview every 1 second
+        },
+    );
+
+    // When mutations occur, preview updates automatically
+    const updateSection = pageSectionHooks.useUpdate();
+
+    const handleSectionChange = (sectionId: string, updates: Partial<PageSectionRow>) => {
+        updateSection.mutate(
+            { id: sectionId, ...updates },
+            {
+                onSuccess: () => {
+                    // TanStack Query auto-updates cache
+                    // Preview re-renders from new data
+                },
+            },
+        );
+    };
+
+    return {
+        page,
+        sections: sections || [],
+        updateSection: handleSectionChange,
+        // ...
+    };
+}
+```
+
+**Benefit**: Users see exactly what they're building in real-time. Page building feels instant and satisfying.
+
+---
+
+## 8.8 Extensibility & Custom Blocks
+
+### How It All Works Together
+
+#### Step 1: App Registers Blocks (at startup)
+
+```typescript
+// apps/my-saas/lib/blocks.ts
+import { BlockRegistry } from '@ottabase/block-registry';
+
+export function registerCustomBlocks() {
+    const registry = BlockRegistry.getInstance();
+
+    registry.register({
+        id: 'myorg:pricing-calculator',
+        label: 'Pricing Calculator',
+        category: 'custom',
+        fields: {
+            title: { type: 'text', required: true },
+            plans: { type: 'object-array', schema: { ... } },
+            currency: { type: 'select', options: ['USD', 'EUR', 'GBP'] },
+        },
+        variants: [
+            { id: 'cards', label: 'Card Layout' },
+            { id: 'slider', label: 'Slider' },
+        ],
+        defaultVariant: 'cards',
+        previewUrl: '/preview/pricing?variant=cards',
+        componentName: 'PricingCalculator',
+    });
+}
+
+// In app layout or middleware
+registerCustomBlocks();
+```
+
+#### Step 2: Admin Discovers Blocks
+
+```typescript
+// Admin loads: GET /api/blocks
+// Response includes: hero, features, pricing-calculator, your-custom-blocks
+// Admin UI palette auto-updates with all blocks
+```
+
+#### Step 3: User Adds Block & Sees Preview
+
+```
+User clicks "Pricing Calculator" variant "Slider"
+↓
+Block added to page with default data
+↓
+Live preview pane renders <PricingCalculator variant="slider" />
+↓
+User sees it immediately on the right side
+```
+
+#### Step 4: User Edits Block Data
+
+```
+User clicks block → Editor sheet opens
+User fills form based on block's field definitions
+↓
+Each field change → mutation → cache updated
+↓
+Live preview re-renders with new data
+```
+
+**Result**: Fully dynamic, extensible page builder with zero custom deployment needed for new blocks.
+
+### 9.1 Creating a New Page
+
+1. User navigates to **Admin → Marketing Pages**
+2. Clicks **"+ New Page"** button
+3. System creates page with:
+    - `title`: "New Page"
+    - `slug`: `page-{timestamp}`
+    - `status`: "draft"
+    - `type`: "block"
+4. Redirects to **Page Builder**
+5. Page builder loads empty canvas
+
+### 9.2 Adding Blocks
+
+1. In Page Builder, user sees **Block Palette** on left
+2. Clicks a block type (e.g., "Hero Section")
+3. System:
+    - Creates `PageSection` record with `slot: 'hero'`, `enabled: true`
+    - Adds to canvas at bottom
+    - Sets default variant (e.g., "centered")
+4. Block appears in canvas with grab handle
+5. User can click block to edit in **Block Editor** sheet
+
+### 9.3 Reordering Blocks
+
+1. User drags block by grab handle
+2. DnD library (@dnd-kit) handles visual feedback
+3. On drop, system:
+    - Calculates new `sortOrder` values
+    - Batch updates all affected sections
+4. Canvas re-renders with new order
+
+### 9.4 Editing a Block
+
+1. User clicks a block in canvas
+2. **Block Editor** sheet slides in from right
+3. Editor shows:
+    - Title, subtitle, body fields
+    - Variant selector (dropdown)
+    - Features list (if `supportsFeatures`)
+    - Actions list (if `supportsActions`)
+    - Advanced: CSS classes, background color
+4. Changes are debounced and auto-saved
+
+### 9.5 Managing Features (within a block)
+
+1. In Block Editor for "Features Grid" block
+2. User sees existing features with drag handles
+3. Clicks **"+ Add Feature"**
+4. Inline editor appears:
+    - Title (required)
+    - Description
+    - Icon (picker or text)
+    - Link URL (optional)
+5. User fills and saves
+6. Feature appears in list, can be reordered
+
+### 9.6 Managing Actions (CTA buttons)
+
+1. In Block Editor for "Hero" or "CTA" block
+2. User sees existing buttons
+3. Clicks **"+ Add Button"**
+4. Inline editor:
+    - Label (required)
+    - URL (required)
+    - Variant (Primary, Secondary, Outline, Ghost, Link)
+    - Icon (optional)
+    - Open in new tab (toggle)
+5. User fills and saves
+
+### 9.7 Publishing a Page
+
+1. User clicks **"Settings"** button in header
+2. Opens **Page Settings Dialog**
+3. Navigates to **General** tab
+4. Changes Status from "Draft" → "Published"
+5. Clicks **Save**
+6. Page is now live at `/{slug}`
+
+### 9.8 Previewing a Page
+
+1. User clicks **"Preview"** button in header
+2. Opens new tab to `http://{HOMEPAGE_URL}/{slug}?preview=true`
+3. Draft page renders with **amber preview banner**
+4. User verifies design before publishing
+
+### 9.9 Deleting a Page
+
+1. In Pages List, user clicks **⋮** menu on page row
+2. Clicks **"Delete"**
+3. Confirmation dialog appears
+4. User confirms
+5. System:
+    - Deletes page (cascade deletes sections, features, actions)
+    - Removes from list
+
+---
+
+## 10. Implementation Checklist
+
+### Phase 1: Database & Models
+
+- [ ] Create `Page.schema.ts` with all fields
+- [ ] Create `PageSection.schema.ts` with FK to pages
+- [ ] Create `PageFeature.schema.ts` with FK to sections
+- [ ] Create `PageAction.schema.ts` with FK to sections
+- [ ] Export all tables in `ottabase/db/schema.ts`
+- [ ] Add tables to `config.migrations.ts` PACKAGE_REGISTRY
+- [ ] Create `Page.ts` model with static methods
+- [ ] Create `PageSection.ts` model
+- [ ] Create `PageFeature.ts` model
+- [ ] Create `PageAction.ts` model
+- [ ] Register models in `worker/lib/db-utils.ts`
+- [ ] Run migrations: `curl -X POST /api/ottaorm/init`
+
+### Phase 2: API Routes
+
+- [ ] Create `worker/routes/pages.ts`
+- [ ] Implement `GET /api/pages/:slug` with features/actions
+- [ ] Implement `GET /api/pages/nav`
+- [ ] Implement `POST /api/pages/seed`
+- [ ] Add preview mode (`?preview=true`)
+- [ ] Register routes in `router.ts`
+- [ ] Test with curl/Postman
+
+### Phase 3: Contract Package
+
+- [ ] Create `packages/homepage-contract/`
+- [ ] Define Zod schemas in `schemas.ts`
+- [ ] Export TypeScript types in `types.ts`
+- [ ] Add to workspace and build
+
+### Phase 4: Admin UI - Pages List
+
+- [ ] Create `src/pages/admin/pages/AdminPagesListPage.tsx`
+- [ ] Create CRUD hooks in `hooks/pageHooks.ts`
+- [ ] Add route in TanStack Router
+- [ ] Implement create/delete/duplicate
+- [ ] Add search and filtering
+
+### Phase 5: Admin UI - Page Builder
+
+- [ ] Create `pages-constants.ts` with block definitions
+- [ ] Create `MarketingPageBuilder.tsx`
+- [ ] Implement Block Palette component
+- [ ] Implement Canvas with @dnd-kit
+- [ ] Implement Block Editor sheet
+- [ ] Implement Features editor
+- [ ] Implement Actions editor
+- [ ] Implement Page Settings dialog
+- [ ] Wire up all mutations
+
+### Phase 6: Next.js Frontend
+
+- [ ] Create `app/[slug]/page.tsx` dynamic route
+- [ ] Create `app/[slug]/marketing-page-content.tsx`
+- [ ] Update `lib/api.ts` with preview support
+- [ ] Create/update slot components in `components/variants/`
+- [ ] Implement SlotRenderer with variant dispatch
+- [ ] Add preview banner for draft pages
+- [ ] Test all slots and variants
+
+### Phase 7: Polish & Testing
+
+- [ ] Add loading states
+- [ ] Add error handling
+- [ ] Add optimistic updates
+- [ ] Write tests for models
+- [ ] Write tests for API routes
+- [ ] Write component tests
+
+---
+
+## 10.5 UX/DX Enhancements
+
+These are not MVP but significantly improve the builder experience:
+
+### A. Inline Editing (Block Title in Canvas)
+
+**Problem**: Users must click a block, wait for sheet to open, find the title field, edit it.
+
+**Solution**: Double-click block title in canvas to edit inline.
+
+```tsx
+// src/components/BlockCanvas/BlockCard.tsx
+export function BlockCard({ section }: { section: PageSectionRow }) {
+    const [isEditingTitle, setIsEditingTitle] = useState(false);
+    const [title, setTitle] = useState(section.title);
+    const updateSection = pageSectionHooks.useUpdate();
+
+    const handleTitleBlur = async () => {
+        if (title !== section.title) {
+            updateSection.mutate({ id: section.id, title });
+        }
+        setIsEditingTitle(false);
+    };
+
+    return (
+        <Card className="cursor-grab active:cursor-grabbing">
+            {isEditingTitle ? (
+                <input
+                    autoFocus
+                    value={title}
+                    onChange={(e) => setTitle(e.target.value)}
+                    onBlur={handleTitleBlur}
+                    onKeyDown={(e) => {
+                        if (e.key === 'Enter') handleTitleBlur();
+                        if (e.key === 'Escape') {
+                            setTitle(section.title);
+                            setIsEditingTitle(false);
+                        }
+                    }}
+                    className="text-sm font-semibold border-b focus:outline-none"
+                />
+            ) : (
+                <h3
+                    onDoubleClick={() => setIsEditingTitle(true)}
+                    className="text-sm font-semibold cursor-pointer hover:text-blue-600"
+                >
+                    {title || 'Untitled Block'}
+                </h3>
+            )}
+        </Card>
+    );
+}
+```
+
+**Benefit**: Faster editing flow, especially for bulk updates.
+
+---
+
+### B. Keyboard Shortcuts
+
+**Common flows that need shortcuts**:
+
+| Shortcut   | Action                | Context      |
+| ---------- | --------------------- | ------------ |
+| `Ctrl/⌘ Z` | Undo last change      | Builder      |
+| `Ctrl/⌘ Y` | Redo                  | Builder      |
+| `Ctrl/⌘ D` | Duplicate selected    | Canvas       |
+| `Delete`   | Delete selected block | Canvas       |
+| `Ctrl/⌘ S` | Save page             | Builder      |
+| `Escape`   | Close editor sheet    | Editor       |
+| `Tab`      | Focus next field      | Block editor |
+
+**Implementation**:
+
+```typescript
+// src/lib/useKeyboardShortcuts.ts
+export function useKeyboardShortcuts() {
+    const { selectedBlockId, deleteBlock, duplicateBlock } = useBuilder();
+    const updatePage = pageHooks.useUpdate();
+
+    useEffect(() => {
+        const handleKeyDown = (e: KeyboardEvent) => {
+            if (e.key === 'z' && (e.ctrlKey || e.metaKey)) {
+                e.preventDefault();
+                undo();
+            }
+            if (e.key === 'y' && (e.ctrlKey || e.metaKey)) {
+                e.preventDefault();
+                redo();
+            }
+            if (e.key === 'd' && (e.ctrlKey || e.metaKey) && selectedBlockId) {
+                e.preventDefault();
+                duplicateBlock(selectedBlockId);
+            }
+            if (e.key === 'Delete' && selectedBlockId) {
+                deleteBlock(selectedBlockId);
+            }
+        };
+
+        window.addEventListener('keydown', handleKeyDown);
+        return () => window.removeEventListener('keydown', handleKeyDown);
+    }, [selectedBlockId]);
+}
+```
+
+---
+
+### C. Undo/Redo (Action History)
+
+**Architecture**: Track mutations in builder state, allow forward/backward navigation.
+
+```typescript
+// src/lib/useActionHistory.ts
+interface Action {
+    type: 'add' | 'update' | 'delete' | 'reorder';
+    targetId: string;
+    before: Record<string, unknown>;
+    after: Record<string, unknown>;
+    timestamp: number;
+}
+
+export function useActionHistory() {
+    const [history, setHistory] = useState<Action[]>([]);
+    const [currentIndex, setCurrentIndex] = useState(-1);
+
+    const record = (action: Omit<Action, 'timestamp'>) => {
+        const newHistory = history.slice(0, currentIndex + 1);
+        newHistory.push({ ...action, timestamp: Date.now() });
+        setHistory(newHistory);
+        setCurrentIndex(newHistory.length - 1);
+    };
+
+    const undo = () => {
+        if (currentIndex > 0) {
+            const action = history[currentIndex - 1];
+            replayAction(action, 'undo');
+            setCurrentIndex(currentIndex - 1);
+        }
+    };
+
+    const redo = () => {
+        if (currentIndex < history.length - 1) {
+            const action = history[currentIndex + 1];
+            replayAction(action, 'redo');
+            setCurrentIndex(currentIndex + 1);
+        }
+    };
+
+    return { record, undo, redo, canUndo: currentIndex > 0, canRedo: currentIndex < history.length - 1 };
+}
+```
+
+---
+
+### D. Copy/Paste Blocks
+
+**Allows users to reuse common patterns**.
+
+```typescript
+// src/lib/useBlockClipboard.ts
+export function useBlockClipboard() {
+    const [clipboard, setClipboard] = useState<PageSectionRow | null>(null);
+
+    const copyBlock = (section: PageSectionRow) => {
+        setClipboard(section);
+        toast.success('Block copied');
+    };
+
+    const pasteBlock = async (pageId: string, afterSectionId?: string) => {
+        if (!clipboard) return;
+
+        const newSection = { ...clipboard, id: generateId(), pageId };
+        if (afterSectionId) {
+            // Insert after specified block
+            newSection.sortOrder = clipboard.sortOrder + 1;
+        }
+
+        const createSection = pageSectionHooks.useCreate();
+        createSection.mutate(newSection);
+        toast.success('Block pasted');
+    };
+
+    return { copyBlock, pasteBlock, hasClipboard: !!clipboard };
+}
+```
+
+---
+
+### E. Column Resizing (Split-Pane)
+
+**Allow users to adjust builder/preview ratio**:
+
+```tsx
+// src/components/ResizablePanes.tsx
+import { Rnd } from 'react-rnd';
+
+export function ResizableBuilderLayout() {
+    return (
+        <Rnd
+            default={{ x: 0, y: 0, width: '70%', height: '100%' }}
+            resizeHandleComponent={{ right: <div className="w-1 bg-border hover:bg-blue-500" /> }}
+            enableResizing={{ right: true }}
+        >
+            <BuilderPane />
+        </Rnd>
+    );
+}
+```
+
+---
+
+## 10.6 Quick UX Wins (Highest Impact, Low Effort)
+
+These are 1-3 hour improvements that dramatically improve the builder feel:
+
+### 1. **Block Icons in Palette + Canvas** (30 min)
+
+Add Lucide icons to block palette and canvas cards to make the builder visually scannable.
+
+```tsx
+// src/components/BlockPalette.tsx
+const BLOCK_ICONS = {
+    hero: 'Zap',
+    features: 'Grid3x3',
+    cta: 'Button',
+    navbar: 'Menu',
+    footer: 'LayoutFooter',
+    testimonials: 'MessageSquare',
+};
+
+{
+    blocks.map((block) => (
+        <div key={block.id} className="flex items-center gap-2 p-2 hover:bg-gray-100">
+            <Icon name={BLOCK_ICONS[block.id]} size={18} />
+            <span className="text-sm">{block.label}</span>
+        </div>
+    ));
+}
+```
+
+**Impact**: Builders visually identify blocks 3x faster.
+
+---
+
+### 2. **Empty State Messaging** (30 min)
+
+Show helpful hints when page has no blocks:
+
+```tsx
+// src/components/BlockCanvas.tsx
+if (sections.length === 0) {
+    return (
+        <div className="flex flex-col items-center justify-center h-96 bg-gray-50 rounded-lg border-2 border-dashed border-gray-300">
+            <div className="text-center">
+                <p className="text-gray-600 text-sm mb-4">No blocks yet. Start by adding one from the palette →</p>
+                <button onClick={() => selectBlock('hero')} className="px-4 py-2 bg-blue-500 text-white rounded">
+                    Add Hero Section
+                </button>
+            </div>
+        </div>
+    );
+}
+```
+
+**Impact**: First-time users understand what to do next immediately.
+
+---
+
+### 3. **Validation Errors in Block Editor** (30 min)
+
+Show red outlines and error messages for required fields:
+
+```tsx
+// src/components/BlockEditor.tsx
+export function BlockEditor({ block, definition }: Props) {
+    const [errors, setErrors] = useState<Record<string, string>>({});
+
+    const handleSave = () => {
+        const schema = buildBlockSchema(definition.fields);
+        const result = schema.safeParse(formData);
+
+        if (!result.success) {
+            const errorMap: Record<string, string> = {};
+            result.error.errors.forEach((err) => {
+                errorMap[err.path.join('.')] = err.message;
+            });
+            setErrors(errorMap);
+            return;
+        }
+
+        updateBlock(block.id, formData);
+    };
+
+    return (
+        <form>
+            {Object.entries(definition.fields).map(([fieldKey, fieldDef]) => (
+                <div key={fieldKey} className={errors[fieldKey] ? 'border-red-500' : ''}>
+                    <input value={formData[fieldKey]} />
+                    {errors[fieldKey] && <span className="text-red-500 text-xs">{errors[fieldKey]}</span>}
+                </div>
+            ))}
+        </form>
+    );
+}
+```
+
+**Impact**: Users never waste time fixing data validation errors after publishing.
+
+---
+
+### 4. **Publish Preview (Quick Visual Check)** (30 min)
+
+Show a mini preview of how the page looks before publish:
+
+```tsx
+// src/components/PublishDialog.tsx
+export function PublishDialog({ page }: Props) {
+    return (
+        <Dialog>
+            <div className="flex gap-4">
+                {/* Left: Settings */}
+                <div className="flex-1">
+                    <h3 className="text-sm font-semibold mb-4">Confirm & Publish</h3>
+                    <div className="space-y-3">
+                        <div>
+                            <label>URL Slug</label>
+                            <input value={page.slug} readOnly className="w-full px-2 py-1 border rounded bg-gray-100" />
+                        </div>
+                        <div>
+                            <label>SEO Title</label>
+                            <input value={page.seoTitle} />
+                        </div>
+                    </div>
+                </div>
+
+                {/* Right: Live Preview (375px mobile viewport) */}
+                <div className="w-96 bg-gray-100 rounded overflow-hidden">
+                    <LivePreviewPane pageId={page.id} viewport="mobile" />
+                </div>
+            </div>
+        </Dialog>
+    );
+}
+```
+
+**Impact**: Users see exactly what they're publishing before going live.
+
+---
+
+### 5. **Duplicate Page** (15 min)
+
+Add "Duplicate" option to pages list context menu:
+
+```tsx
+// src/pages/admin/pages/AdminPagesListPage.tsx
+const handleDuplicate = async (pageId: string) => {
+    const originalPage = await fetchPage(pageId);
+    const newPage = {
+        ...originalPage,
+        id: generateId(),
+        title: `${originalPage.title} (Copy)`,
+        slug: `${originalPage.slug}-copy-${Date.now()}`,
+        status: 'draft' as const,
+    };
+
+    createPage.mutate(newPage);
+
+    // Also duplicate all sections
+    const sections = await fetchSections(pageId);
+    sections.forEach((section) => {
+        createSection.mutate({
+            ...section,
+            id: generateId(),
+            pageId: newPage.id,
+        });
+    });
+
+    toast.success('Page duplicated');
+};
+```
+
+**Impact**: Template pages reduce time for new landing pages from 5 min to 30 sec.
+
+---
+
+### 6. **Bulk Section Import (JSON)** (1 hour)
+
+Let power users paste JSON to bulk-import sections:
+
+```tsx
+// src/components/BlockImportDialog.tsx
+const handleImportJSON = (json: string) => {
+    try {
+        const sections = JSON.parse(json);
+        sections.forEach((section) => {
+            createSection.mutate(section);
+        });
+        toast.success(`Imported ${sections.length} sections`);
+    } catch (e) {
+        toast.error('Invalid JSON');
+    }
+};
+```
+
+**Example JSON**:
+
+```json
+[
+    {
+        "slot": "hero",
+        "variant": "centered",
+        "title": "Welcome to our platform",
+        "subtitle": "Build landing pages in minutes",
+        "actions": [{ "label": "Get Started", "href": "/signup", "variant": "primary" }]
+    },
+    {
+        "slot": "features",
+        "variant": "grid",
+        "title": "Why choose us?",
+        "features": [
+            { "title": "Fast", "description": "Deployed in seconds" },
+            { "title": "Secure", "description": "Enterprise-grade" }
+        ]
+    }
+]
+```
+
+**Impact**: Designers or developers can pre-populate pages programmatically, then hand off to content team for
+refinement.
+
+---
+
+## Summary: UX/DX Priority Matrix
+
+| Feature                 | Effort  | Impact | Priority |
+| ----------------------- | ------- | ------ | -------- |
+| Block icons             | 30 min  | High   | **P0**   |
+| Empty state messaging   | 30 min  | High   | **P1**   |
+| Field validation errors | 30 min  | High   | **P1**   |
+| Publish preview         | 30 min  | Medium | **P1**   |
+| Duplicate page          | 15 min  | High   | **P0**   |
+| Bulk JSON import        | 1 hour  | Medium | **P2**   |
+| Inline title editing    | 1 hour  | Medium | **P2**   |
+| Undo/Redo               | 2 hours | High   | **P2**   |
+| Keyboard shortcuts      | 1 hour  | Medium | **P3**   |
+| Copy/Paste blocks       | 1 hour  | Medium | **P3**   |
+| Column resizing         | 30 min  | Low    | **P3**   |
+
+**Recommendation**: Ship P0 features (block icons ~15 min, duplicate ~15 min = 30 min ROI) immediately after MVP. Add P1
+features in second iteration.
+
+---
+
+## 11. File Paths Summary
+
+```
+Database & Models (TanStack App):
+├── ottabase/models/Page.schema.ts
+├── ottabase/models/PageSection.schema.ts
+├── ottabase/models/PageFeature.schema.ts
+├── ottabase/models/PageAction.schema.ts
+├── ottabase/models/Page.ts
+├── ottabase/models/PageSection.ts
+├── ottabase/models/PageFeature.ts
+├── ottabase/models/PageAction.ts
+├── ottabase/models/pagePolicy.ts (RLS policies)
+├── ottabase/db/schema.ts (exports all tables)
+├── ottabase/db/schemas-helper.ts (schema collection)
+├── ottabase/config.migrations.ts (registration)
+└── worker/lib/db-utils.ts (model & policy registration)
+
+API Routes (TanStack App):
+├── worker/routes/pages.ts (main implementation)
+├── worker/routes/router.ts (route registration)
+└── src/router.tsx (admin UI route registration)
+
+RLS Policies (TanStack App):
+├── ottabase/models/pagePolicy.ts (Page, PageSection, PageFeature, PageAction policies)
+└── Registered in worker/lib/db-utils.ts via registerPolicy()
+
+Contract Package:
+└── packages/homepage-contract/src/
+    ├── schemas.ts (Zod schemas for validation)
+    ├── types.ts (TypeScript inferred types)
+    └── index.ts (re-exports)
+
+Admin UI (TanStack App):
+├── src/pages/admin/pages/
+│   ├── index.ts (route exports)
+│   ├── AdminPagesListPage.tsx (pages list view)
+│   ├── AdminPageBuilderPage.tsx (builder container with tabs)
+│   ├── MarketingPageBuilder.tsx (main drag-and-drop builder)
+│   └── pages-constants.ts (block types, variants, constants)
+├── src/hooks/pageHooks.ts (CRUD hooks via createModelHooks)
+└── src/router.tsx (TanStack Router config with /admin/pages routes)
+
+Next.js Frontend (Next.js Homepage App):
+├── app/[slug]/page.tsx (dynamic route for marketing pages)
+├── app/[slug]/marketing-page-content.tsx (client component rendering logic)
+├── components/SlotRenderer.tsx (discriminated union slot renderer)
+├── components/variants/
+│   ├── hero/ (HeroCentered, HeroSplit, HeroMinimal)
+│   ├── features/ (FeaturesGrid, FeaturesCards, FeaturesList)
+│   ├── cta/ (CTADefault, CTABanner, CTAMinimal)
+│   ├── navbar/ (NavbarDefault, NavbarCentered, NavbarMinimal)
+│   ├── footer/ (FooterDefault, FooterMinimal, FooterColumns)
+│   └── about/ (AboutDefault, AboutMinimal, AboutDetailed)
+└── lib/api.ts (API client with fetch functions)
+```
+
+---
+
+## 12. Key Technical Decisions
+
+| Decision                                 | Rationale                                                      |
+| ---------------------------------------- | -------------------------------------------------------------- |
+| **4 tables (normalized)**                | Clean separation, cascade deletes, efficient queries           |
+| **Slot + Variant pattern**               | Write data once, render via any visual variant                 |
+| **Contract package**                     | Single source of truth, no type drift between API and frontend |
+| **Zod schemas**                          | Runtime validation + TypeScript inference                      |
+| **@dnd-kit for DnD**                     | Modern, accessible, React 18+ compatible                       |
+| **Preview mode via query param**         | Simple, no auth required for dev (can add token later)         |
+| **Discriminated union for SlotRenderer** | Compile-time enforcement of slot ↔ data type match             |
+| **Dynamic imports for variants**         | Code splitting, better performance                             |
+| **OttaORM for CRUD**                     | Consistent with rest of codebase, auto-hooks                   |
+| **Cascade deletes in DB**                | Data integrity, no orphan records                              |
+
+---
+
+## 13. Future Enhancements
+
+- **Undo/Redo** — Track action history in builder
+- **Block templates** — Pre-filled content for common patterns
+- **A/B testing** — Multiple versions of pages
+- **Analytics** — Track page views and conversions
+- **Scheduled publishing** — Publish at specific time
+- **Version history** — Restore previous versions
+- **Multi-language** — i18n for page content
+- **Theme builder** — Visual theme customization
+- **Form blocks** — Contact forms with submission handling
+- **Integration blocks** — Calendly, Stripe, etc.
+
+---
+
+## 13.5 Row-Level Security (RLS) — Data Access Control
+
+> **Important**: This system includes RLS policies to enforce data isolation. These are automatically enforced by the
+> OttaORM layer.
+
+### RLS Policy Files
+
+All pages system RLS policies are defined in `ottabase/models/pagePolicy.ts`:
+
+```typescript
+// File: ottabase/models/pagePolicy.ts
+export const pagePolicy = {
+    entity: 'pages',
+    tenant: {
+        field: 'appId',
+        description: 'Pages scoped to app',
+    },
+};
+
+export const pageSectionPolicy = {
+    entity: 'page_sections',
+    description: 'Sections inherit page scope via pageId FK',
+};
+
+export const pageFeaturePolicy = {
+    entity: 'page_features',
+    description: 'Features inherit section scope via sectionId FK',
+};
+
+export const pageActionPolicy = {
+    entity: 'page_actions',
+    description: 'Actions inherit section scope via sectionId FK',
+};
+```
+
+### Policy Registration
+
+Policies are registered in `worker/lib/db-utils.ts` during app initialization:
+
+```typescript
+// worker/lib/db-utils.ts
+function initDbConnection(env: CloudflareEnv) {
+    registerConnection('default', createD1Driver(env.OBCF_D1));
+
+    // Register policies before models
+    registerPolicy(pagePolicy);
+    registerPolicy(pageSectionPolicy);
+    registerPolicy(pageFeaturePolicy);
+    registerPolicy(pageActionPolicy);
+
+    // Register models (policies automatically enforced)
+    registerModels([Page, PageSection, PageFeature, PageAction, ...otherModels]);
+
+    // Initialize RLS rules for current context
+    initRLS();
+}
+```
+
+### Policy Behavior
+
+When a query is executed via OttaORM:
+
+1. **Tenant Rule** → If `appId` filter set, restrict results to matching appId
+2. **Cascade** → Sections, Features, Actions inherit parent scope automatically
+3. **No Bypassing** → Raw SQL queries must manually apply RLS (recommended: use OttaORM instead)
+
+**Example Query** (automatically scoped):
+
+```typescript
+// Assuming context has appId = "app-123"
+const pages = await Page.where({ status: 'published' });
+// Behind the scenes: SELECT * FROM pages WHERE status = 'published' AND appId = 'app-123'
+```
+
+### Multi-Tenant Isolation
+
+For SaaS deployments where multiple organizations share the system:
+
+```typescript
+// In handler context, set appId filter
+const pages = await Page.where({
+    status: 'published',
+    appId: currentOrgId, // Must specify orgId
+});
+
+// Cannot query across orgs (policy prevents it)
+const allPages = await Page.where({ status: 'published' }); // Error if appId required
+```
+
+---
+
+## 14. Problem Statement & Why This Exists
+
+### The Problem
+
+Before this system, marketing pages in Ottabase had two options:
+
+1. **Hardcoded in Next.js** — Fast but requires developer deployment for every text change
+2. **Blog posts (ottablog)** — Dynamic but limited to article format, no rich layouts
+
+Neither option allowed non-technical users to create landing pages with modern layouts (hero sections, feature grids,
+CTAs, testimonials).
+
+### The Solution
+
+A **block-based page builder** that:
+
+- Stores page structure in D1 (no code deploys for content changes)
+- Supports multiple visual variants per block (centered hero vs split hero)
+- Provides drag-and-drop UX for non-technical users
+- Maintains type safety from database to frontend via shared contract
+
+### Success Criteria
+
+| Metric                          | Target                                      |
+| ------------------------------- | ------------------------------------------- |
+| Time to create new landing page | < 5 minutes (no code)                       |
+| Time to update content          | < 30 seconds (edit → save → live)           |
+| Page render time (frontend)     | < 100ms (cached), < 300ms (cold)            |
+| Builder responsiveness          | < 50ms for drag operations                  |
+| Zero deployments for content    | Marketing team never needs DevOps for pages |
+
+---
+
+## 15. Design Principles
+
+### 1. **Blocks Are Data, Not Code**
+
+Blocks store structured data (title, features, actions). Visual rendering is decoupled via variants. _Same data,
+different designs._
+
+```
+Block Data: { slot: "hero", title: "Welcome", actions: [...] }
+     ↓
+Variant Selection: "centered" | "split" | "minimal"
+     ↓
+Component: <HeroCentered data={...} /> | <HeroSplit data={...} />
+```
+
+### 2. **Composition Over Configuration**
+
+Instead of one mega-block with 50 options, we have focused blocks:
+
+- `hero` → title, subtitle, actions
+- `features` → title, feature list
+- `cta` → title, description, actions
+
+Combine blocks to build complex pages.
+
+### 3. **Progressive Enhancement**
+
+Default content always works. Advanced options (custom CSS, metadata) are optional.
+
+### 4. **Type Safety End-to-End**
+
+```
+Drizzle Schema → OttaORM Model → API Response → Zod Validation → TypeScript Type → React Component
+```
+
+No `any` types. All transformations are explicit.
+
+### 5. **Minimal Admin, Maximum Render**
+
+Admin builder does complex work (DnD, inline editing). Public frontend is simple (fetch JSON → render components).
+
+---
+
+## 16. State Management Strategy
+
+### Admin Builder State
+
+```typescript
+// Local state (React useState/useReducer)
+interface BuilderState {
+    page: PageRow; // Current page metadata
+    blocks: PageSectionRow[]; // Ordered sections
+    selectedBlockId: string | null; // Currently selected for editing
+    isDirty: boolean; // Unsaved changes indicator
+    isReordering: boolean; // DnD in progress
+}
+
+// Server state (TanStack Query)
+// - pageHooks.useDetail(pageId) → page metadata
+// - pageSectionHooks.useList({ pageId }) → blocks
+// - pageFeatureHooks.useList({ sectionId }) → features for selected block
+// - pageActionHooks.useList({ sectionId }) → actions for selected block
+```
+
+### Data Flow
+
+```
+User Action (add block)
+     ↓
+Optimistic Update (local state + cache)
+     ↓
+Mutation (pageSectionHooks.useCreate)
+     ↓
+Server Response (success/error)
+     ↓
+Cache Invalidation (queryClient.invalidateQueries(['page_sections']))
+     ↓
+UI Re-render (new block appears)
+```
+
+### Mutation Strategies
+
+| Operation         | Strategy          | Rollback on Error               |
+| ----------------- | ----------------- | ------------------------------- |
+| Add block         | Optimistic        | Remove from cache               |
+| Delete block      | Optimistic        | Restore to cache                |
+| Reorder blocks    | Optimistic        | Restore original order          |
+| Edit block fields | Debounced (300ms) | Revert to server value          |
+| Add feature       | Optimistic        | Remove from cache               |
+| Publish page      | Await             | Show error toast, stay on draft |
+
+---
+
+## 17. Error Handling Matrix
+
+### API Errors
+
+| Error Code           | HTTP Status | Cause                       | User Message                          | Recovery Action               |
+| -------------------- | ----------- | --------------------------- | ------------------------------------- | ----------------------------- |
+| `PAGE_NOT_FOUND`     | 404         | Slug doesn't exist          | "Page not found"                      | Show 404 page                 |
+| `PAGE_NOT_PUBLISHED` | 404         | Page is draft (non-preview) | "Page not found"                      | Show 404 page                 |
+| `VALIDATION_ERROR`   | 400         | Invalid payload             | Field-specific message                | Highlight field, show message |
+| `SLUG_EXISTS`        | 409         | Duplicate slug              | "A page with this URL already exists" | Focus slug field              |
+| `DB_ERROR`           | 500         | D1 query failed             | "Something went wrong. Try again."    | Log error, show retry button  |
+| `RATE_LIMITED`       | 429         | Too many requests           | "Too many requests. Wait a moment."   | Disable button, auto-retry    |
+
+### Client Errors
+
+| Scenario                   | Detection                     | Handling                                |
+| -------------------------- | ----------------------------- | --------------------------------------- |
+| Network offline            | `navigator.onLine === false`  | Queue mutations, sync when online       |
+| Mutation timeout           | 10s without response          | Show retry option                       |
+| Optimistic update conflict | Server returns different data | Show conflict toast, use server version |
+| Stale data                 | `staleTime` exceeded          | Background refetch                      |
+| Component render error     | Error boundary catches        | Show fallback UI, log to error service  |
+
+### Validation Rules
+
+```typescript
+// Page validation
+const pageSchema = z.object({
+    title: z.string().min(1, 'Title is required').max(100, 'Title too long'),
+    slug: z
+        .string()
+        .min(1, 'URL slug is required')
+        .max(50, 'Slug too long')
+        .regex(/^[a-z0-9-]+$/, 'Slug must be lowercase letters, numbers, and hyphens only'),
+    status: z.enum(['draft', 'published', 'archived']),
+});
+
+// Section validation
+const sectionSchema = z.object({
+    title: z.string().max(200).nullable(),
+    subtitle: z.string().max(500).nullable(),
+    body: z.string().max(10000).nullable(),
+});
+
+// Action validation
+const actionSchema = z.object({
+    label: z.string().min(1, 'Button label required').max(50),
+    href: z.string().url('Must be a valid URL').or(z.string().startsWith('/')),
+});
+
+// Feature validation
+const featureSchema = z.object({
+    title: z.string().min(1, 'Feature title required').max(100),
+    description: z.string().max(500).nullable(),
+});
+```
+
+---
+
+## 18. Performance Considerations
+
+### Caching Strategy
+
+| Resource            | Cache Location | TTL     | Invalidation Trigger     |
+| ------------------- | -------------- | ------- | ------------------------ |
+| Page list (admin)   | TanStack Query | 30s     | Create/delete page       |
+| Page detail (admin) | TanStack Query | 60s     | Update page              |
+| Sections (admin)    | TanStack Query | 60s     | Any section mutation     |
+| Public page data    | Next.js ISR    | 60s     | Revalidate on publish    |
+| Nav pages           | Next.js ISR    | 60s     | Revalidate on nav change |
+| Variant components  | Dynamic import | Forever | Code deployment          |
+
+### Lazy Loading
+
+```typescript
+// Variant components are dynamically imported
+const VARIANT_COMPONENTS = {
+    hero: {
+        centered: dynamic(() => import('./variants/hero/HeroCentered')),
+        split: dynamic(() => import('./variants/hero/HeroSplit')),
+        // Only loaded when used
+    },
+};
+
+// Benefits:
+// - Initial bundle excludes unused variants
+// - Each variant ~5-15KB (post-compression)
+// - Total savings: ~50-100KB on initial load
+```
+
+### Database Optimization
+
+```sql
+-- Indexes for common queries
+CREATE INDEX pages_slug_idx ON pages(slug);
+CREATE INDEX pages_status_idx ON pages(status);
+CREATE INDEX pages_nav_idx ON pages(show_in_nav, nav_order);
+CREATE INDEX pages_app_idx ON pages(app_id);
+
+CREATE INDEX page_sections_page_idx ON page_sections(page_id, sort_order);
+CREATE INDEX page_features_section_idx ON page_features(section_id, sort_order);
+CREATE INDEX page_actions_section_idx ON page_actions(section_id, sort_order);
+
+-- Query pattern for /api/pages/:slug
+-- Single query with JOINs (vs multiple roundtrips)
+SELECT
+    p.*,
+    ps.*,
+    pf.*,
+    pa.*
+FROM pages p
+LEFT JOIN page_sections ps ON ps.page_id = p.id
+LEFT JOIN page_features pf ON pf.section_id = ps.id
+LEFT JOIN page_actions pa ON pa.section_id = ps.id
+WHERE p.slug = ? AND p.status = 'published'
+ORDER BY ps.sort_order, pf.sort_order, pa.sort_order;
+```
+
+### Bundle Size Targets
+
+| Component                | Max Size (gzipped) | Current |
+| ------------------------ | ------------------ | ------- |
+| Admin Page Builder       | 150KB              | ~120KB  |
+| Single variant component | 15KB               | ~8-12KB |
+| homepage-contract pkg    | 5KB                | ~3KB    |
+| SlotRenderer             | 10KB               | ~6KB    |
+
+---
+
+## 19. Security Considerations
+
+### Authentication & Authorization
+
+```typescript
+// Admin routes require authentication
+// File: worker/routes/router.ts
+router.use('/api/ottaorm/*', authMiddleware);  // OttaORM CRUD
+router.post('/api/pages/seed', authMiddleware); // Seed requires auth
+
+// Public routes (no auth)
+router.get('/api/pages/:slug', ...);  // Public page data
+router.get('/api/pages/nav', ...);    // Public nav data
+```
+
+### Input Sanitization
+
+```typescript
+// All user input is sanitized before storage
+function sanitizeHtml(input: string): string {
+    // Remove script tags, event handlers
+    return DOMPurify.sanitize(input, {
+        ALLOWED_TAGS: ['b', 'i', 'em', 'strong', 'a', 'p', 'br'],
+        ALLOWED_ATTR: ['href', 'target', 'rel'],
+    });
+}
+
+// Applied to: body, subtitle (markdown/HTML content)
+// NOT applied to: title, label (plain text only)
+```
+
+### Preview Mode Security
+
+```typescript
+// Preview mode considerations:
+// - ?preview=true bypasses status check
+// - Currently no auth required (for dev convenience)
+// - Production should add signed token:
+
+// Secure preview URL generation (admin)
+const previewToken = signJWT({ pageId, exp: Date.now() + 3600000 }, SECRET);
+const previewUrl = `/${slug}?preview=true&token=${previewToken}`;
+
+// Secure preview verification (frontend)
+const isValidPreview = preview === 'true' && verifyJWT(token, SECRET);
+```
+
+### RBAC Integration
+
+```typescript
+// Page operations require specific permissions
+const PAGE_PERMISSIONS = {
+    'pages.create': ['admin', 'marketing'],
+    'pages.update': ['admin', 'marketing', 'editor'],
+    'pages.delete': ['admin'],
+    'pages.publish': ['admin', 'marketing'],
+    'pages.preview': ['admin', 'marketing', 'editor'],
+};
+
+// Check in route handler
+if (!hasPermission(user, 'pages.publish')) {
+    return errorResponse('Insufficient permissions', 403);
+}
+```
+
+---
+
+## 20. Testing Strategy
+
+### Unit Tests
+
+```typescript
+// File: __tests__/models/Page.test.ts
+describe('Page Model', () => {
+    it('generates unique slug from title', async () => {
+        const page = await Page.create({ title: 'My Landing Page' });
+        expect(page.get('slug')).toMatch(/^my-landing-page(-\d+)?$/);
+    });
+
+    it('validates slug format', async () => {
+        await expect(Page.create({ title: 'Test', slug: 'Invalid Slug!' })).rejects.toThrow(/slug must be lowercase/);
+    });
+
+    it('cascades delete to sections', async () => {
+        const page = await Page.create({ title: 'Test' });
+        await PageSection.create({ pageId: page.get('id'), slot: 'hero' });
+
+        await page.delete();
+
+        const sections = await PageSection.where({ pageId: page.get('id') });
+        expect(sections).toHaveLength(0);
+    });
+});
+```
+
+### Integration Tests (API)
+
+```typescript
+// File: __tests__/api/pages.test.ts
+describe('GET /api/pages/:slug', () => {
+    beforeEach(async () => {
+        await seedHomepage();
+    });
+
+    it('returns published page with sections', async () => {
+        const res = await fetch('/api/pages/homepage');
+        const data = await res.json();
+
+        expect(res.status).toBe(200);
+        expect(data.page.slug).toBe('homepage');
+        expect(data.sections).toBeInstanceOf(Array);
+        expect(data.sections.length).toBeGreaterThan(0);
+    });
+
+    it('returns 404 for draft page without preview flag', async () => {
+        await Page.create({ title: 'Draft', slug: 'draft-page', status: 'draft' });
+
+        const res = await fetch('/api/pages/draft-page');
+        expect(res.status).toBe(404);
+    });
+
+    it('returns draft page with preview=true', async () => {
+        await Page.create({ title: 'Draft', slug: 'draft-page', status: 'draft' });
+
+        const res = await fetch('/api/pages/draft-page?preview=true');
+        expect(res.status).toBe(200);
+    });
+});
+```
+
+### Component Tests
+
+```typescript
+// File: __tests__/components/SlotRenderer.test.tsx
+describe('SlotRenderer', () => {
+    it('renders correct hero variant', () => {
+        render(<SlotRenderer slot="hero" variant="centered" data={mockHeroData} />);
+        expect(screen.getByRole('heading')).toHaveTextContent(mockHeroData.title);
+    });
+
+    it('falls back to default variant', () => {
+        render(<SlotRenderer slot="hero" data={mockHeroData} />);
+        // Should render centered (default) without error
+        expect(screen.getByRole('heading')).toBeInTheDocument();
+    });
+
+    it('handles missing variant gracefully', () => {
+        const consoleSpy = vi.spyOn(console, 'warn');
+        render(<SlotRenderer slot="hero" variant="nonexistent" data={mockHeroData} />);
+        expect(consoleSpy).toHaveBeenCalledWith(expect.stringContaining('No component found'));
+    });
+});
+```
+
+### E2E Tests (Playwright)
+
+```typescript
+// File: e2e/page-builder.spec.ts
+test.describe('Marketing Page Builder', () => {
+    test.beforeEach(async ({ page }) => {
+        await page.goto('/admin/pages');
+        await page.click('button:has-text("New Page")');
+    });
+
+    test('creates page and adds hero block', async ({ page }) => {
+        // Add hero block from palette
+        await page.click('[data-block-type="hero"]');
+
+        // Verify block appears in canvas
+        await expect(page.locator('[data-block-slot="hero"]')).toBeVisible();
+
+        // Click block to edit
+        await page.click('[data-block-slot="hero"]');
+
+        // Fill title
+        await page.fill('input[name="title"]', 'Welcome to My Site');
+
+        // Save and verify
+        await page.click('button:has-text("Save")');
+        await expect(page.locator('.toast')).toHaveText(/saved/i);
+    });
+
+    test('reorders blocks via drag and drop', async ({ page }) => {
+        // Add two blocks
+        await page.click('[data-block-type="hero"]');
+        await page.click('[data-block-type="features"]');
+
+        // Get initial order
+        const blocks = page.locator('[data-block-slot]');
+        await expect(blocks.nth(0)).toHaveAttribute('data-block-slot', 'hero');
+        await expect(blocks.nth(1)).toHaveAttribute('data-block-slot', 'features');
+
+        // Drag features above hero
+        await page
+            .locator('[data-block-slot="features"] [data-drag-handle]')
+            .dragTo(page.locator('[data-block-slot="hero"]'));
+
+        // Verify new order
+        await expect(blocks.nth(0)).toHaveAttribute('data-block-slot', 'features');
+        await expect(blocks.nth(1)).toHaveAttribute('data-block-slot', 'hero');
+    });
+
+    test('previews draft page', async ({ page, context }) => {
+        await page.click('[data-block-type="hero"]');
+
+        // Click preview
+        const [previewPage] = await Promise.all([context.waitForEvent('page'), page.click('a:has-text("Preview")')]);
+
+        // Verify preview banner
+        await expect(previewPage.locator('.bg-amber-500')).toContainText('Preview Mode');
+    });
+});
+```
+
+---
+
+## 21. Debugging Guide
+
+### Common Issues
+
+#### 1. "Page not found" after creating page
+
+**Cause**: Page status is `draft` by default.
+
+**Solution**: Either:
+
+- Publish the page (Settings → Status → Published)
+- Use preview mode (`?preview=true`)
+
+#### 2. Blocks not saving
+
+**Cause**: Mutation error not shown (silent failure).
+
+**Debug**:
+
+```typescript
+// Add to useMutation onError
+onError: (error) => {
+    console.error('Block save failed:', error);
+    toast.error(error.message);
+};
+```
+
+#### 3. Variant component not rendering
+
+**Cause**: Dynamic import failed or variant doesn't exist.
+
+**Debug**:
+
+```typescript
+// Check console for:
+// "No component found for slot=X variant=Y"
+
+// Verify variant exists in VARIANT_COMPONENTS
+console.log(Object.keys(VARIANT_COMPONENTS.hero)); // ['centered', 'split', 'minimal']
+```
+
+#### 4. Features/Actions not appearing
+
+**Cause**: Section ID mismatch or missing data.
+
+**Debug**:
+
+```bash
+# Check API response
+curl http://localhost:3004/api/pages/my-page | jq '.sections[].features'
+```
+
+#### 5. DnD not working
+
+**Cause**: Missing @dnd-kit context or wrong strategy.
+
+**Debug**:
+
+```typescript
+// Verify DndContext wraps the sortable area
+<DndContext sensors={sensors} collisionDetection={closestCenter}>
+    <SortableContext items={blockIds} strategy={verticalListSortingStrategy}>
+        {/* blocks */}
+    </SortableContext>
+</DndContext>
+```
+
+### Logging Points
+
+```typescript
+// API handler
+console.log('[pages] Fetching page:', { slug, preview, appId });
+console.log('[pages] Found sections:', sections.length);
+
+// Builder mutations
+console.log('[builder] Adding block:', { slot, pageId });
+console.log('[builder] Reordering:', { oldIndex, newIndex });
+
+// Frontend rendering
+console.log('[SlotRenderer] Rendering:', { slot, variant, hasData: !!data });
+```
+
+### Database Queries
+
+```sql
+-- Find all pages with section counts
+SELECT p.*, COUNT(ps.id) as section_count
+FROM pages p
+LEFT JOIN page_sections ps ON ps.page_id = p.id
+GROUP BY p.id;
+
+-- Find orphan sections (no parent page)
+SELECT ps.* FROM page_sections ps
+LEFT JOIN pages p ON p.id = ps.page_id
+WHERE p.id IS NULL;
+
+-- Check page data integrity
+SELECT
+    p.slug,
+    (SELECT COUNT(*) FROM page_sections WHERE page_id = p.id) as sections,
+    (SELECT COUNT(*) FROM page_sections ps
+     JOIN page_features pf ON pf.section_id = ps.id
+     WHERE ps.page_id = p.id) as features,
+    (SELECT COUNT(*) FROM page_sections ps
+     JOIN page_actions pa ON pa.section_id = ps.id
+     WHERE ps.page_id = p.id) as actions
+FROM pages p;
+```
+
+---
+
+## 22. Adding New Block Types
+
+### Step-by-Step Guide
+
+When adding a new block type (e.g., "Testimonials"):
+
+#### 1. Add to SlotType enum
+
+```typescript
+// File: ottabase/models/PageSection.schema.ts
+export type SlotType =
+    // ... existing types
+    'testimonials'; // ← Add new type
+```
+
+#### 2. Add to BLOCK_TYPES config
+
+```typescript
+// File: src/pages/admin/pages/pages-constants.ts
+export const BLOCK_TYPES: SlotConfig[] = [
+    // ... existing blocks
+    {
+        id: 'testimonials',
+        label: 'Testimonials',
+        icon: Quote,
+        description: 'Customer testimonials in carousel or grid',
+        supportsFeatures: true,  // Each testimonial is a "feature"
+        supportsActions: false,
+        singleton: false,
+        defaultVariant: 'carousel',
+    },
+];
+
+export const BLOCK_VARIANTS: Record<string, ...> = {
+    // ... existing variants
+    testimonials: [
+        { id: 'carousel', label: 'Carousel' },
+        { id: 'grid', label: 'Grid' },
+        { id: 'single', label: 'Single Quote' },
+    ],
+};
+```
+
+#### 3. Create variant components
+
+```typescript
+// File: components/variants/testimonials/types.ts
+export interface TestimonialItem {
+    title: string;      // Person's name
+    description: string; // Quote text
+    imageUrl?: string;  // Avatar
+    href?: string;      // Company/role link
+}
+
+export interface TestimonialsData {
+    title: string;
+    features: TestimonialItem[];  // Reuse "features" structure
+}
+
+// File: components/variants/testimonials/TestimonialsCarousel.tsx
+export default function TestimonialsCarousel({ data }: { data: TestimonialsData }) {
+    return (
+        <section className="py-20">
+            <h2 className="text-3xl font-bold text-center mb-12">{data.title}</h2>
+            <div className="relative overflow-hidden">
+                {/* Carousel implementation */}
+            </div>
+        </section>
+    );
+}
+```
+
+#### 4. Register in SlotRenderer
+
+```typescript
+// File: components/SlotRenderer.tsx
+import type { TestimonialsData } from './variants/testimonials/types';
+
+type SlotRendererProps =
+    // ... existing props
+    { slot: 'testimonials'; data: TestimonialsData; variant?: string };
+
+const VARIANT_COMPONENTS = {
+    // ... existing
+    testimonials: {
+        carousel: dynamic(() => import('./variants/testimonials/TestimonialsCarousel')),
+        grid: dynamic(() => import('./variants/testimonials/TestimonialsGrid')),
+        single: dynamic(() => import('./variants/testimonials/TestimonialsSingle')),
+    },
+};
+
+const DEFAULT_VARIANTS = {
+    // ... existing
+    testimonials: 'carousel',
+};
+```
+
+#### 5. Add transformation in marketing-page-content.tsx
+
+```typescript
+// File: app/[slug]/marketing-page-content.tsx
+function transformSection(section: PageSectionPayload) {
+    switch (slot) {
+        // ... existing cases
+
+        case 'testimonials':
+            return {
+                slot: 'testimonials',
+                data: {
+                    title: title || 'What Our Customers Say',
+                    features: features.map((f) => ({
+                        title: f.title, // Person's name
+                        description: f.description || '',
+                        imageUrl: f.imageUrl || undefined,
+                        href: f.href || undefined,
+                    })),
+                } satisfies TestimonialsData,
+            };
+    }
+}
+```
+
+#### 6. Update contract package
+
+```typescript
+// File: packages/homepage-contract/src/types.ts
+export interface TestimonialItem {
+    title: string;
+    description: string;
+    imageUrl: string | null;
+    href: string | null;
+}
+
+export interface TestimonialsData {
+    title: string;
+    features: TestimonialItem[];
+}
+```
+
+---
+
+## 23. Keyboard Shortcuts & Accessibility
+
+### Admin Builder Keyboard Shortcuts
+
+| Shortcut       | Action                               |
+| -------------- | ------------------------------------ |
+| `Escape`       | Close block editor / deselect block  |
+| `Delete`       | Delete selected block (with confirm) |
+| `Ctrl+S`       | Force save all changes               |
+| `Ctrl+Z`       | Undo (if implemented)                |
+| `Ctrl+Shift+Z` | Redo (if implemented)                |
+| `↑ / ↓`        | Navigate between blocks              |
+| `Enter`        | Open editor for selected block       |
+
+### Accessibility Requirements
+
+```tsx
+// Block in canvas must be focusable
+<div
+    role="listitem"
+    tabIndex={0}
+    aria-selected={isSelected}
+    aria-label={`${block.slot} block: ${block.title || 'Untitled'}`}
+    onKeyDown={(e) => {
+        if (e.key === 'Enter') onSelect();
+        if (e.key === 'Delete') onDelete();
+    }}
+>
+
+// Drag handle must have aria-label
+<button
+    aria-label="Drag to reorder"
+    aria-roledescription="sortable"
+    {...listeners}  // @dnd-kit listeners
+>
+    <GripVertical />
+</button>
+
+// Block palette items
+<button
+    role="menuitem"
+    aria-label={`Add ${block.label} block`}
+    disabled={block.singleton && existingBlocks.includes(block.id)}
+>
+```
+
+### Screen Reader Announcements
+
+```typescript
+// Use live regions for DnD feedback
+const [announcement, setAnnouncement] = useState('');
+
+function onDragStart({ active }) {
+    setAnnouncement(`Picked up ${active.data.current.slot} block`);
+}
+
+function onDragEnd({ active, over }) {
+    if (over) {
+        setAnnouncement(`Moved ${active.data.current.slot} block to position ${newIndex + 1}`);
+    } else {
+        setAnnouncement('Drag cancelled');
+    }
+}
+
+// Render live region
+<div aria-live="polite" aria-atomic="true" className="sr-only">
+    {announcement}
+</div>
+```
+
+---
+
+## 24. Cache Invalidation Strategy
+
+### When to Invalidate
+
+| Event            | Invalidate                            | Method                      |
+| ---------------- | ------------------------------------- | --------------------------- |
+| Create page      | `['pages']` list                      | `invalidateQueries`         |
+| Update page      | `['pages', pageId]`, `['pages']` list | `invalidateQueries`         |
+| Delete page      | `['pages', pageId]`, `['pages']` list | `invalidateQueries`         |
+| Create section   | `['page_sections', { pageId }]`       | `invalidateQueries`         |
+| Update section   | `['page_sections', { pageId }]`       | `setQueryData` (optimistic) |
+| Delete section   | `['page_sections', { pageId }]`       | `invalidateQueries`         |
+| Reorder sections | `['page_sections', { pageId }]`       | `setQueryData` (optimistic) |
+| Publish page     | Public page cache (Next.js)           | `revalidatePath`            |
+
+### Implementation
+
+```typescript
+// Admin mutations (TanStack Query)
+const createSection = useMutation({
+    mutationFn: (data) => pageSectionHooks.create(data),
+    onMutate: async (newSection) => {
+        // Cancel outgoing refetches
+        await queryClient.cancelQueries({ queryKey: ['page_sections', { pageId }] });
+
+        // Snapshot previous value
+        const previous = queryClient.getQueryData(['page_sections', { pageId }]);
+
+        // Optimistically add new section
+        queryClient.setQueryData(['page_sections', { pageId }], (old) => [
+            ...old,
+            { ...newSection, id: `temp-${Date.now()}` },
+        ]);
+
+        return { previous };
+    },
+    onError: (err, newSection, context) => {
+        // Rollback on error
+        queryClient.setQueryData(['page_sections', { pageId }], context.previous);
+    },
+    onSettled: () => {
+        // Refetch to ensure consistency
+        queryClient.invalidateQueries({ queryKey: ['page_sections', { pageId }] });
+    },
+});
+
+// Public page cache (Next.js)
+// File: worker/routes/pages.ts
+export async function handleUpdatePage(context, pageId) {
+    // ... update logic
+
+    const page = await Page.find(pageId);
+    if (page.get('status') === 'published') {
+        // Trigger ISR revalidation
+        await fetch(`${HOMEPAGE_URL}/api/revalidate?path=/${page.get('slug')}`, {
+            method: 'POST',
+            headers: { 'x-revalidate-secret': env.REVALIDATE_SECRET },
+        });
+    }
+}
+```
+
+---
+
+## 25. Rollback & Recovery Procedures
+
+### Accidental Page Deletion
+
+Pages are soft-deleted (status: 'archived') by default. Hard delete requires confirmation.
+
+```typescript
+// Soft delete (recoverable)
+async function archivePage(pageId: string) {
+    await Page.update(pageId, { status: 'archived' });
+}
+
+// Hard delete (with confirmation in UI)
+async function permanentlyDeletePage(pageId: string) {
+    await Page.delete(pageId); // Cascades to sections/features/actions
+}
+
+// Recovery
+async function recoverPage(pageId: string) {
+    await Page.update(pageId, { status: 'draft' });
+}
+```
+
+### Restoring Previous Version
+
+```typescript
+// Version history (if implemented)
+interface PageVersion {
+    id: string;
+    pageId: string;
+    data: PageDataPayload; // Full snapshot
+    createdAt: number;
+    createdBy: string;
+}
+
+// Create version before major changes
+async function createVersion(pageId: string) {
+    const pageData = await fetchFullPageData(pageId);
+    await PageVersion.create({
+        pageId,
+        data: pageData,
+        createdBy: getCurrentUserId(),
+    });
+}
+
+// Restore from version
+async function restoreVersion(versionId: string) {
+    const version = await PageVersion.find(versionId);
+    const { sections, ...pageData } = version.get('data');
+
+    // Delete current sections
+    await PageSection.where({ pageId: version.get('pageId') }).delete();
+
+    // Restore page metadata
+    await Page.update(version.get('pageId'), pageData);
+
+    // Restore sections with features/actions
+    for (const section of sections) {
+        const newSection = await PageSection.create({
+            pageId: version.get('pageId'),
+            ...section,
+        });
+
+        for (const feature of section.features) {
+            await PageFeature.create({ sectionId: newSection.get('id'), ...feature });
+        }
+
+        for (const action of section.actions) {
+            await PageAction.create({ sectionId: newSection.get('id'), ...action });
+        }
+    }
+}
+```
+
+### Database Backup/Restore
+
+```bash
+# Backup D1 database (Cloudflare CLI)
+wrangler d1 export OBCF_D1 --output=backup-$(date +%Y%m%d).sql
+
+# Restore
+wrangler d1 execute OBCF_D1 --file=backup-20260331.sql
+```
+
+---
+
+## 26. Multi-Tenant Considerations
+
+### App Isolation
+
+Every page belongs to an `appId`. Queries must scope by appId:
+
+```typescript
+// Model method with RLS context
+static async getForApp(appId: string): Promise<Page[]> {
+    return this.where({ appId, status: 'published' });
+}
+
+// API handler extracts appId from context
+const appId = context.appId; // From RLS context
+const pages = await Page.where({ ...where, appId });
+```
+
+### Slug Uniqueness
+
+Slugs are unique **per appId**, not globally:
+
+```sql
+-- Unique constraint in schema
+CREATE UNIQUE INDEX pages_app_slug_idx ON pages(app_id, slug);
+```
+
+### Template Sharing
+
+Pages can be marked as templates and copied across apps:
+
+```typescript
+interface PageTemplate {
+    id: string;
+    name: string;
+    thumbnail: string;
+    pageData: Omit<PageDataPayload, 'page.id' | 'page.appId'>;
+}
+
+async function createFromTemplate(templateId: string, appId: string, slug: string) {
+    const template = await PageTemplate.find(templateId);
+    const { sections, display } = template.get('pageData');
+
+    const page = await Page.create({
+        appId,
+        slug,
+        title: template.get('name'),
+        ...display,
+    });
+
+    // Copy sections with features/actions
+    for (const section of sections) {
+        // ... create section and children
+    }
+
+    return page;
+}
+```
+
+---
+
+## 27. Analytics Integration
+
+### Page View Tracking
+
+```typescript
+// Frontend - Fire on page render
+useEffect(() => {
+    trackPageView({
+        pageId: pageData.page.id,
+        slug: pageData.page.slug,
+        referrer: document.referrer,
+        userAgent: navigator.userAgent,
+    });
+}, [pageData.page.id]);
+
+// API endpoint
+POST /api/analytics/pageview
+{
+    "pageId": "...",
+    "slug": "pricing",
+    "referrer": "https://google.com",
+    "sessionId": "..."
+}
+```
+
+### Block Performance
+
+Track which blocks get the most engagement:
+
+```typescript
+// Track CTA clicks
+function trackBlockClick(sectionId: string, actionId: string) {
+    fetch('/api/analytics/click', {
+        method: 'POST',
+        body: JSON.stringify({ sectionId, actionId }),
+    });
+}
+
+// Dashboard shows:
+// - Click-through rate per CTA
+// - Time on page
+// - Scroll depth (which blocks are seen)
+```
+
+---
+
+## 28. API Reference (OpenAPI Summary)
+
+### Endpoints
+
+| Method | Path                           | Auth? | Description                         |
+| ------ | ------------------------------ | ----- | ----------------------------------- |
+| GET    | `/api/pages/:slug`             | No    | Get page by slug (public + preview) |
+| GET    | `/api/pages/nav`               | No    | Get nav-enabled pages               |
+| POST   | `/api/pages/seed`              | Yes   | Seed default homepage               |
+| GET    | `/api/ottaorm/pages`           | Yes   | List pages (admin)                  |
+| POST   | `/api/ottaorm/pages`           | Yes   | Create page                         |
+| PUT    | `/api/ottaorm/pages/:id`       | Yes   | Update page                         |
+| DELETE | `/api/ottaorm/pages/:id`       | Yes   | Delete page                         |
+| ...    | `/api/ottaorm/page_sections/*` | Yes   | Section CRUD                        |
+| ...    | `/api/ottaorm/page_features/*` | Yes   | Feature CRUD                        |
+| ...    | `/api/ottaorm/page_actions/*`  | Yes   | Action CRUD                         |
+
+### Request/Response Examples
+
+```bash
+# Get public page
+GET /api/pages/pricing
+→ 200 { page: {...}, sections: [...], display: {...}, content: null }
+
+# Get with preview
+GET /api/pages/pricing?preview=true
+→ 200 { page: { status: 'draft', ... }, ... }
+
+# Create page (admin)
+POST /api/ottaorm/pages
+Content-Type: application/json
+Authorization: Bearer <token>
+{ "title": "New Landing Page", "slug": "new-landing" }
+→ 201 { "id": "uuid...", ... }
+
+# Update section
+PUT /api/ottaorm/page_sections/section-uuid
+Content-Type: application/json
+Authorization: Bearer <token>
+{ "title": "Updated Hero Title", "variant": "split" }
+→ 200 { "id": "section-uuid", "title": "Updated Hero Title", ... }
+```
+
+---
+
+## 29. Glossary
+
+| Term             | Definition                                                            |
+| ---------------- | --------------------------------------------------------------------- |
+| **Block**        | A section of a page (hero, features, CTA). Stored as `page_sections`. |
+| **Slot**         | The type of a block (`hero`, `features`, `cta`, etc.).                |
+| **Variant**      | Visual style of a block (`centered`, `split`, `grid`).                |
+| **Feature**      | An item within a block (a feature card, testimonial, FAQ item).       |
+| **Action**       | A CTA button within a block (label, href, variant).                   |
+| **Canvas**       | The drag-and-drop area showing page blocks.                           |
+| **Palette**      | The sidebar showing available block types to add.                     |
+| **Contract**     | Shared TypeScript types + Zod schemas between API and frontend.       |
+| **Preview Mode** | Viewing a draft page via `?preview=true`.                             |
+| **ISR**          | (Incremental Static Regeneration) Next.js caching strategy.           |
+| **OttaORM**      | Ottabase's fat-model ORM built on Drizzle.                            |
+
+---
+
+_Document Version: 2.0_  
+_Last Updated: March 2026_  
+_Maintainer: @thinkdj_
diff --git a/docs/MARKETING_PAGES_FEATURE_SPEC_OPTIMIZED.md b/docs/MARKETING_PAGES_FEATURE_SPEC_OPTIMIZED.md
new file mode 100644
index 000000000..646eacf89
--- /dev/null
+++ b/docs/MARKETING_PAGES_FEATURE_SPEC_OPTIMIZED.md
@@ -0,0 +1,1116 @@
+# Marketing Pages System — Optimized Feature Spec
+
+> **Purpose**: Drag-and-drop marketing page builder with database-driven block rendering. For detailed docs, see
+> [MARKETING_PAGES_FEATURE_SPEC.md](MARKETING_PAGES_FEATURE_SPEC.md).
+
+---
+
+## Quick Start
+
+| What                    | Location                                      |
+| ----------------------- | --------------------------------------------- |
+| **Database Schema**     | [Section 3](#3-database-schema)               |
+| **OttaORM Models**      | [Section 4](#4-models)                        |
+| **API Endpoints**       | [Section 5](#5-api-routes)                    |
+| **Admin UI Build**      | [Section 7](#7-admin-ui)                      |
+| **UI/UX Requirements**  | [Section 9](#9-uiux-requirements)             |
+| **Implementation Plan** | [Section 10](#10-implementation)              |
+| **Security & Auth**     | [Section 11](#11-security--authentication)    |
+| **Cache Strategy**      | [Section 12](#12-cache-invalidation-strategy) |
+| **Testing**             | [Section 13](#13-testing-strategy)            |
+| **Debugging**           | [Section 14](#14-debugging-checklist)         |
+
+---
+
+## 1. System Overview
+
+### Architecture Diagram
+
+```
+Admin UI (TanStack) → Worker API (Cloudflare) → D1 SQLite
+                         ↓
+                   Next.js Homepage
+                   (Dynamic [slug] route)
+```
+
+### Key Concepts
+
+- **Blocks**: Reusable content sections (hero, features, CTA, testimonials)
+- **Variants**: Visual presentations of blocks (centered vs split, grid vs carousel)
+- **Slot Pattern**: Single data structure, multiple renderers
+- **Preview Mode**: Draft pages visible via `?preview=true`
+
+---
+
+## 2. Database Schema (4 Tables)
+
+### pages
+
+```sql
+CREATE TABLE pages (
+    id TEXT PRIMARY KEY,
+    appId TEXT NOT NULL,
+    slug TEXT NOT NULL,
+    title TEXT NOT NULL,
+    status TEXT NOT NULL DEFAULT 'draft', -- 'draft' | 'published' | 'archived'
+    createdAt INTEGER NOT NULL,
+    updatedAt INTEGER NOT NULL,
+    UNIQUE(appId, slug)
+);
+```
+
+### page_sections
+
+```sql
+CREATE TABLE page_sections (
+    id TEXT PRIMARY KEY,
+    pageId TEXT NOT NULL REFERENCES pages(id) ON DELETE CASCADE,
+    slot TEXT NOT NULL, -- 'hero', 'features', 'cta', etc.
+    variant TEXT NOT NULL,
+    title TEXT,
+    subtitle TEXT,
+    body TEXT,
+    enabled INTEGER DEFAULT 1,
+    sortOrder INTEGER NOT NULL DEFAULT 0,
+    createdAt INTEGER NOT NULL,
+    updatedAt INTEGER NOT NULL
+);
+```
+
+### page_features & page_actions
+
+```sql
+CREATE TABLE page_features (
+    id TEXT PRIMARY KEY,
+    sectionId TEXT NOT NULL REFERENCES page_sections(id) ON DELETE CASCADE,
+    title TEXT NOT NULL,
+    description TEXT,
+    icon TEXT,
+    link TEXT,
+    sortOrder INTEGER NOT NULL DEFAULT 0,
+    createdAt INTEGER NOT NULL
+);
+
+CREATE TABLE page_actions (
+    id TEXT PRIMARY KEY,
+    sectionId TEXT NOT NULL REFERENCES page_sections(id) ON DELETE CASCADE,
+    label TEXT NOT NULL,
+    href TEXT NOT NULL,
+    variant TEXT DEFAULT 'default',
+    icon TEXT,
+    external INTEGER DEFAULT 0,
+    sortOrder INTEGER NOT NULL DEFAULT 0,
+    createdAt INTEGER NOT NULL
+);
+```
+
+---
+
+## 3. OttaORM Models
+
+### Page Model
+
+```typescript
+export class Page extends BaseModel {
+    static entity = 'pages';
+    static table = pagesTable;
+    static primaryKey = 'id';
+
+    // Methods
+    async sections() {
+        return PageSection.where({ pageId: this.get('id') });
+    }
+
+    publish() {
+        this.set('status', 'published');
+        return this.save();
+    }
+
+    draft() {
+        this.set('status', 'draft');
+        return this.save();
+    }
+}
+```
+
+### PageSection Model
+
+```typescript
+export class PageSection extends BaseModel {
+    static entity = 'page_sections';
+    static table = pageSectionsTable;
+
+    async features() {
+        return PageFeature.where({ sectionId: this.get('id') }).orderBy('sortOrder');
+    }
+
+    async actions() {
+        return PageAction.where({ sectionId: this.get('id') }).orderBy('sortOrder');
+    }
+
+    static async getForPage(pageId: string) {
+        return this.where({ pageId }).orderBy('sortOrder');
+    }
+}
+```
+
+### PageFeature & PageAction Models
+
+```typescript
+export class PageFeature extends BaseModel {
+    static entity = 'page_features';
+    static table = pageFeaturesTable;
+
+    static async getForSection(sectionId: string) {
+        return this.where({ sectionId }).orderBy('sortOrder');
+    }
+}
+
+export class PageAction extends BaseModel {
+    static entity = 'page_actions';
+    static table = pageActionsTable;
+
+    static async getForSection(sectionId: string) {
+        return this.where({ sectionId }).orderBy('sortOrder');
+    }
+}
+```
+
+---
+
+## 4. API Routes
+
+### Public Routes
+
+| Method | Endpoint           | Purpose                                    |
+| ------ | ------------------ | ------------------------------------------ |
+| GET    | `/api/pages/:slug` | Fetch page + sections + features + actions |
+| GET    | `/api/pages/nav`   | Nav-enabled pages only                     |
+
+### Admin CRUD (Auto-generated by OttaORM)
+
+| Method   | Endpoint                     | Purpose       |
+| -------- | ---------------------------- | ------------- |
+| GET      | `/api/ottaorm/pages`         | List pages    |
+| POST     | `/api/ottaorm/pages`         | Create page   |
+| PUT      | `/api/ottaorm/pages/:id`     | Update page   |
+| DELETE   | `/api/ottaorm/pages/:id`     | Delete page   |
+| GET/POST | `/api/ottaorm/page_sections` | Sections CRUD |
+| GET/POST | `/api/ottaorm/page_features` | Features CRUD |
+| GET/POST | `/api/ottaorm/page_actions`  | Actions CRUD  |
+
+---
+
+## 5. Contract Package
+
+### TypeScript Types
+
+```typescript
+// @ottabase/marketing-pages-contract
+
+export type PageStatus = 'draft' | 'published' | 'archived';
+export type BlockSlot = 'hero' | 'features' | 'cta' | 'testimonials' | 'navbar' | 'footer';
+export type ActionVariant = 'primary' | 'secondary' | 'outline' | 'ghost' | 'link';
+
+export interface PageRow {
+    id: string;
+    appId: string;
+    slug: string;
+    title: string;
+    status: PageStatus;
+    createdAt: number;
+    updatedAt: number;
+}
+
+export interface PageSectionRow {
+    id: string;
+    pageId: string;
+    slot: BlockSlot;
+    variant: string;
+    title?: string;
+    subtitle?: string;
+    body?: string;
+    enabled: boolean;
+    sortOrder: number;
+}
+
+export interface PageFeatureRow {
+    id: string;
+    sectionId: string;
+    title: string;
+    description?: string;
+    icon?: string;
+    link?: string;
+    sortOrder: number;
+}
+
+export interface PageActionRow {
+    id: string;
+    sectionId: string;
+    label: string;
+    href: string;
+    variant: ActionVariant;
+    icon?: string;
+    external: boolean;
+    sortOrder: number;
+}
+```
+
+### Zod Schemas (Runtime Validation)
+
+```typescript
+export const pageSchema = z.object({
+    title: z.string().min(1).max(100),
+    slug: z.string().regex(/^[a-z0-9-]+$/),
+    status: z.enum(['draft', 'published', 'archived']),
+});
+
+export const pageSectionSchema = z.object({
+    slot: z.string(),
+    variant: z.string(),
+    title: z.string().max(200).nullable(),
+    enabled: z.boolean(),
+    sortOrder: z.number(),
+});
+
+export const pageActionSchema = z.object({
+    label: z.string().min(1).max(50),
+    href: z.string().url().or(z.string().startsWith('/')),
+    variant: z.enum(['primary', 'secondary', 'outline', 'ghost', 'link']),
+});
+```
+
+---
+
+## 6. Admin UI Architecture
+
+### Page 1: Pages List
+
+```
+┌─────────────────────────────────────┐
+│  [+ New Page]  [Search...]    ⋮⋮⋮   │
+├─────────────────────────────────────┤
+│ Title        | Status    | Updated  │
+│ Home         | Published | 2h ago   │
+│ Pricing      | Draft     | 1d ago   │
+│ About        | Published | 1w ago   │
+└─────────────────────────────────────┘
+```
+
+### Page 2: Page Builder (Main)
+
+```
+┌──────────────────────────────────────────────────────┐
+│ [← Pages]  Page Title  [Preview] [⚙️ Settings] [Save] │
+├────────────────────┬─────────────────────────────────┤
+│ Block Palette (30%)│ Canvas (70%)                     │
+├────────────────────┼─────────────────────────────────┤
+│ ⬜ Hero            │ ┌─────────────────────────────┐ │
+│ ⬜ Features        │ │ [Hero] ≡                    │ │
+│ ⬜ CTA             │ │ "Welcome to..."             │ │
+│ ⬜ Testimonials    │ └─────────────────────────────┘ │
+│ ⬜ Navbar          │ ┌─────────────────────────────┐ │
+│ ⬜ Footer          │ │ [Features] ≡                │ │
+│                    │ │ • Feature 1, 2, 3          │ │
+│                    │ └─────────────────────────────┘ │
+│                    │  [+ Add Block]                  │
+└────────────────────┴─────────────────────────────────┘
+```
+
+### Block Editor (Sheet Panel)
+
+```
+┌──────────────────────────────────────┐
+│ ✕ Edit Block                         │
+├──────────────────────────────────────┤
+│ Title                                │
+│ [Welcome to...........................] │
+│                                      │
+│ Subtitle                             │
+│ [Subheading text...................]  │
+│                                      │
+│ Variant         [Centered ▼]         │
+│                                      │
+│ Background Image [Upload]            │
+│                                      │
+│ Actions         [+ Add Button]       │
+│ • Get Started                        │
+│ • Learn More                         │
+│                                      │
+│              [Cancel] [Save]         │
+└──────────────────────────────────────┘
+```
+
+### Key Components
+
+- **BlockPalette**: Scrollable list of available blocks
+- **Canvas**: Drag-and-drop sortable grid
+- **BlockCard**: Individual block in canvas with inline preview
+- **BlockEditor**: Form sheet for editing block data
+- **FeatureManager**: Inline CRUD for features within a block
+- **ActionManager**: Inline CRUD for buttons/actions within a block
+
+---
+
+## 7. Next.js Frontend
+
+### Dynamic Route
+
+```typescript
+// app/[slug]/page.tsx
+export async function generateStaticParams() {
+    const pages = await fetch(`${API_URL}/api/pages/nav`).then(r => r.json());
+    return pages.map(p => ({ slug: p.slug }));
+}
+
+export default async function Page({ params }: { params: { slug: string } }) {
+    const preview = searchParams.preview === 'true';
+    const page = await fetch(`${API_URL}/api/pages/${params.slug}?preview=${preview}`).then(r => r.json());
+
+    return (
+        <>
+            {page.status === 'draft' && <DraftBanner />}
+            {page.sections.map(section => (
+                <SlotRenderer key={section.id} slot={section.slot} data={section} variant={section.variant} />
+            ))}
+        </>
+    );
+}
+```
+
+### SlotRenderer (Discriminated Union)
+
+```typescript
+export function SlotRenderer({ slot, data, variant }: SlotRendererProps) {
+    const componentMap: Record<BlockSlot, React.ComponentType<any>> = {
+        hero: variant === 'centered' ? HeroCentered : variant === 'split' ? HeroSplit : HeroMinimal,
+        features: variant === 'grid' ? FeaturesGrid : variant === 'list' ? FeaturesList : FeaturesCards,
+        cta: CTAButton,
+        testimonials: TestimonialCarousel,
+        navbar: Navbar,
+        footer: Footer,
+    };
+
+    const Component = componentMap[slot];
+    return Component ? <Component data={data} /> : <div>Unknown slot: {slot}</div>;
+}
+```
+
+---
+
+## 8. Block Registry System
+
+### Goal
+
+Apps register custom blocks at runtime without code deployment or DB migrations.
+
+### API (Simplified)
+
+```typescript
+// In Next.js app startup
+import { BlockRegistry } from '@ottabase/block-registry';
+
+const registry = BlockRegistry.getInstance();
+
+registry.register({
+    id: 'hero',
+    label: 'Hero Section',
+    category: 'layout',
+    fields: {
+        title: { type: 'text', required: true },
+        subtitle: { type: 'text' },
+        backgroundImage: { type: 'image' },
+        actions: { type: 'list' },
+    },
+    variants: [
+        { id: 'centered', label: 'Centered' },
+        { id: 'split', label: 'Split' },
+    ],
+});
+```
+
+### Discovery Endpoint
+
+```
+GET /api/blocks → Admin UI discovers all available blocks
+```
+
+---
+
+## 9. UX Flows
+
+### Create Page
+
+1. Click **[+ New Page]**
+2. Enter title and slug
+3. Redirected to **Page Builder**
+4. Empty canvas with block palette
+
+### Add & Edit Blocks
+
+1. Drag block from palette to canvas
+2. Double-click block title to edit inline
+3. Click block to open **Block Editor** sheet
+4. Edit fields, features, actions
+5. Auto-saves with debounce
+
+### Reorder Blocks
+
+1. Drag block by grab handle
+2. Visual feedback with opacity change
+3. On drop, `sortOrder` values updated
+
+### Publish
+
+1. Click **[Settings]** → **Publish**
+2. Confirm slug & SEO fields
+3. Page now live at `/{slug}`
+
+---
+
+## 9. UI/UX Requirements
+
+### 9.1 Accessibility (A11y)
+
+**Keyboard Navigation**: | Key | Action | |-----|--------| | `Escape` | Close block editor / deselect block | | `Delete`
+| Delete selected block (confirm) | | `Ctrl+S` | Save all changes | | `Ctrl+Z` / `Ctrl+Shift+Z` | Undo / Redo | |
+`↑ / ↓` | Navigate between blocks | | `Enter` | Open editor for selected block | | `Tab` | Focus next field |
+
+**ARIA Requirements**:
+
+```tsx
+// Blocks must be focusable with semantic roles
+<div
+    role="listitem"
+    tabIndex={0}
+    aria-selected={isSelected}
+    aria-label={`${block.slot} block: ${block.title || 'Untitled'}`}
+/>
+
+// Drag handle with aria-label
+<button aria-label="Drag to reorder" aria-roledescription="sortable">
+    <GripVertical />
+</button>
+
+// Live regions for announcements
+<div aria-live="polite" aria-atomic="true" className="sr-only">
+    Moved block to position {index + 1}
+</div>
+```
+
+---
+
+### 9.2 Validation Rules
+
+```typescript
+// Page-level validation
+- title: required, 1-100 chars
+- slug: required, lowercase+numbers+hyphens, must be unique per app
+- status: 'draft' | 'published' | 'archived'
+
+// Block-level validation
+- Block title: optional, max 200 chars
+- Block subtitle: optional, max 500 chars
+- Block body: optional, max 10,000 chars
+
+// Features validation (within blocks)
+- title: required, 1-100 chars
+- description: optional, max 500 chars
+- icon: optional (text name or Lucide icon ID)
+- link: optional (valid URL or internal route)
+
+// Actions validation (buttons within blocks)
+- label: required, 1-50 chars
+- href: required, valid URL or starts with /
+- variant: 'primary' | 'secondary' | 'outline' | 'ghost' | 'link'
+- icon: optional (Lucide icon name)
+- external: toggle (open in new tab)
+```
+
+**Error Messages**:
+
+```tsx
+// Field-level inline errors
+<input value={title} />;
+{
+    errors.title && <span className="text-red-500 text-sm">{errors.title}</span>;
+}
+
+// Slug availability check (real-time)
+<input value={slug} onBlur={() => checkSlugAvailable(slug)} />;
+{
+    slugError && <span className="text-red-500">{slugError}</span>;
+}
+```
+
+---
+
+### 9.3 Error Handling
+
+| Error            | HTTP | Message                               | Action           |
+| ---------------- | ---- | ------------------------------------- | ---------------- |
+| Page not found   | 404  | "Page not found"                      | Show 404 page    |
+| Slug exists      | 409  | "A page with this URL already exists" | Focus slug field |
+| Validation error | 400  | Field-specific message                | Highlight field  |
+| DB error         | 500  | "Something went wrong. Try again."    | Retry button     |
+| Rate limited     | 429  | "Too many requests. Wait a moment."   | Auto-retry       |
+| Unauthorized     | 403  | "You don't have permission"           | Refresh auth     |
+
+**UI Pattern**:
+
+```tsx
+// Toast notifications for all errors
+if (error) {
+    toast.error(error.message, { duration: 5000 });
+}
+
+// Inline validation errors on field blur
+<input
+    onBlur={() => {
+        const result = schema.safeParse(formData);
+        if (!result.success) {
+            setErrors(result.error.flatten().fieldErrors);
+        }
+    }}
+/>;
+```
+
+---
+
+### 9.4 Loading & Empty States
+
+**Skeleton Loading**:
+
+```tsx
+// Pages list loading
+<div className="space-y-3">
+    {[1, 2, 3].map(i => (
+        <div key={i} className="h-16 bg-gray-200 rounded animate-pulse" />
+    ))}
+</div>
+
+// Block editor loading
+<Sheet open={isLoading}>
+    <div className="space-y-4 p-4">
+        <div className="h-10 bg-gray-200 rounded animate-pulse" />
+        <div className="h-20 bg-gray-200 rounded animate-pulse" />
+    </div>
+</Sheet>
+```
+
+**Empty States**:
+
+```tsx
+// Empty pages list
+<div className="text-center py-12">
+    <FileText size={48} className="mx-auto opacity-30 mb-4" />
+    <p className="text-gray-600 mb-4">No pages yet. Start by creating one.</p>
+    <button onClick={createPage}>+ New Page</button>
+</div>
+
+// Empty canvas
+<div className="flex flex-col items-center justify-center h-96 bg-gray-50 rounded border-2 border-dashed">
+    <p className="text-gray-600 mb-4">No blocks yet. Add one from the palette →</p>
+    <button onClick={() => selectBlock('hero')}>Add Hero Section</button>
+</div>
+```
+
+---
+
+### 9.5 Visual Feedback & Interactions
+
+**Drag & Drop Feedback**:
+
+```tsx
+// Active state during drag
+{
+    isActive && <div className="opacity-50 bg-blue-100 rounded" />;
+}
+
+// Hover feedback
+<button className="hover:bg-gray-100 active:scale-95 transition" />;
+
+// Drop zone indication
+{
+    isOver && <div className="bg-blue-50 border-2 border-blue-400" />;
+}
+
+// Animated feedback
+<MotionDiv initial={{ opacity: 0, y: -10 }} animate={{ opacity: 1, y: 0 }} transition={{ duration: 0.2 }}>
+    Block added
+</MotionDiv>;
+```
+
+**Confirmation Dialogs**:
+
+```tsx
+// Delete confirmation
+<AlertDialog>
+    <AlertDialogTitle>Delete block?</AlertDialogTitle>
+    <AlertDialogDescription>
+        This action cannot be undone. The block and all its features/actions will be deleted permanently.
+    </AlertDialogDescription>
+    <AlertDialogAction onClick={handleDelete}>Delete</AlertDialogAction>
+    <AlertDialogCancel>Cancel</AlertDialogCancel>
+</AlertDialog>
+
+// Publish confirmation
+<Dialog>
+    <DialogTitle>Publish page?</DialogTitle>
+    <p>This will make the page live at <code>/{slug}</code></p>
+    <button onClick={publishPage}>Publish</button>
+</Dialog>
+```
+
+---
+
+### 9.6 Responsive Design
+
+**Viewport Preview** (in builder):
+
+```
+┌─────────────────────────────┐
+│ [📱 Mobile]  [Tablet]  [🖥️ Desktop] │
+├─────────────────────────────┤
+│  ┌─────────┐                │
+│  │ 375px   │  (Phone)      │
+│  │ Preview │                │
+│  └─────────┘                │
+└─────────────────────────────┘
+```
+
+**Responsive Canvas Preview**:
+
+- **Mobile**: 375px × auto (full height)
+- **Tablet**: 768px × auto
+- **Desktop**: 1200px × auto
+
+**Block Palette Behavior**:
+
+- Desktop: Fixed left sidebar (250px) + canvas (70%)
+- Tablet: Collapsible sidebar + canvas
+- Mobile: Drawer mode (swipe from left)
+
+---
+
+### 9.7 Toast & Notification Patterns
+
+```tsx
+// Success
+toast.success('Page published!', { icon: '✓' });
+
+// Error
+toast.error('Failed to save block', { duration: 5000 });
+
+// Loading
+toast.loading('Publishing page...', { id: 'publish' });
+// Later: toast.update('publish', { type: 'success', description: 'Published!' });
+
+// Info
+toast.info('Pages are cached for 60 seconds', { duration: 3000 });
+```
+
+---
+
+### 9.8 Form States
+
+```tsx
+// Disabled state during submission
+<button disabled={isSaving} className="opacity-50 cursor-not-allowed">
+    {isSaving ? 'Saving...' : 'Save'}
+</button>
+
+// Required field indicator
+<label>
+    Title
+    <span className="text-red-500 ml-1" aria-label="required">*</span>
+    <input required aria-required="true" />
+</label>
+
+// Focused field highlight
+<input
+    className="focus:ring-2 focus:ring-blue-500 focus:border-transparent"
+/>
+```
+
+---
+
+## 10. Implementation Roadmap
+
+### Phase 1: Database & Models (2-3 hours)
+
+- [ ] Create 4 tables in `apps/*/ottabase/db/schema.ts`
+- [ ] Create model classes with relationships
+- [ ] Register in `worker/lib/db-utils.ts`
+- [ ] Run migration: `curl -X POST http://localhost:3004/api/ottaorm/init`
+
+### Phase 2: Contract Package (1 hour)
+
+- [ ] Create `@ottabase/marketing-pages-contract`
+- [ ] Export TypeScript types + Zod schemas
+
+### Phase 3: Worker API (Basic CRUD) (2 hours)
+
+- [ ] Models auto-generate CRUD via OttaORM
+- [ ] Add public endpoint `/api/pages/:slug`
+- [ ] Add preview mode support
+
+### Phase 4: Admin UI - Pages List (2 hours)
+
+- [ ] Create pages list with create/delete/duplicate
+- [ ] Add search and filtering
+
+### Phase 5: Admin UI - Builder (6-8 hours)
+
+- [ ] Block palette component
+- [ ] Canvas with @dnd-kit
+- [ ] Block card component
+- [ ] Block editor sheet
+- [ ] Features & actions managers
+- [ ] Page settings dialog
+
+### Phase 6: Next.js Frontend (2-3 hours)
+
+- [ ] Dynamic route `app/[slug]/page.tsx`
+- [ ] SlotRenderer with variant dispatch
+- [ ] Render all block variants
+- [ ] Preview banner for drafts
+
+### Phase 7: Polish (2 hours)
+
+- [ ] Loading states, empty states, error handling
+- [ ] Tests for models, API, components
+
+**Total: ~18-20 hours for MVP**
+
+---
+
+## 10.6 Quick UX Wins (Priority)
+
+| Feature                 | Effort  | Impact | Do First? |
+| ----------------------- | ------- | ------ | --------- |
+| Block icons             | 30 min  | High   | ✅ **P0** |
+| Duplicate page          | 15 min  | High   | ✅ **P0** |
+| Empty state UI          | 30 min  | High   | **P1**    |
+| Field validation errors | 30 min  | High   | **P1**    |
+| Publish preview         | 30 min  | Medium | **P1**    |
+| Inline title edit       | 1 hour  | Medium | **P2**    |
+| Undo/Redo               | 2 hours | High   | **P2**    |
+| Keyboard shortcuts      | 1 hour  | Medium | **P3**    |
+
+**Recommendation**: Ship 45 min of P0 features immediately, then P1 features in iteration 2.
+
+---
+
+## 11. Security & Authentication
+
+**Admin Routes Require Auth**:
+
+```typescript
+// All mutation endpoints protected
+router.use('/api/ottaorm/*', authMiddleware);
+router.post('/api/pages/seed', authMiddleware);
+
+// Public routes (no auth)
+router.get('/api/pages/:slug', ...);  // Public data
+router.get('/api/pages/nav', ...);    // Nav data
+```
+
+**Input Sanitization**:
+
+```typescript
+// Sanitize rich text fields (body, subtitle)
+import DOMPurify from 'dompurify';
+
+function sanitizeHtml(input: string) {
+    return DOMPurify.sanitize(input, {
+        ALLOWED_TAGS: ['b', 'i', 'em', 'strong', 'a', 'p', 'br'],
+        ALLOWED_ATTR: ['href', 'target', 'rel'],
+    });
+}
+```
+
+**Preview Mode Security**:
+
+```typescript
+// Development: Simple flag bypass
+GET /api/pages/my-page?preview=true
+
+// Production: Use signed token
+const token = signJWT({ pageId, exp: Date.now() + 3600000 }, SECRET);
+GET /api/pages/:slug?preview=true&token={token}
+```
+
+**RBAC (Role-Based Access)**:
+
+```typescript
+const PAGE_PERMISSIONS = {
+    'pages.create': ['admin', 'marketing'],
+    'pages.update': ['admin', 'marketing', 'editor'],
+    'pages.delete': ['admin'],
+    'pages.publish': ['admin', 'marketing'],
+};
+
+if (!hasPermission(user, 'pages.publish')) {
+    return errorResponse('Insufficient permissions', 403);
+}
+```
+
+---
+
+## 12. Cache Invalidation Strategy
+
+**Invalidation Triggers**:
+
+| Event            | Invalidate                      | Method                      |
+| ---------------- | ------------------------------- | --------------------------- |
+| Create page      | `['pages']` list                | `invalidateQueries`         |
+| Update page      | `['pages', pageId]` + list      | `setQueryData`              |
+| Delete page      | `['pages', pageId]` + list      | `invalidateQueries`         |
+| Create section   | `['page_sections', { pageId }]` | `setQueryData`              |
+| Reorder sections | `['page_sections', { pageId }]` | `setQueryData` (optimistic) |
+| Publish page     | Public page cache               | `revalidatePath` (Next.js)  |
+
+**Optimistic Updates** (instant UI feedback without spinners):
+
+```typescript
+const updateSection = useMutation({
+    mutationFn: (data) => api.updateSection(data),
+    onMutate: async (newData) => {
+        // Cancel outgoing fetches
+        await queryClient.cancelQueries(['page_sections', { pageId }]);
+
+        // Save previous state
+        const previous = queryClient.getQueryData(['page_sections', { pageId }]);
+
+        // Update UI immediately
+        queryClient.setQueryData(['page_sections', { pageId }], (old) =>
+            old.map((s) => (s.id === newData.id ? newData : s)),
+        );
+
+        return { previous };
+    },
+    onError: (err, newData, context) => {
+        // Rollback on error
+        queryClient.setQueryData(['page_sections', { pageId }], context.previous);
+        toast.error('Failed to save');
+    },
+});
+```
+
+---
+
+## 13. Testing Strategy
+
+**Unit Tests** (Models):
+
+```typescript
+describe('Page Model', () => {
+    it('validates slug format', async () => {
+        await expect(Page.create({ title: 'Test', slug: 'Invalid Slug!' })).rejects.toThrow(/lowercase/);
+    });
+
+    it('cascades delete to sections', async () => {
+        const page = await Page.create({ title: 'Test' });
+        await PageSection.create({ pageId: page.id, slot: 'hero' });
+        await page.delete();
+
+        const sections = await PageSection.where({ pageId: page.id });
+        expect(sections).toHaveLength(0);
+    });
+});
+```
+
+**Integration Tests** (API):
+
+```typescript
+describe('Pages API', () => {
+    it('returns 404 for draft page (non-preview)', async () => {
+        await Page.create({ title: 'Draft', slug: 'draft', status: 'draft' });
+        const res = await fetch('/api/pages/draft');
+        expect(res.status).toBe(404);
+    });
+
+    it('returns 200 for published page', async () => {
+        await Page.create({ title: 'Live', slug: 'live', status: 'published' });
+        const res = await fetch('/api/pages/live');
+        expect(res.status).toBe(200);
+    });
+});
+```
+
+**E2E Tests** (Playwright):
+
+```typescript
+test('create and publish page flow', async ({ page }) => {
+    await page.goto('/admin/pages');
+    await page.click('[data-test=new-page-btn]');
+
+    await page.fill('[data-test=page-title]', 'My Page');
+    await page.fill('[data-test=page-slug]', 'my-page');
+    await page.click('[data-test=save-btn]');
+
+    // Add block
+    await page.click('[data-test=add-hero-btn]');
+    await page.click('[data-test=settings-btn]');
+
+    // Publish
+    await page.click('[data-test=publish-btn]');
+    await page.click('[data-test=confirm-publish]');
+
+    // Verify live
+    const response = await page.goto('/my-page');
+    expect(response?.status()).toBe(200);
+});
+```
+
+---
+
+## 14. Debugging Checklist
+
+| Issue                         | Debug                                     | Solution                                       |
+| ----------------------------- | ----------------------------------------- | ---------------------------------------------- |
+| "Page not found" after create | Check status                              | Page is `draft`; preview or publish it         |
+| Blocks not saving             | Browser console, network tab              | Look for mutation errors; add error logging    |
+| Variant not rendering         | Browser console                           | Verify variant in `VARIANT_COMPONENTS` map     |
+| Features/actions missing      | `curl /api/pages/slug\|jq '.sections[0]'` | Check sectionId matches DB                     |
+| DnD not working               | React DevTools                            | Verify `<DndContext>` wraps sortable area      |
+| Build fails                   | `pnpm lint && pnpm type-check`            | Fix TypeScript errors first                    |
+| Slow builder                  | React Profiler                            | Check for re-render thrashing; use memoization |
+
+---
+
+## 15. Key Technical Decisions
+
+| Decision                         | Rationale                                            |
+| -------------------------------- | ---------------------------------------------------- |
+| **4 normalized tables**          | Clean separation, cascade deletes, efficient queries |
+| **Slot + Variant pattern**       | Write data once, render via any visual variant       |
+| **Shared contract package**      | Single source of truth, type safety end-to-end       |
+| **@dnd-kit for DnD**             | Modern, accessible, React 18+ compatible             |
+| **Preview mode via query param** | Simple, stateless                                    |
+| **OttaORM for CRUD**             | Consistent with codebase, auto-hooks                 |
+| **Dynamic block registry**       | Extensible without code deployment                   |
+
+---
+
+## 16. File Paths
+
+```
+Admin UI (TanStack):
+├── src/pages/admin/pages/
+│   ├── AdminPagesListPage.tsx
+│   ├── AdminPageBuilderPage.tsx
+│   └── components/
+│       ├── BlockPalette.tsx
+│       ├── BlockCanvas.tsx
+│       ├── BlockCard.tsx
+│       ├── BlockEditor.tsx
+│       ├── FeatureManager.tsx
+│       └── ActionManager.tsx
+├── hooks/pageHooks.ts (CRUD hooks)
+
+Next.js App:
+├── app/[slug]/page.tsx
+├── app/[slug]/marketing-page-content.tsx
+├── components/SlotRenderer.tsx
+├── components/variants/
+│   ├── hero/ (HeroCentered, HeroSplit, etc.)
+│   ├── features/ (FeaturesGrid, etc.)
+│   └── ... (other block variants)
+├── lib/api.ts
+
+Models & DB (OttaBase):
+├── ottabase/db/schema.ts
+├── ottabase/models/
+│   ├── Page.ts
+│   ├── PageSection.ts
+│   ├── PageFeature.ts
+│   └── PageAction.ts
+
+Package:
+└── @ottabase/marketing-pages-contract/
+    └── src/
+        ├── types.ts
+        ├── schemas.ts
+        └── index.ts
+```
+
+---
+
+## 17. Error Handling
+
+| Error               | Status | Response                           |
+| ------------------- | ------ | ---------------------------------- |
+| Page not found      | 404    | `{ error: "Page not found" }`      |
+| Slug already exists | 409    | `{ error: "Slug in use" }`         |
+| Invalid slot type   | 400    | `{ error: "Invalid slot: xyz" }`   |
+| Validation failed   | 422    | `{ error: "...", details: {...} }` |
+| Unauthorized        | 403    | `{ error: "Access denied" }`       |
+
+**Use `errorResponse()` from `@ottabase/utils/http-errors`**
+
+---
+
+## 18. Performance Targets
+
+| Metric                  | Target  |
+| ----------------------- | ------- |
+| Page render (cached)    | < 100ms |
+| Page render (cold)      | < 300ms |
+| Builder drag operations | < 50ms  |
+| Create page → publish   | < 5 min |
+| Admin load page data    | < 50ms  |
+
+**Caching**: ISR 60s for public pages, TanStack Query 30-60s for admin
+
+---
+
+## 19. Quick Reference: Block Types (MVP)
+
+```
+Layout:  Hero, Features, CTA, Testimonials, Gallery
+Nav:     Navbar, Footer
+Custom:  Form, Video, Code, Text, Image, Spacer
+```
+
+Each block has **2-3 variants** (e.g., Hero: centered/split/minimal).
+
+---
+
+## 20. RLS (Row-Level Security)
+
+All pages scoped to `appId` via OttaORM. No manual permission checks needed.
+
+```typescript
+// @ottabase/ottaorm automatically enforces
+Export allowCrossAppAccess(false); // Default
+```
+
+---
+
+## 21. Testing Checklist
+
+- [ ] Models: CRUD, relationships, validation
+- [ ] API: Status codes, error messages, authorization
+- [ ] Admin UI: Add, edit, delete, reorder blocks
+- [ ] Frontend: All block variants render correctly
+- [ ] E2E: Create page → publish → access public URL
+
+---
+
+## 22. Deployment Notes
+
+- **D1 migrations**: Auto-run on `/api/ottaorm/init` (idempotent)
+- **ISR invalidation**: Trigger on page publish via `revalidatePath()`
+- **No env vars needed**: Uses Cloudflare bindings directly
+- **Multi-tenant**: RLS handles isolation automatically
+
+---
+
+## References
+
+- [Full Specification](MARKETING_PAGES_FEATURE_SPEC.md) (4000+ lines, all details)
+- OttaORM: `@ottabase/ottaorm`
+- UI Components: `@ottabase/ui-shadcn`
+- DnD Kit: `@dnd-kit/core`