spine-framework 0.1.0

package/.framework/migrations/001_seed.sql

@@ -0,0 +1,92 @@
+-- =============================================================================
+-- 001_seed.sql
+-- Spine Framework — Bare minimum bootstrap data for a fresh install
+-- Generated from live production DB audit: May 28, 2026
+-- =============================================================================
+-- Run AFTER 000_foundation.sql.
+--
+-- This file contains ONLY what is required for Spine to boot and for a
+-- system_admin to log in and interact with the framework. Nothing more.
+--
+-- What requires seeding before the app can function:
+--   1. system_admin role        — people.role_id FK target
+--   2. spine-core app           — required by runtime; people/accounts ref app_id
+--   3. account type             — accounts.type_id is NOT NULL
+--   4. person type              — people.type_id is NOT NULL
+--   5. root system account      — people.account_id is NOT NULL; the bootstrap
+--                                 system_admin must belong to an account
+--
+-- Everything else (additional roles, app-specific types, tenant accounts,
+-- app-owned link types) belongs in app seed files or is created via the admin UI.
+-- =============================================================================
+
+-- ---------------------------------------------------------------------------
+-- 1. System Role
+-- ---------------------------------------------------------------------------
+INSERT INTO public.roles (slug, name, description, permissions, is_system, is_active, is_protected)
+VALUES (
+  'system_admin',
+  'System Admin',
+  'Full system access — can manage all accounts, types, and system configuration',
+  '["*"]'::jsonb,
+  true,
+  true,
+  true
+)
+ON CONFLICT DO NOTHING;
+
+-- ---------------------------------------------------------------------------
+-- 2. Spine Core App
+-- ---------------------------------------------------------------------------
+INSERT INTO public.apps (slug, name, description, version, app_type, source, is_active, is_system, min_role, config, nav_items, route_prefix, renderer, integration_deps, metadata)
+VALUES (
+  'spine-core',
+  'Spine Core',
+  'Core Spine runtime — provides accounts, people, items, threads, messages, links, attachments, watchers',
+  '1.0.0',
+  'system',
+  'builtin',
+  true,
+  true,
+  NULL,
+  '{}'::jsonb,
+  '[]'::jsonb,
+  NULL,
+  'none',
+  '[]'::jsonb,
+  '{}'::jsonb
+)
+ON CONFLICT (slug) DO NOTHING;
+
+-- ---------------------------------------------------------------------------
+-- 3. Core Types
+-- accounts.type_id and people.type_id are both NOT NULL, so these must exist
+-- before any account or person can be created.
+-- ---------------------------------------------------------------------------
+INSERT INTO public.types (app_id, kind, slug, name, description, ownership, is_active)
+VALUES
+  ((SELECT id FROM public.apps WHERE slug = 'spine-core'), 'account', 'account', 'Account', 'Organization or tenant account', 'pack', true),
+  ((SELECT id FROM public.apps WHERE slug = 'spine-core'), 'person',  'person',  'Person',  'User or contact person',         'pack', true)
+ON CONFLICT (app_id, kind, slug) DO NOTHING;
+
+-- ---------------------------------------------------------------------------
+-- 4. Root System Account
+-- The first system_admin person must belong to an account. This is the
+-- bootstrap account for the Spine system itself.
+-- NOTE: The system_admin person record is NOT seeded here — it is created
+-- via Supabase Auth invite + the onboarding flow, which stamps type_id and
+-- role_id onto the resulting people row.
+-- ---------------------------------------------------------------------------
+INSERT INTO public.accounts (type_id, slug, display_name, description, is_active)
+VALUES (
+  (SELECT id FROM public.types WHERE kind = 'account' AND slug = 'account'),
+  'spine-system',
+  'Spine System',
+  'Root system account for the Spine framework',
+  true
+)
+ON CONFLICT (slug) DO NOTHING;
+
+-- NOTE: No link types are seeded here. All link types are app-owned.
+-- Cortex seeds: account_signals, account_opportunities, analyzed_by, tagged_with
+-- See custom/apps/cortex/seed/link-types.json

package/.framework/migrations/002_seed_constraints.sql

@@ -0,0 +1,13 @@
+-- =============================================================================
+-- 002_seed_constraints.sql
+-- Adds unique constraints required for idempotent seed upserts
+-- =============================================================================
+
+-- link_types needs unique on (app_id, slug) for seed upserts
+ALTER TABLE public.link_types ADD CONSTRAINT IF NOT EXISTS link_types_app_id_slug_key UNIQUE (app_id, slug);
+
+-- triggers needs unique on (app_id, name) for seed upserts
+ALTER TABLE public.triggers ADD CONSTRAINT IF NOT EXISTS triggers_app_id_name_key UNIQUE (app_id, name);
+
+-- pipelines needs unique on (app_id, name) for seed upserts
+ALTER TABLE public.pipelines ADD CONSTRAINT IF NOT EXISTS pipelines_app_id_name_key UNIQUE (app_id, name);

package/.framework/migrations/003_auth_user_trigger.sql

@@ -0,0 +1,59 @@
+-- =============================================================================
+-- 003_auth_user_trigger.sql
+-- Creates a people record whenever a new Supabase auth user signs up.
+-- Run AFTER 001_seed.sql (requires spine-system account and person type).
+--
+-- First user ever → system_admin role (bootstrap)
+-- Subsequent users → no role (assigned later via admin invite flow)
+-- =============================================================================
+
+CREATE OR REPLACE FUNCTION public.handle_new_auth_user()
+RETURNS TRIGGER LANGUAGE plpgsql SECURITY DEFINER SET search_path = public AS $$
+DECLARE
+  v_account_id uuid;
+  v_type_id    uuid;
+  v_role_id    uuid;
+  v_is_first   boolean;
+BEGIN
+  SELECT id INTO v_account_id FROM public.accounts WHERE slug = 'spine-system' LIMIT 1;
+  SELECT id INTO v_type_id    FROM public.types   WHERE kind = 'person' AND slug = 'person' LIMIT 1;
+
+  IF v_account_id IS NULL OR v_type_id IS NULL THEN
+    RAISE WARNING 'handle_new_auth_user: spine-system account or person type not found — skipping people insert';
+    RETURN NEW;
+  END IF;
+
+  -- First person ever gets system_admin; subsequent users get no role
+  SELECT NOT EXISTS (SELECT 1 FROM public.people LIMIT 1) INTO v_is_first;
+  IF v_is_first THEN
+    SELECT id INTO v_role_id FROM public.roles WHERE slug = 'system_admin' LIMIT 1;
+  END IF;
+
+  INSERT INTO public.people (
+    id,
+    auth_uid,
+    email,
+    full_name,
+    account_id,
+    type_id,
+    role_id,
+    is_active
+  ) VALUES (
+    NEW.id,
+    NEW.id,
+    NEW.email,
+    COALESCE(NEW.raw_user_meta_data->>'full_name', split_part(NEW.email, '@', 1)),
+    v_account_id,
+    v_type_id,
+    v_role_id,
+    true
+  )
+  ON CONFLICT (id) DO NOTHING;
+
+  RETURN NEW;
+END;
+$$;
+
+CREATE OR REPLACE TRIGGER on_auth_user_created
+  AFTER INSERT ON auth.users
+  FOR EACH ROW EXECUTE FUNCTION public.handle_new_auth_user();

package/.framework/src/App.tsx

@@ -0,0 +1,126 @@
+import { Suspense, lazy } from 'react'
+import { Routes, Route, Navigate } from 'react-router-dom'
+import { useAuth } from './contexts/AuthContext'
+import { LoadingSpinner } from './components/ui/LoadingSpinner'
+import { LoginPage } from './pages/auth/LoginPage'
+import { RegisterPage } from './pages/auth/RegisterPage'
+import { NotFoundPage } from './pages/NotFoundPage'
+import { DashboardPage } from './pages/DashboardPage'
+import { AppWrapper } from './components/AppWrapper'
+import { AppsRegistryProvider, useAppsRegistry } from './contexts/AppContext'
+import { CustomAppLoader } from './components/CustomAppLoader'
+import { GenericAppShell } from './components/app-shell/GenericAppShell'
+import { APIPage } from './pages/spine-framework/APIPage'
+import { CLIPage } from './pages/spine-framework/CLIPage'
+
+const AdminApp = lazy(() => import('./apps/admin/index'))
+
+function App() {
+  const { user, isLoading } = useAuth()
+
+  if (isLoading) {
+    return (
+      <div className="min-h-screen flex items-center justify-center bg-slate-50">
+        <div className="text-center">
+          <LoadingSpinner className="w-8 h-8 mx-auto mb-4" />
+          <p className="text-slate-600">Loading Spine...</p>
+        </div>
+      </div>
+    )
+  }
+
+  return (
+    <AppsRegistryProvider>
+      {!user ? (
+        <Routes>
+          <Route path="/login" element={<LoginPage />} />
+          <Route path="/register" element={<RegisterPage />} />
+          <Route path="*" element={<Navigate to="/login" replace />} />
+        </Routes>
+      ) : (
+        <AuthenticatedRouter />
+      )}
+    </AppsRegistryProvider>
+  )
+}
+
+function AuthenticatedRouter() {
+  const { routableApps: apps, loading } = useAppsRegistry()
+
+  if (loading) {
+    return (
+      <div className="min-h-screen flex items-center justify-center bg-slate-50">
+        <div className="text-center">
+          <LoadingSpinner className="w-8 h-8 mx-auto mb-4" />
+          <p className="text-slate-600">Loading apps...</p>
+        </div>
+      </div>
+    )
+  }
+
+  // Sort: explicit prefixes first, root (/) last
+  const sorted = [...apps]
+    .filter(app => app.slug !== 'spine-framework' && !app.route_prefix?.startsWith('/spine-framework'))
+    .sort((a, b) => {
+      if (a.route_prefix === '/') return 1
+      if (b.route_prefix === '/') return -1
+      return (b.route_prefix?.length || 0) - (a.route_prefix?.length || 0)
+    })
+
+  return (
+    <Suspense fallback={<div className="min-h-screen flex items-center justify-center"><LoadingSpinner /></div>}>
+      <Routes>
+        {/* Default redirect */}
+        <Route path="/" element={<Navigate to="/dashboard" replace />} />
+        <Route path="/dashboard" element={<DashboardPage />} />
+        
+        {/* Login route for authenticated users (redirects to qualified app) */}
+        <Route path="/login" element={<LoginPage />} />
+
+        {/* ── Spine Framework namespace (reserved — no custom app may use this path) ── */}
+        <Route path="/spine-framework/admin/*" element={<AdminApp />} />
+        <Route path="/spine-framework/api" element={<APIPage />} />
+        <Route path="/spine-framework/cli" element={<CLIPage />} />
+
+        {/* Dynamic app routes */}
+        {sorted.map(app => {
+          const prefix = app.route_prefix!
+
+          if (app.renderer === 'custom') {
+            return (
+              <Route
+                key={app.slug}
+                path={`${prefix}/*`}
+                element={
+                  <AppWrapper app={app}>
+                    <CustomAppLoader slug={app.slug} />
+                  </AppWrapper>
+                }
+              />
+            )
+          }
+
+          if (app.renderer === 'generic') {
+            return (
+              <Route
+                key={app.slug}
+                path={`${prefix}/*`}
+                element={
+                  <AppWrapper app={app}>
+                    <GenericAppShell app={app} />
+                  </AppWrapper>
+                }
+              />
+            )
+          }
+
+          return null
+        })}
+
+        <Route path="*" element={<NotFoundPage />} />
+      </Routes>
+    </Suspense>
+  )
+}
+
+export default App

package/.framework/src/apps/admin/index.tsx

@@ -0,0 +1,173 @@
+import { lazy, Suspense } from 'react'
+import { Routes, Route, Navigate, useLocation } from 'react-router-dom'
+import { LoadingSpinner } from '../../components/ui/LoadingSpinner'
+import { NotFoundPage } from '../../pages/NotFoundPage'
+import { useAuth } from '../../contexts/AuthContext'
+import { AppShell } from '../../components/layout/AppShell'
+import { AdminSidebar } from '../../components/admin/AdminSidebar'
+import { TooltipProvider } from '../../components/ui/tooltip'
+
+// Config list pages
+const TypesPage = lazy(() => import('../../pages/admin/TypesPage').then(m => ({ default: m.TypesPage })))
+const AppsPage = lazy(() => import('../../pages/admin/AppsPage').then(m => ({ default: m.AppsPage })))
+const TypeDetailPage = lazy(() => import('../../pages/admin/TypeDetailPage').then(m => ({ default: m.TypeDetailPage })))
+const PipelinesPage = lazy(() => import('../../pages/admin/PipelinesPage').then(m => ({ default: m.PipelinesPage })))
+const TriggersPage = lazy(() => import('../../pages/admin/TriggersPage').then(m => ({ default: m.TriggersPage })))
+const AIAgentsPage = lazy(() => import('../../pages/admin/AIAgentsPage').then(m => ({ default: m.AIAgentsPage })))
+const EmbeddingsPage = lazy(() => import('../../pages/admin/EmbeddingsPage').then(m => ({ default: m.EmbeddingsPage })))
+const TimersPage = lazy(() => import('../../pages/admin/TimersPage').then(m => ({ default: m.TimersPage })))
+const IntegrationsPage = lazy(() => import('../../pages/admin/IntegrationsPage').then(m => ({ default: m.IntegrationsPage })))
+
+// Config detail pages
+const AppDetailPage = lazy(() => import('../../pages/admin/AppDetailPage').then(m => ({ default: m.AppDetailPage })))
+const PipelineDetailPage = lazy(() => import('../../pages/admin/PipelineDetailPage').then(m => ({ default: m.PipelineDetailPage })))
+const TriggerDetailPage = lazy(() => import('../../pages/admin/TriggerDetailPage').then(m => ({ default: m.TriggerDetailPage })))
+const AIAgentDetailPage = lazy(() => import('../../pages/admin/AIAgentDetailPage').then(m => ({ default: m.AIAgentDetailPage })))
+const EmbeddingDetailPage = lazy(() => import('../../pages/admin/EmbeddingDetailPage').then(m => ({ default: m.EmbeddingDetailPage })))
+const TimerDetailPage = lazy(() => import('../../pages/admin/TimerDetailPage').then(m => ({ default: m.TimerDetailPage })))
+const IntegrationDetailPage = lazy(() => import('../../pages/admin/IntegrationDetailPage').then(m => ({ default: m.IntegrationDetailPage })))
+const RolesPage = lazy(() => import('../../pages/admin/RolesPage').then(m => ({ default: m.RolesPage })))
+const RoleDetailPage = lazy(() => import('../../pages/admin/RoleDetailPage').then(m => ({ default: m.RoleDetailPage })))
+const PromptConfigsPage = lazy(() => import('../../pages/admin/PromptConfigsPage').then(m => ({ default: m.PromptConfigsPage })))
+const PromptConfigDetailPage = lazy(() => import('../../pages/admin/PromptConfigDetailPage').then(m => ({ default: m.PromptConfigDetailPage })))
+const APIKeysPage = lazy(() => import('../../pages/admin/APIKeysPage').then(m => ({ default: m.APIKeysPage })))
+const APIKeyDetailPage = lazy(() => import('../../pages/admin/APIKeyDetailPage').then(m => ({ default: m.APIKeyDetailPage })))
+
+// Observability pages
+const ObservabilityDashboard = lazy(() => import('../../pages/admin/ObservabilityDashboard').then(m => ({ default: m.ObservabilityDashboard })))
+const PipelineExecutionsPage = lazy(() => import('../../pages/admin/PipelineExecutionsPage').then(m => ({ default: m.PipelineExecutionsPage })))
+const LogsPage = lazy(() => import('../../pages/admin/LogsPage').then(m => ({ default: m.LogsPage })))
+const AlertsConfigPage = lazy(() => import('../../pages/admin/AlertsConfigPage').then(m => ({ default: m.AlertsConfigPage })))
+
+// Runtime data pages (unified)
+const DataListPage = lazy(() => import('../../components/runtime/DataListPage').then(m => ({ default: m.DataListPage })))
+const DataDetailPage = lazy(() => import('../../components/runtime/DataDetailPage').then(m => ({ default: m.DataDetailPage })))
+
+// Testing pages
+const TestingDashboard = lazy(() => import('../../pages/admin/TestingDashboard'))
+const TestRunDetailPage = lazy(() => import('../../pages/admin/TestRunDetailPage').then(m => ({ default: m.TestRunDetailPage })))
+const ShadcnTestPage = lazy(() => import('../../pages/admin/ShadcnTestPage').then(m => ({ default: m.ShadcnTestPage })))
+const MinimalShadcnTestPage = lazy(() => import('../../pages/admin/MinimalShadcnTestPage').then(m => ({ default: m.MinimalShadcnTestPage })))
+const IncrementalShadcnTestPage = lazy(() => import('../../pages/admin/IncrementalShadcnTestPage').then(m => ({ default: m.IncrementalShadcnTestPage })))
+const ExtendedShadcnTestPage = lazy(() => import('../../pages/admin/ExtendedShadcnTestPage').then(m => ({ default: m.ExtendedShadcnTestPage })))
+const SelectTestPage = lazy(() => import('../../pages/admin/SelectTestPage').then(m => ({ default: m.SelectTestPage })))
+const DesignedPage = lazy(() => import('../../pages/admin/DesignedPage').then(m => ({ default: m.DesignedPage })))
+const ProperlyDesignedPage = lazy(() => import('../../pages/admin/ProperlyDesignedPage').then(m => ({ default: m.ProperlyDesignedPage })))
+const IntegratedDashboard = lazy(() => import('../../pages/admin/IntegratedDashboard').then(m => ({ default: m.IntegratedDashboard })))
+const SimpleDashboard = lazy(() => import('../../pages/admin/SimpleDashboard').then(m => ({ default: m.SimpleDashboard })))
+
+function AdminRoutes() {
+  const location = useLocation()
+
+  // Build breadcrumbs from current path
+  const pathSegments = location.pathname.split('/').filter(Boolean)
+  const breadcrumbs: { title: string; url?: string }[] = [{ title: 'Spine', url: '/dashboard' }]
+
+  // Add admin section
+  if (pathSegments.includes('admin')) {
+    breadcrumbs.push({ title: 'Admin', url: '/spine-framework/admin' })
+
+    // Add subsection
+    const section = pathSegments[2]
+    if (section) {
+      breadcrumbs.push({ title: section.charAt(0).toUpperCase() + section.slice(1) })
+    }
+  }
+
+  return (
+    <AppShell
+      sidebar={<AdminSidebar />}
+      breadcrumbs={breadcrumbs}
+    >
+      <Suspense fallback={<div className="min-h-[400px] flex items-center justify-center"><LoadingSpinner /></div>}>
+        <Routes>
+          {/* Default redirect → configs */}
+          <Route index element={<Navigate to="configs/types" replace />} />
+          <Route path="dashboard" element={<Navigate to="configs/types" replace />} />
+
+          {/* Configs section */}
+          <Route path="configs/types/new" element={<TypeDetailPage />} />
+          <Route path="configs/types/:id" element={<TypeDetailPage />} />
+          <Route path="configs/types" element={<TypesPage />} />
+          <Route path="configs/apps/new" element={<AppDetailPage />} />
+          <Route path="configs/apps/:id" element={<AppDetailPage />} />
+          <Route path="configs/apps" element={<AppsPage />} />
+          <Route path="configs/pipelines/new" element={<PipelineDetailPage />} />
+          <Route path="configs/pipelines/:id" element={<PipelineDetailPage />} />
+          <Route path="configs/pipelines" element={<PipelinesPage />} />
+          <Route path="configs/triggers/new" element={<TriggerDetailPage />} />
+          <Route path="configs/triggers/:id" element={<TriggerDetailPage />} />
+          <Route path="configs/triggers" element={<TriggersPage />} />
+          <Route path="configs/ai-agents/new" element={<AIAgentDetailPage />} />
+          <Route path="configs/ai-agents/:id" element={<AIAgentDetailPage />} />
+          <Route path="configs/ai-agents" element={<AIAgentsPage />} />
+          <Route path="configs/embeddings/new" element={<EmbeddingDetailPage />} />
+          <Route path="configs/embeddings/:id" element={<EmbeddingDetailPage />} />
+          <Route path="configs/embeddings" element={<EmbeddingsPage />} />
+          <Route path="configs/timers/new" element={<TimerDetailPage />} />
+          <Route path="configs/timers/:id" element={<TimerDetailPage />} />
+          <Route path="configs/timers" element={<TimersPage />} />
+          <Route path="configs/integrations/new" element={<IntegrationDetailPage />} />
+          <Route path="configs/integrations/:id" element={<IntegrationDetailPage />} />
+          <Route path="configs/integrations" element={<IntegrationsPage />} />
+          <Route path="configs/roles/new" element={<RoleDetailPage />} />
+          <Route path="configs/roles/:id" element={<RoleDetailPage />} />
+          <Route path="configs/roles" element={<RolesPage />} />
+          <Route path="configs/prompts/new" element={<PromptConfigDetailPage />} />
+          <Route path="configs/prompts/:id" element={<PromptConfigDetailPage />} />
+          <Route path="configs/prompts" element={<PromptConfigsPage />} />
+          <Route path="configs/api-keys/new" element={<APIKeyDetailPage />} />
+          <Route path="configs/api-keys/:id" element={<APIKeyDetailPage />} />
+          <Route path="configs/api-keys" element={<APIKeysPage />} />
+
+          {/* Observability section */}
+          <Route path="observability" element={<ObservabilityDashboard />} />
+          <Route path="observability/dashboard" element={<ObservabilityDashboard />} />
+          <Route path="observability/alerts" element={<AlertsConfigPage />} />
+          <Route path="observability/executions/:id" element={<PipelineExecutionsPage />} />
+          <Route path="observability/executions" element={<PipelineExecutionsPage />} />
+          <Route path="observability/logs" element={<LogsPage />} />
+
+          {/* Testing section */}
+          <Route path="testing/:run_id" element={<TestRunDetailPage />} />
+          <Route path="testing" element={<TestingDashboard />} />
+          <Route path="test/ui" element={<ShadcnTestPage />} />
+          <Route path="test/minimal" element={<MinimalShadcnTestPage />} />
+          <Route path="test/incremental" element={<IncrementalShadcnTestPage />} />
+          <Route path="test/extended" element={<ExtendedShadcnTestPage />} />
+          <Route path="test/select" element={<SelectTestPage />} />
+          <Route path="test/designed" element={<DesignedPage />} />
+          <Route path="test/properly-designed" element={<ProperlyDesignedPage />} />
+          <Route path="test/integrated" element={<IntegratedDashboard />} />
+          <Route path="test/simple" element={<SimpleDashboard />} />
+
+          {/* Runtime Data - Unified entity management */}
+          <Route path="runtime/:entity" element={<DataListPage />} />
+          <Route path="runtime/:entity/new" element={<DataDetailPage />} />
+          <Route path="runtime/:entity/:id" element={<DataDetailPage />} />
+
+          {/* Legacy data routes - redirect to runtime routes */}
+          <Route path="data/:entity" element={<Navigate to="../runtime/:entity" replace />} />
+          <Route path="data/:entity/create" element={<Navigate to="../runtime/:entity/new" replace />} />
+          <Route path="data/:entity/:id" element={<Navigate to="../runtime/:entity/:id" replace />} />
+
+          <Route path="*" element={<NotFoundPage />} />
+        </Routes>
+      </Suspense>
+    </AppShell>
+  )
+}
+
+export default function AdminApp() {
+  const { user } = useAuth()
+
+  if (!user?.is_system_admin) {
+    return <Navigate to="/dashboard" replace />
+  }
+
+  return (
+    <TooltipProvider>
+      <AdminRoutes />
+    </TooltipProvider>
+  )
+}

package/.framework/src/components/AppWrapper.tsx

@@ -0,0 +1,56 @@
+import React from 'react'
+import { Navigate } from 'react-router-dom'
+import { useAuth } from '../contexts/AuthContext'
+import { AppProvider } from '../contexts/AppContext'
+import { AppRecord } from '../hooks/useApps'
+
+interface AppWrapperProps {
+  app: AppRecord
+  children: React.ReactNode
+}
+
+/**
+ * Shared wrapper for all apps. Provides:
+ * - Auth gate: redirects to /login if unauthenticated
+ * - Role gate: shows 403 if user lacks app's min_role
+ * - App context: makes app record available via useCurrentApp()
+ */
+export function AppWrapper({ app, children }: AppWrapperProps) {
+  const { user } = useAuth()
+
+  // Auth gate
+  if (!user) {
+    return <Navigate to="/login" replace />
+  }
+
+  // Role gate
+  if (app.min_role) {
+    const hasRole = user.roles?.includes('system_admin') || user.roles?.includes(app.min_role)
+    if (!hasRole) {
+      return (
+        <div className="min-h-screen flex items-center justify-center bg-slate-50">
+          <div className="text-center p-8">
+            <div className="w-16 h-16 bg-red-100 rounded-full flex items-center justify-center mx-auto mb-4">
+              <svg className="w-8 h-8 text-red-600" fill="none" stroke="currentColor" viewBox="0 0 24 24">
+                <path strokeLinecap="round" strokeLinejoin="round" strokeWidth={2} d="M12 9v2m0 4h.01m-6.938 4h13.856c1.54 0 2.502-1.667 1.732-2.5L13.732 4c-.77-.833-1.964-.833-2.732 0L3.732 16.5c-.77.833.192 2.5 1.732 2.5z" />
+              </svg>
+            </div>
+            <h1 className="text-2xl font-bold text-slate-900 mb-2">Access Denied</h1>
+            <p className="text-slate-600 mb-6">You don't have permission to access {app.name}.</p>
+            <div className="bg-slate-100 rounded-lg p-4 text-left">
+              <p className="text-sm text-slate-600 mb-2"><strong>Your roles:</strong> {user.roles?.join(', ') || 'None'}</p>
+              <p className="text-sm text-slate-600"><strong>Required:</strong> {app.min_role}</p>
+            </div>
+          </div>
+        </div>
+      )
+    }
+  }
+
+  // App context
+  return (
+    <AppProvider app={app}>
+      {children}
+    </AppProvider>
+  )
+}

package/.framework/src/components/CustomAppLoader.tsx

@@ -0,0 +1,116 @@
+import React, { lazy, Suspense, Component } from 'react'
+import type { ReactNode } from 'react'
+import { LoadingSpinner } from './ui/LoadingSpinner'
+
+// ─── ERROR BOUNDARY ───────────────────────────────────────────────────────────
+
+interface ErrorBoundaryProps {
+  slug: string
+  children: ReactNode
+}
+
+interface ErrorBoundaryState {
+  error: Error | null
+}
+
+class AppErrorBoundary extends Component<ErrorBoundaryProps, ErrorBoundaryState> {
+  constructor(props: ErrorBoundaryProps) {
+    super(props)
+    this.state = { error: null }
+  }
+
+  static getDerivedStateFromError(error: Error): ErrorBoundaryState {
+    return { error }
+  }
+
+  render() {
+    if (this.state.error) {
+      return (
+        <div className="min-h-screen flex items-center justify-center bg-slate-50">
+          <div className="text-center p-8 max-w-lg">
+            <div className="w-16 h-16 bg-amber-100 rounded-full flex items-center justify-center mx-auto mb-4">
+              <svg className="w-8 h-8 text-amber-600" fill="none" stroke="currentColor" viewBox="0 0 24 24">
+                <path strokeLinecap="round" strokeLinejoin="round" strokeWidth={2} d="M12 9v2m0 4h.01m-6.938 4h13.856c1.54 0 2.502-1.667 1.732-2.5L13.732 4c-.77-.833-1.964-.833-2.732 0L3.732 16.5c-.77.833.192 2.5 1.732 2.5z" />
+              </svg>
+            </div>
+            <h1 className="text-2xl font-bold text-slate-900 mb-2">App Load Error</h1>
+            <p className="text-slate-600 mb-4">
+              Failed to load the <strong>{this.props.slug}</strong> app.
+            </p>
+            <pre className="bg-slate-100 rounded-lg p-4 text-left text-sm text-red-600 overflow-auto mb-4">
+              {this.state.error.message}
+            </pre>
+            <p className="text-sm text-slate-500">
+              Check that <code>apps/{this.props.slug}/index.tsx</code> exists and exports a default component.
+            </p>
+          </div>
+        </div>
+      )
+    }
+
+    return this.props.children
+  }
+}
+
+// ─── LOADER ───────────────────────────────────────────────────────────────────
+
+// Static glob maps — Vite analyzes these at build time and builds a complete
+// module map. Runtime lookup is just a map key lookup, no dynamic string eval.
+// Custom apps take precedence over core apps with the same slug.
+const customAppModules = import.meta.glob('../../../custom/apps/*/index.tsx')
+const coreAppModules   = import.meta.glob('../apps/*/index.tsx')
+
+// Module-level cache for lazy components to avoid re-creating on each render
+const appModuleCache = new Map<string, React.LazyExoticComponent<React.ComponentType>>()
+
+// Resolve the glob key for a given slug from the custom or core map.
+function resolveAppLoader(slug: string): (() => Promise<{ default: React.ComponentType }>) | null {
+  // Check custom first (custom/apps/{slug}/index.tsx)
+  const customKey = `../../../custom/apps/${slug}/index.tsx`
+  if (customAppModules[customKey]) {
+    return customAppModules[customKey] as () => Promise<{ default: React.ComponentType }>
+  }
+  // Fall back to core (../apps/{slug}/index.tsx relative to this file)
+  const coreKey = `../apps/${slug}/index.tsx`
+  if (coreAppModules[coreKey]) {
+    return coreAppModules[coreKey] as () => Promise<{ default: React.ComponentType }>
+  }
+  return null
+}
+
+function getAppComponent(slug: string): React.LazyExoticComponent<React.ComponentType> {
+  if (!appModuleCache.has(slug)) {
+    const loader = resolveAppLoader(slug)
+    const LazyComponent = lazy(
+      loader
+        ? loader
+        : () => Promise.reject(new Error(`App "${slug}" not found. Expected apps/${slug}/index.tsx in custom/apps or .framework/src/apps.`))
+    )
+    appModuleCache.set(slug, LazyComponent)
+  }
+  return appModuleCache.get(slug)!
+}
+
+interface CustomAppLoaderProps {
+  slug: string
+}
+
+/**
+ * Lazy-loads a custom app component from apps/{slug}/index.tsx.
+ * Wraps in an error boundary so a broken app doesn't crash the entire site.
+ */
+export function CustomAppLoader({ slug }: CustomAppLoaderProps) {
+  const AppComponent = getAppComponent(slug)
+
+  return (
+    <AppErrorBoundary slug={slug}>
+      <Suspense fallback={
+        <div className="min-h-screen flex items-center justify-center">
+          <LoadingSpinner />
+        </div>
+      }>
+        <AppComponent />
+      </Suspense>
+    </AppErrorBoundary>
+  )
+}