@nextsparkjs/core 0.1.0-beta.7 → 0.1.0-beta.71

package/dist/presets/theme/tests/cypress.config.ts

@@ -9,6 +9,8 @@ import { defineConfig } from 'cypress'
 import path from 'path'
 import fs from 'fs'
 
+// __dirname works natively with CommonJS module resolution (tsconfig.cypress.json)
+
 // Paths relative to this config file
 const themeRoot = path.resolve(__dirname, '..')
 const projectRoot = path.resolve(__dirname, '../../../..')
@@ -21,6 +23,17 @@ dotenv.config({ path: path.join(projectRoot, '.env') })
 // Server port (from .env or default 5173)
 const port = process.env.PORT || 5173
 
+// Extract CYPRESS_ prefixed variables from process.env
+// Cypress auto-strips the CYPRESS_ prefix when accessing via Cypress.env()
+const cypressEnvVars: Record<string, string> = {}
+Object.entries(process.env).forEach(([key, value]) => {
+  if (key.startsWith('CYPRESS_') && value) {
+    // Remove CYPRESS_ prefix for Cypress.env() access
+    const cypressKey = key.replace('CYPRESS_', '')
+    cypressEnvVars[cypressKey] = value
+  }
+})
+
 export default defineConfig({
   e2e: {
     // Base URL for the application
@@ -73,14 +86,13 @@ export default defineConfig({
 
     // Environment variables
     env: {
+      // Spread CYPRESS_ prefixed vars from .env (e.g., CYPRESS_DEVELOPER_EMAIL -> DEVELOPER_EMAIL)
+      ...cypressEnvVars,
+
       // Theme info
       ACTIVE_THEME: '{{THEME_SLUG}}',
       THEME_PATH: themeRoot,
 
-      // Test user credentials (update with your test users)
-      TEST_USER_EMAIL: 'user@example.com',
-      TEST_USER_PASSWORD: 'Testing1234',
-
       // Feature flags
       ENABLE_ALLURE: true,
 
@@ -104,7 +116,9 @@ export default defineConfig({
       })
 
       // @cypress/grep plugin for test filtering by tags
-      require('@cypress/grep/src/plugin')(config)
+      // v5.x uses named export { plugin } from '@cypress/grep/plugin'
+      const { plugin: grepPlugin } = require('@cypress/grep/plugin')
+      grepPlugin(config)
 
       // Documentation video tasks
       on('task', {

package/dist/providers/TranslationContextManager.js

@@ -1,5 +1,5 @@
 "use client";
-import { useContextAwareTranslations } from "../hooks/useContextAwareTranslations";
+import { useContextAwareTranslations } from "../hooks/useContextAwareTranslations.js";
 import { useEffect } from "react";
 function TranslationContextManager() {
   const { currentContext, loadedNamespaces } = useContextAwareTranslations();

package/dist/providers/index.js

@@ -1,4 +1,4 @@
-export * from "./PluginProvider";
-export * from "./TranslationContextManager";
-export * from "./query-provider";
-export * from "./theme-provider";
+export * from "./PluginProvider.js";
+export * from "./TranslationContextManager.js";
+export * from "./query-provider.js";
+export * from "./theme-provider.js";

package/dist/templates/ai-workflow/claude/config/context.json

@@ -0,0 +1,54 @@
+{
+  "context": "consumer",
+  "description": "NextSpark application development - Build your app using themes and plugins",
+
+  "capabilities": {
+    "modifyCore": false,
+    "allThemes": false,
+    "allPlugins": true,
+    "createReleases": false,
+    "maintainWorkflows": false
+  },
+
+  "allowedPaths": [
+    "contents/themes/${NEXT_PUBLIC_ACTIVE_THEME}/**/*",
+    "contents/plugins/**/*",
+    ".claude/sessions/**/*"
+  ],
+
+  "restrictions": {
+    "core": {
+      "level": "forbidden",
+      "message": "Core is installed via npm (node_modules/) and cannot be modified. To customize behavior, create a theme override or plugin instead."
+    },
+    "otherThemes": {
+      "level": "forbidden",
+      "message": "Only the active theme (NEXT_PUBLIC_ACTIVE_THEME) can be modified. To work on a different theme, update your .env file."
+    },
+    "app": {
+      "level": "discouraged",
+      "requiresExplicitConfirmation": true,
+      "message": "Modifying /app directly is discouraged as it reduces portability. Use theme page overrides when possible. Only proceed if user explicitly requests and understands the trade-offs."
+    }
+  },
+
+  "disabledCommands": [
+    "release:version",
+    "npm-publish",
+    "npm-version",
+    "npm-repackage",
+    "npm-test-local",
+    "npm-test-npm",
+    "workflow-update"
+  ],
+
+  "disabledAgents": [
+    "release-manager"
+  ],
+
+  "notes": {
+    "gettingStarted": "Your active theme is defined in .env (NEXT_PUBLIC_ACTIVE_THEME). All customizations should go there.",
+    "creatingPlugins": "Use /create:plugin to scaffold a new plugin in contents/plugins/.",
+    "needCoreChanges": "If you need functionality not available in core, create a plugin or request the feature in NextSpark repository."
+  }
+}

package/dist/templates/app/(auth)/forgot-password/page.tsx

@@ -6,7 +6,7 @@ import { zodResolver } from '@hookform/resolvers/zod';
 import { AlertCircle, ArrowLeft, CheckCircle, Loader2, Mail } from 'lucide-react';
 import Link from 'next/link';
 import { useState, useCallback } from 'react';
-import { sel } from '@nextsparkjs/core/lib/test';
+import { sel } from '@nextsparkjs/core/selectors';
 import { useTranslations } from 'next-intl';
 import { useForm } from 'react-hook-form';
 import { Button } from '@nextsparkjs/core/components/ui/button';

package/dist/templates/app/(auth)/reset-password/page.tsx

@@ -19,7 +19,7 @@ import { PasswordInput } from "@nextsparkjs/core/components/ui/password-input";
 import { Alert, AlertDescription } from "@nextsparkjs/core/components/ui/alert";
 import { Card, CardContent, CardDescription, CardHeader, CardTitle } from "@nextsparkjs/core/components/ui/card";
 import { getTemplateOrDefaultClient } from '@nextsparkjs/registries/template-registry.client'
-import { createCyId } from '@nextsparkjs/core/lib/test'
+import { sel } from '@nextsparkjs/core/selectors'
 
 function ResetPasswordContent() {
   const searchParams = useSearchParams();
@@ -84,7 +84,7 @@ function ResetPasswordContent() {
 
   if (success) {
     return (
-      <Card className="w-full max-w-md" data-cy={createCyId('reset-password', 'success')}>
+      <Card className="w-full max-w-md" data-cy={sel('auth.resetPassword.success')}>
         <CardContent className="pt-6">
           <div className="text-center space-y-4">
             <div className="w-16 h-16 bg-green-100 rounded-full flex items-center justify-center mx-auto">
@@ -96,7 +96,7 @@ function ResetPasswordContent() {
                 Your password has been successfully reset. You can now sign in with your new password.
               </p>
             </div>
-            <Button asChild className="w-full" data-cy={createCyId('reset-password', 'login-link')}>
+            <Button asChild className="w-full" data-cy={sel('auth.resetPassword.loginLink')}>
               <Link href="/login">
                 Sign In Now
               </Link>
@@ -108,7 +108,7 @@ function ResetPasswordContent() {
   }
 
   return (
-    <Card className="w-full max-w-md" data-cy={createCyId('reset-password', 'form')}>
+    <Card className="w-full max-w-md" data-cy={sel('auth.resetPassword.form')}>
       <CardHeader className="space-y-1">
         <CardTitle className="text-2xl font-bold">Set New Password</CardTitle>
         <CardDescription>
@@ -117,7 +117,7 @@ function ResetPasswordContent() {
       </CardHeader>
       <CardContent>
         {error && (
-          <Alert variant="destructive" className="mb-4" data-cy={createCyId('reset-password', 'error')}>
+          <Alert variant="destructive" className="mb-4" data-cy={sel('auth.resetPassword.error')}>
             <AlertCircle className="h-4 w-4" />
             <AlertDescription>
               {error}
@@ -142,7 +142,7 @@ function ResetPasswordContent() {
               placeholder="Create a strong password"
               showRequirements={true}
               password={password || ""}
-              data-cy={createCyId('reset-password', 'password-input')}
+              data-cy={sel('auth.resetPassword.password')}
             />
             {errors.password && (
               <p className="text-sm text-destructive">{errors.password.message}</p>
@@ -156,7 +156,7 @@ function ResetPasswordContent() {
               id="confirmPassword"
               autoComplete="new-password"
               placeholder="Confirm your new password"
-              data-cy={createCyId('reset-password', 'confirm-input')}
+              data-cy={sel('auth.resetPassword.confirmPassword')}
             />
             {errors.confirmPassword && (
               <p className="text-sm text-destructive">{errors.confirmPassword.message}</p>
@@ -167,7 +167,7 @@ function ResetPasswordContent() {
             type="submit"
             disabled={loading || !token}
             className="w-full"
-            data-cy={createCyId('reset-password', 'submit')}
+            data-cy={sel('auth.resetPassword.submitButton')}
           >
             {loading ? (
               <>
@@ -184,7 +184,7 @@ function ResetPasswordContent() {
           <Link
             href="/login"
             className="text-sm text-primary hover:underline"
-            data-cy={createCyId('reset-password', 'back')}
+            data-cy={sel('auth.resetPassword.backToLogin')}
           >
             Back to Login
           </Link>

package/dist/templates/app/(auth)/verify-email/page.tsx

@@ -6,7 +6,7 @@ import { Suspense, useEffect, useState } from "react";
 import { Button } from '@nextsparkjs/core/components/ui/button';
 import { Alert, AlertDescription } from '@nextsparkjs/core/components/ui/alert';
 import { getTemplateOrDefaultClient } from '@nextsparkjs/registries/template-registry.client'
-import { createCyId } from '@nextsparkjs/core/lib/test'
+import { sel } from '@nextsparkjs/core/selectors'
 
 function VerifyEmailContent() {
   const searchParams = useSearchParams();
@@ -116,7 +116,7 @@ function VerifyEmailContent() {
 
   if (status === 'loading') {
     return (
-      <div className="space-y-4" data-cy={createCyId('verify-email', 'loading')}>
+      <div className="space-y-4" data-cy={sel('auth.verifyEmail.container')}>
         <div className="text-center">
           <h2 className="text-xl font-semibold">Verifying Email</h2>
           <p className="text-sm text-muted-foreground mt-2">Please wait while we verify your email address</p>
@@ -130,7 +130,7 @@ function VerifyEmailContent() {
 
   if (status === 'success') {
     return (
-      <div className="space-y-4" data-cy={createCyId('verify-email', 'success')}>
+      <div className="space-y-4" data-cy={sel('auth.verifyEmail.successMessage')}>
         <div className="text-center">
           <div className="flex justify-center mb-2">
             <CheckCircle className="h-12 w-12 text-primary" />
@@ -148,7 +148,7 @@ function VerifyEmailContent() {
   }
 
   return (
-    <div className="space-y-4" data-cy={createCyId('verify-email', 'error')}>
+    <div className="space-y-4">
       <div className="text-center">
         <div className="flex justify-center mb-2">
           <AlertCircle className="h-12 w-12 text-destructive" />
@@ -157,15 +157,15 @@ function VerifyEmailContent() {
         <p className="text-sm text-muted-foreground mt-2">We couldn&apos;t verify your email address</p>
       </div>
       {error && (
-        <Alert variant="destructive" data-cy={createCyId('verify-email', 'error-message')}>
+        <Alert variant="destructive" data-cy={sel('auth.verifyEmail.error')}>
           <AlertDescription>{error}</AlertDescription>
         </Alert>
       )}
       <div className="flex gap-2">
-        <Button onClick={() => router.push('/signup')} variant="outline" className="flex-1" data-cy={createCyId('verify-email', 'back-signup')}>
+        <Button onClick={() => router.push('/signup')} variant="outline" className="flex-1">
           Back to Sign Up
         </Button>
-        <Button onClick={() => router.push('/login')} className="flex-1" data-cy={createCyId('verify-email', 'go-login')}>
+        <Button onClick={() => router.push('/login')} className="flex-1">
           Go to Login
         </Button>
       </div>

package/dist/templates/app/(public)/[...slug]/page.tsx

@@ -20,12 +20,23 @@ import {
   matchPathToEntity,
   getEntityBasePath,
 } from '@nextsparkjs/core/lib/entities/schema-generator'
-import { getEntityRegistry } from '@nextsparkjs/core/lib/entities/queries'
+import { getEntityRegistry, setEntityRegistry } from '@nextsparkjs/core/lib/entities/queries'
 import { TemplateService } from '@nextsparkjs/core/lib/services/template.service'
 import { resolvePublicEntityFromUrl } from '@nextsparkjs/core/lib/api/entity/public-resolver'
 import { PublicEntityGrid } from '@nextsparkjs/core/components/public/entities/PublicEntityGrid'
 import type { EntityConfig } from '@nextsparkjs/core/lib/entities/types'
 import type { Metadata } from 'next'
+// Pattern resolution imports
+import { PatternsResolverService } from '@nextsparkjs/core/lib/blocks/patterns-resolver.service'
+import { extractPatternIds, resolvePatternReferences } from '@nextsparkjs/core/lib/blocks/pattern-resolver'
+import type { BlockInstance } from '@nextsparkjs/core/types/blocks'
+import type { PatternReference } from '@nextsparkjs/core/types/pattern-reference'
+// Import registry directly - webpack resolves @nextsparkjs/registries alias at compile time
+import { ENTITY_REGISTRY, ENTITY_METADATA } from '@nextsparkjs/registries/entity-registry'
+
+// Initialize registry at module load time (before any component renders)
+// This ensures the registry is available even if this page loads before the layout
+setEntityRegistry(ENTITY_REGISTRY, ENTITY_METADATA)
 
 /**
  * Convert entity registry to format expected by matchPathToEntity
@@ -34,7 +45,8 @@ function getEntityConfigs(): Record<string, EntityConfig> {
   const registry = getEntityRegistry()
   const configs: Record<string, EntityConfig> = {}
   for (const [key, entry] of Object.entries(registry)) {
-    configs[key] = entry.config as EntityConfig
+    // eslint-disable-next-line @typescript-eslint/no-explicit-any
+    configs[key] = (entry as any).config as EntityConfig
   }
   return configs
 }
@@ -47,6 +59,23 @@ interface PageProps {
   searchParams: Promise<{ [key: string]: string | string[] | undefined }>
 }
 
+/**
+ * Base fields that all builder-enabled entities have (from migrations)
+ * These are the minimum fields needed for public page rendering
+ */
+const BASE_PUBLIC_FIELDS = ['id', 'slug', 'title', 'status', 'blocks', 'locale', 'createdAt', 'userId']
+
+/**
+ * Optional SEO fields that may exist on builder entities
+ */
+const SEO_FIELDS = ['seoTitle', 'seoDescription', 'ogImage']
+
+/**
+ * Common optional fields for content entities (posts, articles, etc.)
+ * These are checked dynamically - only included if they exist in entity.fields
+ */
+const OPTIONAL_CONTENT_FIELDS = ['excerpt', 'featuredImage']
+
 interface PublishedItem {
   id: string
   slug: string
@@ -64,6 +93,72 @@ interface PublishedItem {
   ogImage?: string
   locale?: string
   createdAt?: string
+  userId?: string
+}
+
+/**
+ * Quote a field name for PostgreSQL (handles camelCase)
+ */
+function quoteField(field: string): string {
+  return /[A-Z]/.test(field) ? `"${field}"` : field
+}
+
+/**
+ * Build SELECT clause dynamically based on entity configuration
+ * Only includes fields that actually exist in the entity's schema
+ */
+function buildPublicSelectClause(entity: EntityConfig): string {
+  const fields = new Set<string>(BASE_PUBLIC_FIELDS)
+
+  // Add SEO fields (these are standard for builder entities)
+  SEO_FIELDS.forEach(f => fields.add(f))
+
+  // Check entity.fields for optional content fields
+  const entityFieldNames = entity.fields?.map(f => f.name) || []
+  OPTIONAL_CONTENT_FIELDS.forEach(f => {
+    if (entityFieldNames.includes(f)) {
+      fields.add(f)
+    }
+  })
+
+  return Array.from(fields).map(quoteField).join(', ')
+}
+
+/**
+ * Resolve pattern references in blocks array
+ *
+ * Fetches all referenced patterns and expands them inline.
+ * This ensures public pages show the actual pattern content.
+ *
+ * @param blocks - Blocks array which may contain pattern references
+ * @returns Resolved blocks array with patterns expanded
+ */
+async function getResolvedBlocks(
+  blocks: (BlockInstance | PatternReference)[]
+): Promise<BlockInstance[]> {
+  // Extract pattern IDs from blocks array
+  const patternIds = extractPatternIds(blocks)
+
+  // If no patterns referenced, return blocks as-is
+  if (patternIds.length === 0) {
+    return blocks as BlockInstance[]
+  }
+
+  try {
+    // Batch fetch all referenced patterns (only published ones)
+    const patterns = await PatternsResolverService.getByIds(patternIds)
+
+    // Build pattern cache (Map for O(1) lookup)
+    const patternCache = new Map(patterns.map((p) => [p.id, p]))
+
+    // Resolve pattern references and return flattened blocks
+    return resolvePatternReferences(blocks, patternCache)
+  } catch (error) {
+    console.error('[getResolvedBlocks] Failed to resolve patterns:', error)
+    // Fallback: Return blocks without pattern resolution
+    // Pattern references will be skipped gracefully
+    return blocks.filter((block) => !('type' in block && block.type === 'pattern')) as BlockInstance[]
+  }
 }
 
 /**
@@ -79,18 +174,24 @@ function buildTemplatePath(entity: EntityConfig): string {
 
 /**
  * Fetch a published item from the database
+ * Dynamically builds SELECT clause based on entity configuration
+ * to avoid querying non-existent columns
  */
 async function fetchPublishedItem(
-  tableName: string,
+  entity: EntityConfig,
   slug: string
 ): Promise<PublishedItem | null> {
   try {
+    const tableName = entity.tableName || entity.slug
+    const selectClause = buildPublicSelectClause(entity)
+
     const result = await query<PublishedItem>(
-      `SELECT * FROM "${tableName}" WHERE slug = $1 AND status = 'published'`,
+      `SELECT ${selectClause} FROM "${tableName}" WHERE slug = $1 AND status = 'published'`,
       [slug]
     )
     return result.rows[0] || null
-  } catch {
+  } catch (error) {
+    console.error(`[fetchPublishedItem] Error fetching ${entity.slug}:`, error)
     return null
   }
 }
@@ -122,7 +223,7 @@ export async function generateMetadata({
     }
 
     // Metadata from database
-    const item = await fetchPublishedItem(entity.tableName || entity.slug, slug)
+    const item = await fetchPublishedItem(entity, slug)
     if (item) {
       return {
         title: item.seoTitle || `${item.title} | Boilerplate`,
@@ -209,12 +310,18 @@ export default async function DynamicPublicPage({
     }
 
     // No template override - use default rendering
-    const item = await fetchPublishedItem(entity.tableName || entity.slug, slug)
+    const item = await fetchPublishedItem(entity, slug)
 
     if (!item) {
       notFound()
     }
 
+    // Resolve pattern references before rendering
+    // This expands pattern blocks inline for public display
+    const resolvedBlocks = await getResolvedBlocks(
+      item.blocks as (BlockInstance | PatternReference)[]
+    )
+
     // Default rendering with PageRenderer
     return (
       <main
@@ -228,7 +335,7 @@ export default async function DynamicPublicPage({
             id: item.id,
             title: item.title,
             slug: item.slug,
-            blocks: item.blocks || [],
+            blocks: resolvedBlocks,
             locale: item.locale || 'en',
           }}
         />

package/dist/templates/app/(public)/docs/[section]/[page]/page.tsx

@@ -0,0 +1,90 @@
+import { notFound } from 'next/navigation'
+import { DOCS_REGISTRY } from '@nextsparkjs/registries/docs-registry'
+import { parseMarkdownFile } from '@nextsparkjs/core/lib/docs/parser'
+import { DocsBreadcrumbs } from '@nextsparkjs/core/components/docs/docs-breadcrumbs'
+import { DocsContent } from '@nextsparkjs/core/components/docs/docs-content'
+import { sel } from '@nextsparkjs/core/selectors'
+import { getTranslations } from 'next-intl/server'
+import path from 'path'
+import type { Metadata } from 'next'
+
+interface DocsPageProps {
+  params: Promise<{
+    section: string
+    page: string
+  }>
+}
+
+export async function generateStaticParams() {
+  const params: Array<{ section: string; page: string }> = []
+
+  // Generate params for public docs only
+  for (const section of DOCS_REGISTRY.public) {
+    for (const page of section.pages) {
+      params.push({
+        section: section.slug,
+        page: page.slug
+      })
+    }
+  }
+
+  return params
+}
+
+export async function generateMetadata({ params }: DocsPageProps): Promise<Metadata> {
+  const resolvedParams = await params
+  const { section: sectionSlug, page: pageSlug } = resolvedParams
+
+  const section = DOCS_REGISTRY.public.find(s => s.slug === sectionSlug)
+  if (!section) return { title: 'Page Not Found' }
+
+  const page = section.pages.find(p => p.slug === pageSlug)
+  if (!page) return { title: 'Page Not Found' }
+
+  const filePath = path.join(process.cwd(), page.path)
+  const { metadata } = await parseMarkdownFile(filePath)
+
+  return {
+    title: `${metadata.title} | Documentation`,
+    description: metadata.description || `Documentation for ${metadata.title}`
+  }
+}
+
+export default async function DocsPage({ params }: DocsPageProps) {
+  const resolvedParams = await params
+  const { section: sectionSlug, page: pageSlug } = resolvedParams
+  const t = await getTranslations('docs')
+
+  // Find section in public docs
+  const section = DOCS_REGISTRY.public.find(s => s.slug === sectionSlug)
+  if (!section) notFound()
+
+  // Find page in section
+  const page = section.pages.find(p => p.slug === pageSlug)
+  if (!page) notFound()
+
+  // Parse markdown file
+  const filePath = path.join(process.cwd(), page.path)
+  const { metadata, html } = await parseMarkdownFile(filePath)
+
+  return (
+    <div className="max-w-4xl" data-cy={sel('public.docs.pageDetail')}>
+      <DocsBreadcrumbs
+        items={[
+          { label: t('breadcrumbs.home'), href: '/docs' },
+          { label: section.title },
+          { label: metadata.title }
+        ]}
+      />
+
+      <article className="mt-8 prose prose-slate dark:prose-invert max-w-none">
+        <h1 className="text-4xl font-bold mb-2">{metadata.title}</h1>
+        {metadata.description && (
+          <p className="text-xl text-muted-foreground mb-8">{metadata.description}</p>
+        )}
+
+        <DocsContent html={html} />
+      </article>
+    </div>
+  )
+}

package/dist/templates/app/(public)/docs/layout.tsx

@@ -0,0 +1,25 @@
+import { Suspense } from 'react'
+import { DocsLayout } from '@nextsparkjs/core/components/docs/docs-layout'
+import { DocsSidebar } from '@nextsparkjs/core/components/docs/docs-sidebar'
+import { DOCS_REGISTRY } from '@nextsparkjs/registries/docs-registry'
+import { sel } from '@nextsparkjs/core/selectors'
+
+export default function DocsLayoutPage({
+  children
+}: {
+  children: React.ReactNode
+}) {
+  // Only show public docs in this layout
+  const sections = DOCS_REGISTRY.public
+
+  return (
+    <DocsLayout>
+      <DocsSidebar sections={sections} />
+      <main className="flex-1 p-6 lg:p-8" data-cy={sel('public.docs.mainContent')}>
+        <Suspense fallback={<div className="animate-pulse">Loading...</div>}>
+          {children}
+        </Suspense>
+      </main>
+    </DocsLayout>
+  )
+}

package/dist/templates/app/(public)/docs/page.tsx

@@ -0,0 +1,81 @@
+import { Card, CardContent, CardDescription, CardHeader, CardTitle } from '@nextsparkjs/core/components/ui/card'
+import { DOCS_REGISTRY } from '@nextsparkjs/registries/docs-registry'
+import { sel } from '@nextsparkjs/core/selectors'
+import { BookOpen, Folder, FileText, ArrowRight } from 'lucide-react'
+import Link from 'next/link'
+import type { Metadata } from 'next'
+
+export const metadata: Metadata = {
+  title: 'Documentation',
+  description: 'Complete documentation for the application'
+}
+
+export default function DocsPage() {
+  const sections = DOCS_REGISTRY.public
+
+  return (
+    <div className="container max-w-7xl mx-auto px-4 py-8">
+      {/* Hero Section */}
+      <div className="text-center mb-12">
+        <div className="inline-flex items-center gap-2 bg-primary/10 text-primary px-3 py-1 rounded-full text-sm font-medium mb-4">
+          <BookOpen className="h-4 w-4" />
+          Documentation
+        </div>
+        <h1 className="text-4xl font-bold mb-4">
+          Documentation
+        </h1>
+        <p className="text-xl text-muted-foreground max-w-2xl mx-auto">
+          Guides and reference documentation to help you get the most out of the application.
+        </p>
+      </div>
+
+      {/* Documentation Sections */}
+      {sections.length > 0 ? (
+        <div className="grid grid-cols-1 md:grid-cols-2 lg:grid-cols-3 gap-6">
+          {sections.map((section) => (
+            <Card key={section.slug} className="h-full hover:shadow-lg transition-shadow" data-cy={sel('public.docs.sectionCard', { slug: section.slug })}>
+              <CardHeader>
+                <div className="flex items-center gap-3 mb-3">
+                  <div className="p-2 bg-primary/10 rounded-lg text-primary">
+                    <Folder className="h-6 w-6" />
+                  </div>
+                  <div>
+                    <CardTitle className="text-lg">{section.title}</CardTitle>
+                  </div>
+                </div>
+                <CardDescription>
+                  {section.pages.length} {section.pages.length === 1 ? 'page' : 'pages'}
+                </CardDescription>
+              </CardHeader>
+              <CardContent>
+                <ul className="space-y-2">
+                  {section.pages.map((page) => (
+                    <li key={page.slug}>
+                      <Link
+                        href={`/docs/${section.slug}/${page.slug}`}
+                        className="text-sm text-muted-foreground hover:text-foreground transition-colors flex items-center gap-2 group"
+                        data-cy={sel('public.docs.pageLink', { slug: page.slug })}
+                      >
+                        <FileText className="h-3 w-3" />
+                        <span className="flex-1">{page.title}</span>
+                        <ArrowRight className="h-3 w-3 opacity-0 group-hover:opacity-100 group-hover:translate-x-0.5 transition-all" />
+                      </Link>
+                    </li>
+                  ))}
+                </ul>
+              </CardContent>
+            </Card>
+          ))}
+        </div>
+      ) : (
+        <div className="text-center py-12">
+          <BookOpen className="h-12 w-12 text-muted-foreground mx-auto mb-4" />
+          <h2 className="text-xl font-semibold mb-2">No Documentation Available</h2>
+          <p className="text-muted-foreground">
+            Documentation will appear here once it is added to the project.
+          </p>
+        </div>
+      )}
+    </div>
+  )
+}