spine-framework-cortex 0.1.7 → 1.0.0

package/custom/apps/cortex/docs/configuration.md

@@ -0,0 +1,222 @@
+# Cortex App Configuration
+
+This guide explains how to configure and deploy the Cortex app for customer support, CRM, and community management.
+
+## Database Configuration
+
+### 1. Apps Table Entry
+
+Insert the Cortex app into the `public.apps` table:
+
+```sql
+INSERT INTO public.apps (
+  id,
+  slug, 
+  name,
+  description,
+  version,
+  app_type,
+  source,
+  owner_account_id,
+  is_active,
+  is_system,
+  min_role,
+  config,
+  nav_items,
+  route_prefix,
+  renderer,
+  created_at
+) VALUES (
+  gen_random_uuid(),
+  'cortex',
+  'Cortex',
+  'Unified workspace for CRM, Support, Community, and Knowledge Base',
+  '1.0.0',
+  'custom',
+  'spine-framework',
+  'd3ab4cf8-33de-4ca5-97a2-dbc288c94338', -- spine-system account
+  true,
+  false,
+  'support',
+  '{}',
+  '[
+    {
+      "title": "Dashboard",
+      "path": "/dashboard",
+      "icon": "LayoutDashboard",
+      "order": 1
+    },
+    {
+      "title": "CRM", 
+      "path": "/crm",
+      "icon": "Users",
+      "order": 2,
+      "children": [
+        {"title": "Accounts", "path": "/crm/accounts"},
+        {"title": "Contacts", "path": "/crm/contacts"},
+        {"title": "Deals", "path": "/crm/deals"},
+        {"title": "Health", "path": "/crm/health"},
+        {"title": "Activity", "path": "/crm/activity"}
+      ]
+    },
+    {
+      "title": "Support",
+      "path": "/support", 
+      "icon": "Headphones",
+      "order": 3
+    },
+    {
+      "title": "Community",
+      "path": "/community",
+      "icon": "Users", 
+      "order": 4
+    },
+    {
+      "title": "Knowledge Base",
+      "path": "/kb",
+      "icon": "BookOpen",
+      "order": 5
+    },
+    {
+      "title": "Courses",
+      "path": "/courses",
+      "icon": "GraduationCap",
+      "order": 6
+    },
+    {
+      "title": "Intelligence",
+      "path": "/intelligence",
+      "icon": "Brain",
+      "order": 7
+    }
+  ]',
+  '/cortex', -- Change to '/' for root serving
+  'custom',
+  now()
+);
+```
+
+### 2. App Installation
+
+Install Cortex for your account:
+
+```sql
+INSERT INTO public.app_installations (
+  account_id,
+  app_slug,
+  is_enabled
+) VALUES (
+  'your-account-id', -- Replace with your account ID
+  'cortex', 
+  true
+);
+```
+
+### 3. Required Roles
+
+Cortex requires users to have the `support` role. Create this role if it doesn't exist:
+
+```sql
+INSERT INTO public.roles (
+  slug,
+  name,
+  description,
+  is_system,
+  is_active
+) VALUES (
+  'support',
+  'Support Agent', 
+  'Can access Cortex support features',
+  false,
+  true
+) ON CONFLICT (slug) DO NOTHING;
+```
+
+Assign the support role to users who need Cortex access:
+
+```sql
+INSERT INTO public.people (
+  account_id,
+  user_id,
+  role_id,
+  is_active
+) VALUES (
+  'your-account-id',
+  'user-id',
+  (SELECT id FROM public.roles WHERE slug = 'support'),
+  true
+);
+```
+
+## Manifest Configuration
+
+The `manifest.json` file controls app behavior and routing:
+
+### Key Settings
+
+- **`required_roles`**: `["support"]` - Users must have support role
+- **`routes`**: Define all available routes in the app
+- **`nav_items`**: Navigation structure and icons
+- **`route_prefix`**: Where the app is served from
+
+### Route Prefix Configuration
+
+#### Subdirectory Serving (Default)
+```json
+{
+  "route_prefix": "/cortex"
+}
+```
+- App accessible at: `http://domain.com/cortex`
+- Safe for multi-app deployments
+- Default configuration
+
+#### Root Serving
+```json
+{
+  "route_prefix": "/"
+}
+```
+- App accessible at: `http://domain.com/`
+- Use for single-app deployments
+- Requires updating database `route_prefix` field
+
+### Prefix-Aware Routing
+
+Cortex uses prefix-aware routing that automatically adapts to the `route_prefix`:
+
+- Navigation links automatically include the base path
+- Route definitions work regardless of serving location
+- Breadcrumbs and redirects are prefix-aware
+
+No code changes needed when switching between subdirectory and root serving.
+
+## Deployment Options
+
+### Option 1: Subdirectory Deployment (Recommended)
+
+1. Set `route_prefix: "/cortex"` in database
+2. App available at `/cortex/*` URLs
+3. Multiple apps can coexist safely
+
+### Option 2: Root Deployment
+
+1. Set `route_prefix: "/"` in database  
+2. App available at root URLs (`/`, `/dashboard`, etc.)
+3. Use for dedicated Cortex deployments
+
+## Verification
+
+Test the configuration:
+
+1. Check `/api/apps?action=list` returns Cortex
+2. Navigate to the configured route prefix
+3. Verify navigation works correctly
+4. Confirm all pages load without errors
+
+## Troubleshooting
+
+- **404 errors**: Check `route_prefix` matches database entry
+- **Access denied**: Verify user has `support` role
+- **Navigation broken**: Ensure prefix-aware routing is enabled
+- **Missing pages**: Check all route components exist and export defaults

package/{index.tsx → custom/apps/cortex/index.tsx}

@@ -4,6 +4,7 @@ import { LoadingSpinner } from '@core/components/ui/LoadingSpinner'
 import { AppShell } from '@core/components/layout/AppShell'
 import { CortexSidebar } from './components/CortexSidebar'
 import { TooltipProvider } from '@core/components/ui/tooltip'
+import { useCurrentApp } from '@core/contexts/AppContext'
 
 const CortexDashboard = lazy(() => import('./pages/CortexDashboard'))
 
@@ -40,13 +41,21 @@ const Fallback = <div className="min-h-[400px] flex items-center justify-center"
 
 function CortexLayout() {
   const location = useLocation()
+  const app = useCurrentApp()
+
+  // Normalize route_prefix: '/' → '' so paths are /dashboard, /crm/accounts, etc.
+  const base = app.route_prefix === '/' ? '' : (app.route_prefix || '')
+  const prefixDepth = base.split('/').filter(Boolean).length
+
   const segments = location.pathname.split('/').filter(Boolean)
-  const breadcrumbs: { title: string; url?: string }[] = [{ title: 'Cortex', url: '/cortex/dashboard' }]
-  if (segments[1] && segments[1] !== 'dashboard') {
-    breadcrumbs.push({ title: segments[1].charAt(0).toUpperCase() + segments[1].slice(1) })
+  const appSegments = segments.slice(prefixDepth) // strips the prefix segments
+
+  const breadcrumbs: { title: string; url?: string }[] = [{ title: 'Cortex', url: `${base}/dashboard` }]
+  if (appSegments[0] && appSegments[0] !== 'dashboard') {
+    breadcrumbs.push({ title: appSegments[0].charAt(0).toUpperCase() + appSegments[0].slice(1) })
   }
-  if (segments[2]) {
-    breadcrumbs.push({ title: segments[2].charAt(0).toUpperCase() + segments[2].slice(1) })
+  if (appSegments[1]) {
+    breadcrumbs.push({ title: appSegments[1].charAt(0).toUpperCase() + appSegments[1].slice(1) })
   }
 
   return (

package/custom/apps/cortex/kb-ingestion.tsx

@@ -0,0 +1,217 @@
+import React, { useState } from 'react'
+import { useApi } from '../../../v2-core/src/hooks/useApi'
+import { Button } from '../../../v2-core/src/components/ui/button'
+import { Card, CardContent, CardDescription, CardHeader, CardTitle } from '../../../v2-core/src/components/ui/card'
+import { Progress } from '../../../v2-core/src/components/ui/progress'
+import { Alert, AlertDescription } from '../../../v2-core/src/components/ui/alert'
+import { Badge } from '../../../v2-core/src/components/ui/badge'
+
+interface IngestionResponse {
+  success: boolean
+  items_created: number
+  items_updated: number
+  embeddings_generated: number
+  errors: string[]
+  skipped: string[]
+}
+
+interface IngestionStats {
+  total: number
+  processed: number
+  created: number
+  updated: number
+  errors: number
+}
+
+export default function KBIngestion() {
+  const [isIngesting, setIsIngesting] = useState(false)
+  const [stats, setStats] = useState<IngestionStats | null>(null)
+  const [error, setError] = useState<string | null>(null)
+  const [logs, setLogs] = useState<string[]>([])
+  const apiFetch = useApi()
+
+  const addLog = (message: string) => {
+    const timestamp = new Date().toLocaleTimeString()
+    setLogs(prev => [...prev, `[${timestamp}] ${message}`])
+  }
+
+  const loadChunks = async (): Promise<any[]> => {
+    try {
+      const response = await fetch('/chunks.json')
+      if (!response.ok) {
+        throw new Error('Failed to load chunks file')
+      }
+      const data = await response.json()
+      return data.chunks || []
+    } catch (err) {
+      throw new Error(`Could not load chunks: ${err instanceof Error ? err.message : 'Unknown error'}`)
+    }
+  }
+
+  const ingestBatch = async (chunks: any[], batchSize = 10): Promise<IngestionResponse> => {
+    const response = await apiFetch('/.netlify/functions/custom_kb-ingestion', {
+      method: 'POST',
+      headers: {
+        'Content-Type': 'application/json',
+      },
+      body: JSON.stringify({
+        chunks,
+        force_update: false
+      })
+    })
+
+    if (!response.ok) {
+      const errorData = await response.json().catch(() => ({ error: 'Unknown error' }))
+      throw new Error(`Batch failed: ${errorData.error || response.statusText}`)
+    }
+
+    return await response.json()
+  }
+
+  const startIngestion = async () => {
+    setIsIngesting(true)
+    setError(null)
+    setStats(null)
+    setLogs([])
+
+    try {
+      addLog('Loading chunks from file...')
+      const chunks = await loadChunks()
+      addLog(`Loaded ${chunks.length} chunks`)
+
+      if (chunks.length === 0) {
+        throw new Error('No chunks found to ingest')
+      }
+
+      const results: IngestionStats = {
+        total: chunks.length,
+        processed: 0,
+        created: 0,
+        updated: 0,
+        errors: 0
+      }
+
+      const batchSize = 10
+      const totalBatches = Math.ceil(chunks.length / batchSize)
+
+      for (let i = 0; i < chunks.length; i += batchSize) {
+        const batch = chunks.slice(i, i + batchSize)
+        const batchNum = Math.floor(i / batchSize) + 1
+
+        addLog(`Processing batch ${batchNum}/${totalBatches} (${batch.length} chunks)...`)
+
+        try {
+          const response = await ingestBatch(batch)
+          
+          results.processed += batch.length
+          results.created += response.items_created || 0
+          results.updated += response.items_updated || 0
+
+          if (response.errors && response.errors.length > 0) {
+            results.errors += response.errors.length
+            addLog(`Batch ${batchNum} had ${response.errors.length} errors`)
+          }
+
+          if (response.skipped && response.skipped.length > 0) {
+            addLog(`Batch ${batchNum} skipped ${response.skipped.length} chunks`)
+          }
+
+          addLog(`Batch ${batchNum} complete: ${response.items_created || 0} created, ${response.items_updated || 0} updated`)
+
+          // Update progress
+          setStats({ ...results })
+          
+          // Small delay to prevent overwhelming the server
+          await new Promise(resolve => setTimeout(resolve, 500))
+
+        } catch (batchError) {
+          results.errors += batch.length
+          addLog(`Batch ${batchNum} failed: ${batchError instanceof Error ? batchError.message : 'Unknown error'}`)
+        }
+      }
+
+      addLog(`Ingestion complete! Created: ${results.created}, Updated: ${results.updated}, Errors: ${results.errors}`)
+      setStats(results)
+
+    } catch (err) {
+      const errorMessage = err instanceof Error ? err.message : 'Unknown error occurred'
+      setError(errorMessage)
+      addLog(`ERROR: ${errorMessage}`)
+    } finally {
+      setIsIngesting(false)
+    }
+  }
+
+  const progress = stats ? (stats.processed / stats.total) * 100 : 0
+
+  return (
+    <div className="max-w-4xl mx-auto p-6 space-y-6">
+      <Card>
+        <CardHeader>
+          <CardTitle>KB Code Chunk Ingestion</CardTitle>
+          <CardDescription>
+            Ingest parsed code chunks from v2-core functions into the Knowledge Base system.
+            This creates KB articles and embeddings for each code chunk.
+          </CardDescription>
+        </CardHeader>
+        <CardContent className="space-y-4">
+          <div className="flex items-center gap-4">
+            <Button 
+              onClick={startIngestion} 
+              disabled={isIngesting}
+              size="lg"
+            >
+              {isIngesting ? 'Ingesting...' : 'Start Ingestion'}
+            </Button>
+            
+            {stats && (
+              <div className="flex gap-2">
+                <Badge variant="outline">
+                  Total: {stats.total}
+                </Badge>
+                <Badge variant="outline">
+                  Created: {stats.created}
+                </Badge>
+                <Badge variant="outline">
+                  Updated: {stats.updated}
+                </Badge>
+                {stats.errors > 0 && (
+                  <Badge variant="destructive">
+                    Errors: {stats.errors}
+                  </Badge>
+                )}
+              </div>
+            )}
+          </div>
+
+          {isIngesting && (
+            <div className="space-y-2">
+              <div className="flex justify-between text-sm">
+                <span>Progress</span>
+                <span>{stats ? `${stats.processed}/${stats.total}` : 'Starting...'}</span>
+              </div>
+              <Progress value={progress} className="w-full" />
+            </div>
+          )}
+
+          {error && (
+            <Alert variant="destructive">
+              <AlertDescription>{error}</AlertDescription>
+            </Alert>
+          )}
+
+          {logs.length > 0 && (
+            <div className="space-y-2">
+              <h4 className="font-medium">Activity Log</h4>
+              <div className="bg-gray-50 dark:bg-gray-900 p-4 rounded-lg max-h-64 overflow-y-auto">
+                <pre className="text-xs font-mono whitespace-pre-wrap">
+                  {logs.join('\n')}
+                </pre>
+              </div>
+            </div>
+          )}
+        </CardContent>
+      </Card>
+    </div>
+  )
+}

package/{manifest.json → custom/apps/cortex/manifest.json}

@@ -5,7 +5,6 @@
   "version": "1.0.0",
   "required_roles": ["support"],
   "routes": [
-    "/cortex",
     "/cortex/dashboard",
     "/cortex/crm",
     "/cortex/crm/accounts",
@@ -75,6 +74,18 @@
       "order": 7
     }
   ],
+  "changelog": [
+    {
+      "version": "1.0.0",
+      "notes": [
+        "Root-relative nav paths for subdomain deployment model",
+        "Prefix-aware sidebar navigation via useCurrentApp()",
+        "Prefix-aware breadcrumbs with Navigate index redirect",
+        "FilterTab replaces FunnelTab (lucide Filter icon)",
+        "Initial release"
+      ]
+    }
+  ],
   "features": ["crm", "support", "community", "kb", "courses", "intelligence"],
   "dependencies": ["items", "accounts", "pipelines", "integrations"],
   "entry_point": "./index.tsx",

package/custom/apps/cortex/package.json

@@ -0,0 +1,31 @@
+{
+  "name": "spine-framework-cortex",
+  "version": "0.1.9",
+  "description": "Cortex — AI-powered support, CRM, and knowledge base app for Spine Framework",
+  "type": "module",
+  "license": "SEE LICENSE IN LICENSE.md",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/spine-framework/cortex",
+    "directory": "custom/apps/cortex"
+  },
+  "peerDependencies": {
+    "spine-framework": ">=0.1.0"
+  },
+  "files": [
+    "index.tsx",
+    "manifest.json",
+    "seed/",
+    "pages/",
+    "components/",
+    "functions/",
+    "lib/",
+    "README.md",
+    "LICENSE.md"
+  ],
+  "spine": {
+    "type": "app",
+    "slug": "cortex",
+    "manifestPath": "manifest.json"
+  }
+}

package/{pages → custom/apps/cortex/pages}/crm/AccountDetailPage.tsx

@@ -7,7 +7,7 @@ import { Skeleton } from '@core/components/ui/skeleton'
 import { Button } from '@core/components/ui/button'
 import { ScrollArea } from '@core/components/ui/scroll-area'
 import { Separator } from '@core/components/ui/separator'
-import { ArrowLeft, User, Ticket, Handshake, Activity, Heart, Funnel, TrendingUp, Target, Clock } from 'lucide-react'
+import { ArrowLeft, User, Ticket, Handshake, Activity, Heart, Filter, TrendingUp, Target, Clock } from 'lucide-react'
 
 interface Account {
   id: string
@@ -140,7 +140,7 @@ function ActivityTab({ accountId }: { accountId: string }) {
   )
 }
 
-function FunnelTab({ account }: { account: Account }) {
+function FilterTab({ account }: { account: Account }) {
   const stage = account.data?.lifecycle_stage
   const score = account.data?.lead_score ?? 0
   const temp = account.data?.temperature
@@ -217,7 +217,7 @@ function FunnelTab({ account }: { account: Account }) {
       {queue?.pending_opportunity_id && (
         <div className="border rounded-lg p-4 bg-yellow-50 border-yellow-200">
           <div className="flex items-center gap-2">
-            <Funnel className="h-4 w-4 text-yellow-600" />
+            <Filter className="h-4 w-4 text-yellow-600" />
             <span className="font-medium text-sm">Opportunity in Queue</span>
           </div>
           <p className="text-xs text-muted-foreground mt-1">
@@ -317,7 +317,7 @@ function FunnelTab({ account }: { account: Account }) {
       {/* Empty State */}
       {!stage && !score && !temp && !ratings && !queue?.pending_opportunity_id && (
         <div className="text-center py-12 text-muted-foreground">
-          <Funnel className="h-10 w-10 mx-auto mb-3 opacity-30" />
+          <Filter className="h-10 w-10 mx-auto mb-3 opacity-30" />
           <p className="text-sm">No funnel data yet.</p>
           <p className="text-xs mt-1">Signals will appear here as they are processed.</p>
         </div>
@@ -364,7 +364,7 @@ export default function AccountDetailPage() {
           <TabsList className="h-9 bg-transparent p-0 gap-4">
             {[
               { value: 'people', label: 'People', icon: User },
-              { value: 'funnel', label: 'Funnel', icon: Funnel },
+              { value: 'funnel', label: 'Funnel', icon: Filter },
               { value: 'tickets', label: 'Tickets', icon: Ticket },
               { value: 'deals', label: 'Deals', icon: Handshake },
               { value: 'health', label: 'Health', icon: Heart },
@@ -381,7 +381,7 @@ export default function AccountDetailPage() {
 
         <ScrollArea className="flex-1">
           <TabsContent value="people" className="mt-0"><PeopleTab accountId={id!} /></TabsContent>
-          <TabsContent value="funnel" className="mt-0"><FunnelTab account={account} /></TabsContent>
+          <TabsContent value="funnel" className="mt-0"><FilterTab account={account} /></TabsContent>
           <TabsContent value="tickets" className="mt-0"><ItemsTab accountId={id!} typeSlug="support_ticket" emptyText="No tickets." /></TabsContent>
           <TabsContent value="deals" className="mt-0"><ItemsTab accountId={id!} typeSlug="deal" emptyText="No deals." /></TabsContent>
           <TabsContent value="health" className="mt-0"><ItemsTab accountId={id!} typeSlug="csm_health" emptyText="No health records." /></TabsContent>