spine-framework 0.3.124 → 0.3.126

package/.framework/src/main.tsx

@@ -1,3 +1,21 @@
+
+
+
+// CIL[BEGIN chunk_id="main_module_header_1783672456" type="module_header" identity="imports" parent="none"]
+// CIL[DOC-MACRO purpose="Import React and app dependencies"]
+// CIL[DOC-RESPONSIBILITY responsibility="Import all required modules for app bootstrap"]
+// CIL[DOC-CONTEXT module="main" layer="frontend-entry" related_files="[\"custom/apps/portal/pages/ContentPage.tsx\",\"custom/apps/cortex/pages/operations/OperationsDashboard.tsx\",\".framework/migrations/015_simplify_apps_table.sql\",\"custom/apps/cortex/functions/custom_cil-embeddings.ts\",\"\\\"]"]
+// CIL[DOC-CONTRACT inputs="none" outputs="React components" errors="none" side_effects="none"]
+// CIL[DOC-MICRO logic_summary="Imports React, routing, state management, and app components" notable_decisions="[]"]
+// CIL[DOC-CONFIDENCE pass="second" score="0.95" flags="none"]
+// CIL[DOC-STABILITY stability="stable"]
+// CIL[DOC-AUDIENCE audience="developer"]
+// CIL[DOC-VECTOR type="context" content="Layer: frontend-entry. Direct callers: 0. Direct calls: 0. Related files: custom/apps/portal/pages/ContentPage.tsx, custom/apps/cortex/pages/operations/OperationsDashboard.tsx, .framework/migrations/015_simplify_apps_table.sql, custom/apps/cortex/functions/custom_cil-embeddings.ts, \."]
+// CIL[DOC-VECTOR type="blast_radius" content="Direct callers: 0. Total affected: 0."]
+// CIL[DOC-VECTOR type="configuration" content="No configuration dependencies."]
+// CIL[DOC-VECTOR type="constraint" content="No test paths identified."]
+// CIL[DOC-VECTOR type="implementation_pattern" content="" status="pending_human_input"]
+// CIL[DOC-VECTOR type="user_journey" content="" status="pending_human_input"]
 import React from 'react'
 import ReactDOM from 'react-dom/client'
 import { BrowserRouter } from 'react-router-dom'
@@ -5,8 +23,21 @@ import { QueryClient, QueryClientProvider } from '@tanstack/react-query'
 import App from './App'
 import { AuthProvider } from './contexts/AuthContext'
 import './index.css'
-
-// Create a client
+// CIL[END chunk_id="main_module_header_1783672456"]
+// CIL[BEGIN chunk_id="main_queryclient_1783672456" type="variable" identity="queryClient" parent="none"]
+// CIL[DOC-MACRO purpose="Configure React Query client"]
+// CIL[DOC-RESPONSIBILITY responsibility="Create and configure query client instance"]
+// CIL[DOC-CONTEXT module="main" layer="frontend-entry" related_files="[\"custom/apps/portal/pages/ContentPage.tsx\",\"custom/apps/cortex/pages/operations/OperationsDashboard.tsx\",\"\\\"]"]
+// CIL[DOC-CONTRACT inputs="none" outputs="QueryClient instance" errors="none" side_effects="none"]
+// CIL[DOC-MICRO logic_summary="Creates QueryClient with retry and refetch options" notable_decisions="[]"]
+// CIL[DOC-CONFIDENCE pass="second" score="0.95" flags="none"]
+// CIL[DOC-STABILITY stability="stable"]
+// CIL[DOC-VECTOR type="context" content="Layer: frontend-entry. Direct callers: 0. Direct calls: 0. Related files: custom/apps/portal/pages/ContentPage.tsx, custom/apps/cortex/pages/operations/OperationsDashboard.tsx, \."]
+// CIL[DOC-VECTOR type="blast_radius" content="Direct callers: 0. Total affected: 0."]
+// CIL[DOC-VECTOR type="configuration" content="No configuration dependencies."]
+// CIL[DOC-VECTOR type="constraint" content="No test paths identified."]
+// CIL[DOC-VECTOR type="implementation_pattern" content="" status="pending_human_input"]
+// CIL[DOC-VECTOR type="user_journey" content="" status="pending_human_input"]
 const queryClient = new QueryClient({
   defaultOptions: {
     queries: {
@@ -15,7 +46,21 @@ const queryClient = new QueryClient({
     },
   },
 })
-
+// CIL[END chunk_id="main_queryclient_1783672456"]
+// CIL[BEGIN chunk_id="main_render_1783672456" type="function" identity="render" parent="none"]
+// CIL[DOC-MACRO purpose="Render React app to DOM"]
+// CIL[DOC-RESPONSIBILITY responsibility="Bootstrap React application"]
+// CIL[DOC-CONTEXT module="main" layer="frontend-entry" related_files="[\"custom/apps/portal/pages/ContentPage.tsx\",\"custom/apps/cortex/functions/custom_cil-embeddings.ts\",\"custom/apps/cortex/pages/operations/OperationsDashboard.tsx\",\".framework/migrations/015_simplify_apps_table.sql\",\"\\\"]"]
+// CIL[DOC-CONTRACT inputs="none" outputs="DOM render" errors="none" side_effects="DOM manipulation"]
+// CIL[DOC-MICRO logic_summary="Creates root and renders app with providers" notable_decisions="[]"]
+// CIL[DOC-CONFIDENCE pass="second" score="0.95" flags="none"]
+// CIL[DOC-STABILITY stability="stable"]
+// CIL[DOC-VECTOR type="context" content="Layer: frontend-entry. Direct callers: 2. Direct calls: 0. Related files: custom/apps/portal/pages/ContentPage.tsx, custom/apps/cortex/functions/custom_cil-embeddings.ts, custom/apps/cortex/pages/operations/OperationsDashboard.tsx, .framework/migrations/015_simplify_apps_table.sql, \."]
+// CIL[DOC-VECTOR type="blast_radius" content="Direct callers: 2. Total affected: 2."]
+// CIL[DOC-VECTOR type="configuration" content="No configuration dependencies."]
+// CIL[DOC-VECTOR type="constraint" content="No test paths identified."]
+// CIL[DOC-VECTOR type="implementation_pattern" content="" status="pending_human_input"]
+// CIL[DOC-VECTOR type="user_journey" content="" status="pending_human_input"]
 ReactDOM.createRoot(document.getElementById('root')!).render(
   <QueryClientProvider client={queryClient}>
     <BrowserRouter>
@@ -25,3 +70,4 @@ ReactDOM.createRoot(document.getElementById('root')!).render(
     </BrowserRouter>
   </QueryClientProvider>,
 )
+// CIL[END chunk_id="main_render_1783672456"]

package/.framework/src/pages/DashboardPage.tsx

@@ -1,36 +1,63 @@
-/**
- * @module src/pages/DashboardPage
- * @audience installer
- * @layer frontend-page
- * @stability stable
- *
- * Admin home page. On mount, fetches all active item types (`kind=item`)
- * from `/api/types` and then fans out parallel requests to
- * `/api/admin-data?action=stats&entity=items&type_slug=…` to collect
- * per-type item counts (capped at 8 types). Renders:
- * - **Entity overview grid** — one stat card per type + a "Configuration"
- *   shortcut card
- * - **Quick Actions row** — "New <Type>" buttons for the first 4 types plus
- *   a "Configure Types" shortcut
- *
- * @seeAlso src/contexts/AuthContext.tsx (provides current user)
- * @seeAlso src/lib/api.ts (apiFetch)
- */
 
+
+
+// CIL[BEGIN chunk_id="dashboardpage_module_header_1783672456" type="module_header" identity="imports" parent="none"]
+// CIL[DOC-MACRO purpose="Import React and dashboard dependencies"]
+// CIL[DOC-RESPONSIBILITY responsibility="Import dashboard components and hooks"]
+// CIL[DOC-CONTEXT module="DashboardPage" layer="frontend-page" related_files="[\"custom/apps/cortex/pages/operations/OperationsDashboard.tsx\",\"custom/apps/portal/pages/ContentPage.tsx\",\".framework/src/components/ui/dialog.tsx\",\".framework/src/pages/admin/RolesPage.tsx\",\".framework/functions/_shared/principal.ts\",\"\\\"]"]
+// CIL[DOC-CONTRACT inputs="none" outputs="React hooks and components" errors="none" side_effects="none"]
+// CIL[DOC-MICRO logic_summary="Imports React, hooks, routing, and icons" notable_decisions="[]"]
+// CIL[DOC-CONFIDENCE pass="second" score="0.95" flags="none"]
+// CIL[DOC-STABILITY stability="stable"]
+// CIL[DOC-AUDIENCE audience="developer"]
+// CIL[DOC-VECTOR type="context" content="Layer: frontend-page. Direct callers: 0. Direct calls: 0. Related files: custom/apps/cortex/pages/operations/OperationsDashboard.tsx, custom/apps/portal/pages/ContentPage.tsx, .framework/src/components/ui/dialog.tsx, .framework/src/pages/admin/RolesPage.tsx, .framework/functions/_shared/principal.ts, \."]
+// CIL[DOC-VECTOR type="blast_radius" content="Direct callers: 0. Total affected: 0."]
+// CIL[DOC-VECTOR type="configuration" content="No configuration dependencies."]
+// CIL[DOC-VECTOR type="constraint" content="No test paths identified."]
+// CIL[DOC-VECTOR type="implementation_pattern" content="" status="pending_human_input"]
+// CIL[DOC-VECTOR type="user_journey" content="" status="pending_human_input"]
 import React, { useState, useEffect } from 'react'
 import { useAuth } from '../contexts/AuthContext'
 import { useApi } from '../hooks/useApi'
 import { apiFetch } from '../lib/api'
 import { useNavigate } from 'react-router-dom'
-import { Box, UserGroupIcon, FileText, BarChart3, Settings, Plus } from 'lucide-react';
-
+import { Box, UserGroupIcon, FileText, BarChart3, Settings, Plus, CubeIcon } from 'lucide-react';
+// CIL[END chunk_id="dashboardpage_module_header_1783672456"]
+// CIL[BEGIN chunk_id="dashboardpage_typestat_1783672456" type="interface" identity="TypeStat" parent="none"]
+// CIL[DOC-MACRO purpose="Define type statistics interface"]
+// CIL[DOC-RESPONSIBILITY responsibility="Type definition for dashboard stats"]
+// CIL[DOC-CONTEXT module="DashboardPage" layer="frontend-page" related_files="[\".framework/functions/_shared/schema-utils.ts\",\".framework/src/pages/admin/TypeDetailPage.tsx\",\".framework/functions/_shared/db.ts\",\"custom/apps/cortex/pages/operations/OperationsDashboard.tsx\",\".framework/src/pages/admin/IntegrationsPage.tsx\",\"\\\"]"]
+// CIL[DOC-CONTRACT inputs="none" outputs="Type definition" errors="none" side_effects="none"]
+// CIL[DOC-MICRO logic_summary="Interface for entity type statistics" notable_decisions="[]"]
+// CIL[DOC-CONFIDENCE pass="second" score="0.95" flags="none"]
+// CIL[DOC-STABILITY stability="stable"]
+// CIL[DOC-VECTOR type="context" content="Layer: frontend-page. Direct callers: 0. Direct calls: 0. Related files: .framework/functions/_shared/schema-utils.ts, .framework/src/pages/admin/TypeDetailPage.tsx, .framework/functions/_shared/db.ts, custom/apps/cortex/pages/operations/OperationsDashboard.tsx, .framework/src/pages/admin/IntegrationsPage.tsx, \."]
+// CIL[DOC-VECTOR type="blast_radius" content="Direct callers: 0. Total affected: 0."]
+// CIL[DOC-VECTOR type="configuration" content="No configuration dependencies."]
+// CIL[DOC-VECTOR type="constraint" content="No test paths identified."]
+// CIL[DOC-VECTOR type="implementation_pattern" content="" status="pending_human_input"]
+// CIL[DOC-VECTOR type="user_journey" content="" status="pending_human_input"]
 interface TypeStat {
   name: string
   count: number
   slug: string
   icon: any
 }
-
+// CIL[END chunk_id="dashboardpage_typestat_1783672456"]
+// CIL[BEGIN chunk_id="dashboardpage_dashboardpage_1783672456" type="function" identity="DashboardPage" parent="none"]
+// CIL[DOC-MACRO purpose="Render admin dashboard"]
+// CIL[DOC-RESPONSIBILITY responsibility="Display entity overview and quick actions"]
+// CIL[DOC-CONTEXT module="DashboardPage" layer="frontend-page" related_files="[\".framework/src/pages/admin/RolesPage.tsx\",\"custom/apps/cortex/pages/operations/OperationsDashboard.tsx\",\".framework/src/pages/admin/TypeDetailPage.tsx\",\".framework/src/pages/admin/IntegrationsPage.tsx\",\"custom/apps/portal/pages/ContentPage.tsx\",\"\\\"]"]
+// CIL[DOC-CONTRACT inputs="none" outputs="Dashboard JSX" errors="Network errors" side_effects="API calls, navigation"]
+// CIL[DOC-MICRO logic_summary="Fetches type stats, displays overview cards and actions" notable_decisions="[]"]
+// CIL[DOC-CONFIDENCE pass="second" score="0.95" flags="none"]
+// CIL[DOC-STABILITY stability="stable"]
+// CIL[DOC-VECTOR type="context" content="Layer: frontend-page. Direct callers: 0. Direct calls: 0. Related files: .framework/src/pages/admin/RolesPage.tsx, custom/apps/cortex/pages/operations/OperationsDashboard.tsx, .framework/src/pages/admin/TypeDetailPage.tsx, .framework/src/pages/admin/IntegrationsPage.tsx, custom/apps/portal/pages/ContentPage.tsx, \."]
+// CIL[DOC-VECTOR type="blast_radius" content="Direct callers: 0. Total affected: 0."]
+// CIL[DOC-VECTOR type="configuration" content="No configuration dependencies."]
+// CIL[DOC-VECTOR type="constraint" content="No test paths identified."]
+// CIL[DOC-VECTOR type="implementation_pattern" content="" status="pending_human_input"]
+// CIL[DOC-VECTOR type="user_journey" content="" status="pending_human_input"]
 export function DashboardPage() {
   const { user } = useAuth()
   const navigate = useNavigate()
@@ -47,11 +74,10 @@ export function DashboardPage() {
   useEffect(() => {
     const fetchStats = async () => {
       try {
-        // Fetch active types with their counts
         const typesResponse = await apiFetch('/api/types?kind=item&is_active=true')
         if (typesResponse.ok) {
           const response = await typesResponse.json()
-          const types = response.data || response // Handle both wrapped and unwrapped responses
+          const types = response.data || response
           
           if (!Array.isArray(types)) {
             console.error('Expected array of types, got:', types)
@@ -59,7 +85,6 @@ export function DashboardPage() {
             return
           }
           
-          // Get counts for each type
           const statsPromises = types.map(async (type: any) => {
             const countResponse = await apiFetch(`/api/admin-data?action=stats&entity=items&type_slug=${type.slug}`)
             if (countResponse.ok) {
@@ -68,14 +93,14 @@ export function DashboardPage() {
                 name: type.name,
                 count: countData.count || 0,
                 slug: type.slug,
-                icon: CubeIcon // Default icon, could be enhanced to use type.icon
+                icon: CubeIcon
               }
             }
             return null
           })
           
           const resolvedStats = await Promise.all(statsPromises)
-          const validStats = resolvedStats.filter((s): s is NonNullable<typeof s> => s !== null).slice(0, 8) // Limit to 8 types
+          const validStats = resolvedStats.filter((s): s is NonNullable<typeof s> => s !== null).slice(0, 8)
           setTypeStats(validStats)
         }
       } catch (error) {
@@ -106,7 +131,6 @@ export function DashboardPage() {
 
   return (
     <div className="space-y-6">
-      {/* Type Stats */}
       <div>
         <h2 className="text-lg font-semibold text-slate-900 mb-4">Entity Overview</h2>
         <div className="grid grid-cols-1 gap-4 sm:grid-cols-2 lg:grid-cols-4">
@@ -131,7 +155,6 @@ export function DashboardPage() {
             )
           })}
           
-          {/* Quick Actions Card */}
           <div
             className="rounded-xl border border-slate-200 bg-white p-5 hover:shadow-md transition-shadow cursor-pointer"
             onClick={() => navigate('/spine-framework/admin/configs/types')}
@@ -149,7 +172,6 @@ export function DashboardPage() {
         </div>
       </div>
 
-      {/* Quick Actions */}
       <div className="rounded-xl border border-slate-200 bg-white p-6">
         <h3 className="text-sm font-semibold text-slate-900 mb-4">
           Quick Actions
@@ -179,3 +201,4 @@ export function DashboardPage() {
     </div>
   )
 }
+// CIL[END chunk_id="dashboardpage_dashboardpage_1783672456"]

package/.framework/src/pages/NotFoundPage.tsx

@@ -1,17 +1,38 @@
-/**
- * @module src/pages/NotFoundPage
- * @audience installer
- * @layer frontend-page
- * @stability stable
- *
- * Generic 404 page rendered by the catch-all route. Displays a large
- * "404" heading and a link back to the sign-in page.
- */
 
+
+// CIL[BEGIN chunk_id="notfoundpage_module_header_1783672456" type="module_header" identity="imports" parent="none"]
+// CIL[DOC-MACRO purpose="Import React and components"]
+// CIL[DOC-RESPONSIBILITY responsibility="Import required dependencies"]
+// CIL[DOC-CONTEXT module="NotFoundPage" layer="frontend-page" related_files="[\"custom/apps/portal/pages/ContentPage.tsx\",\"custom/apps/cortex/pages/operations/OperationsDashboard.tsx\",\".framework/src/components/ui/dialog.tsx\",\".framework/src/components/ui/table-primitives.tsx\",\"\\\"]"]
+// CIL[DOC-CONTRACT inputs="none" outputs="React components" errors="none" side_effects="none"]
+// CIL[DOC-MICRO logic_summary="Imports React, Link, and Home icon" notable_decisions="[]"]
+// CIL[DOC-CONFIDENCE pass="second" score="0.95" flags="none"]
+// CIL[DOC-STABILITY stability="stable"]
+// CIL[DOC-AUDIENCE audience="developer"]
+// CIL[DOC-VECTOR type="context" content="Layer: frontend-page. Direct callers: 0. Direct calls: 0. Related files: custom/apps/portal/pages/ContentPage.tsx, custom/apps/cortex/pages/operations/OperationsDashboard.tsx, .framework/src/components/ui/dialog.tsx, .framework/src/components/ui/table-primitives.tsx, \."]
+// CIL[DOC-VECTOR type="blast_radius" content="Direct callers: 0. Total affected: 0."]
+// CIL[DOC-VECTOR type="configuration" content="No configuration dependencies."]
+// CIL[DOC-VECTOR type="constraint" content="No test paths identified."]
+// CIL[DOC-VECTOR type="implementation_pattern" content="" status="pending_human_input"]
+// CIL[DOC-VECTOR type="user_journey" content="" status="pending_human_input"]
 import React from 'react'
 import { Link } from 'react-router-dom'
 import { Home } from 'lucide-react';
-
+// CIL[END chunk_id="notfoundpage_module_header_1783672456"]
+// CIL[BEGIN chunk_id="notfoundpage_notfoundpage_1783672456" type="function" identity="NotFoundPage" parent="none"]
+// CIL[DOC-MACRO purpose="Render 404 error page"]
+// CIL[DOC-RESPONSIBILITY responsibility="Display not found error with navigation"]
+// CIL[DOC-CONTEXT module="NotFoundPage" layer="frontend-page" related_files="[\"custom/apps/portal/pages/ContentPage.tsx\",\"custom/apps/cortex/pages/operations/OperationsDashboard.tsx\",\".framework/src/pages/admin/TypeDetailPage.tsx\",\".framework/src/pages/admin/RolesPage.tsx\",\".framework/src/pages/admin/IntegrationsPage.tsx\",\"\\\"]"]
+// CIL[DOC-CONTRACT inputs="none" outputs="404 page JSX" errors="none" side_effects="none"]
+// CIL[DOC-MICRO logic_summary="Shows 404 message and login link" notable_decisions="[]"]
+// CIL[DOC-CONFIDENCE pass="second" score="0.95" flags="none"]
+// CIL[DOC-STABILITY stability="stable"]
+// CIL[DOC-VECTOR type="context" content="Layer: frontend-page. Direct callers: 0. Direct calls: 0. Related files: custom/apps/portal/pages/ContentPage.tsx, custom/apps/cortex/pages/operations/OperationsDashboard.tsx, .framework/src/pages/admin/TypeDetailPage.tsx, .framework/src/pages/admin/RolesPage.tsx, .framework/src/pages/admin/IntegrationsPage.tsx, \."]
+// CIL[DOC-VECTOR type="blast_radius" content="Direct callers: 0. Total affected: 0."]
+// CIL[DOC-VECTOR type="configuration" content="No configuration dependencies."]
+// CIL[DOC-VECTOR type="constraint" content="No test paths identified."]
+// CIL[DOC-VECTOR type="implementation_pattern" content="" status="pending_human_input"]
+// CIL[DOC-VECTOR type="user_journey" content="" status="pending_human_input"]
 export function NotFoundPage() {
   return (
     <div className="min-h-screen bg-slate-50 flex flex-col justify-center py-12 sm:px-6 lg:px-8">
@@ -37,3 +58,4 @@ export function NotFoundPage() {
     </div>
   )
 }
+// CIL[END chunk_id="notfoundpage_notfoundpage_1783672456"]

package/.framework/src/pages/SetupPage.tsx

@@ -1,18 +1,37 @@
-/**
- * @module src/pages/SetupPage
- * @audience installer
- * @layer frontend-page
- * @stability stable
- *
- * Shown at the root path when no apps are installed or no users have been
- * created yet. Guides the developer through the initial setup steps.
- * Replaces the old /dashboard fallback — the framework has no opinion
- * about what lives at / once apps are installed.
- */
 
+
+// CIL[BEGIN chunk_id="setuppage_module_header_1783672456" type="module_header" identity="imports" parent="none"]
+// CIL[DOC-MACRO purpose="Import React and routing"]
+// CIL[DOC-RESPONSIBILITY responsibility="Import required components"]
+// CIL[DOC-CONTEXT module="SetupPage" layer="frontend-page" related_files="[\"custom/apps/portal/pages/ContentPage.tsx\",\"custom/apps/cortex/pages/operations/OperationsDashboard.tsx\",\".framework/src/components/ui/dialog.tsx\",\".framework/src/pages/admin/RolesPage.tsx\",\".framework/functions/_shared/principal.ts\",\"\\\"]"]
+// CIL[DOC-CONTRACT inputs="none" outputs="React components" errors="none" side_effects="none"]
+// CIL[DOC-MICRO logic_summary="Imports React and Link for setup page" notable_decisions="[]"]
+// CIL[DOC-CONFIDENCE pass="second" score="0.95" flags="none"]
+// CIL[DOC-STABILITY stability="stable"]
+// CIL[DOC-AUDIENCE audience="developer"]
+// CIL[DOC-VECTOR type="context" content="Layer: frontend-page. Direct callers: 0. Direct calls: 0. Related files: custom/apps/portal/pages/ContentPage.tsx, custom/apps/cortex/pages/operations/OperationsDashboard.tsx, .framework/src/components/ui/dialog.tsx, .framework/src/pages/admin/RolesPage.tsx, .framework/functions/_shared/principal.ts, \."]
+// CIL[DOC-VECTOR type="blast_radius" content="Direct callers: 0. Total affected: 0."]
+// CIL[DOC-VECTOR type="configuration" content="No configuration dependencies."]
+// CIL[DOC-VECTOR type="constraint" content="No test paths identified."]
+// CIL[DOC-VECTOR type="implementation_pattern" content="" status="pending_human_input"]
+// CIL[DOC-VECTOR type="user_journey" content="" status="pending_human_input"]
 import React from 'react'
 import { Link } from 'react-router-dom'
-
+// CIL[END chunk_id="setuppage_module_header_1783672456"]
+// CIL[BEGIN chunk_id="setuppage_setuppage_1783672456" type="function" identity="SetupPage" parent="none"]
+// CIL[DOC-MACRO purpose="Render setup instructions page"]
+// CIL[DOC-RESPONSIBILITY responsibility="Show initial setup guide"]
+// CIL[DOC-CONTEXT module="SetupPage" layer="frontend-page" related_files="[\"custom/apps/portal/pages/ContentPage.tsx\",\"custom/apps/cortex/pages/operations/OperationsDashboard.tsx\",\".framework/src/pages/admin/TypeDetailPage.tsx\",\".framework/src/pages/admin/RolesPage.tsx\",\".framework/src/pages/admin/IntegrationsPage.tsx\",\"\\\"]"]
+// CIL[DOC-CONTRACT inputs="none" outputs="Setup page JSX" errors="none" side_effects="none"]
+// CIL[DOC-MICRO logic_summary="Displays setup steps and login link" notable_decisions="[]"]
+// CIL[DOC-CONFIDENCE pass="second" score="0.95" flags="none"]
+// CIL[DOC-STABILITY stability="stable"]
+// CIL[DOC-VECTOR type="context" content="Layer: frontend-page. Direct callers: 0. Direct calls: 0. Related files: custom/apps/portal/pages/ContentPage.tsx, custom/apps/cortex/pages/operations/OperationsDashboard.tsx, .framework/src/pages/admin/TypeDetailPage.tsx, .framework/src/pages/admin/RolesPage.tsx, .framework/src/pages/admin/IntegrationsPage.tsx, \."]
+// CIL[DOC-VECTOR type="blast_radius" content="Direct callers: 0. Total affected: 0."]
+// CIL[DOC-VECTOR type="configuration" content="No configuration dependencies."]
+// CIL[DOC-VECTOR type="constraint" content="No test paths identified."]
+// CIL[DOC-VECTOR type="implementation_pattern" content="" status="pending_human_input"]
+// CIL[DOC-VECTOR type="user_journey" content="" status="pending_human_input"]
 export function SetupPage() {
   return (
     <div className="min-h-screen flex items-center justify-center bg-slate-50 py-12 px-4 sm:px-6 lg:px-8">
@@ -64,3 +83,4 @@ export function SetupPage() {
     </div>
   )
 }
+// CIL[END chunk_id="setuppage_setuppage_1783672456"]

package/.framework/src/pages/admin/AIAgentDetailPage.tsx

@@ -1,6 +1,22 @@
-/**
- * @module src/pages/admin/AIAgentDetailPage
- */
+
+
+
+
+// CIL[BEGIN chunk_id="aiagentdetailpage_module_header_1783668265" type="module_header" identity="module_header" parent="none"]
+// CIL[DOC-MACRO purpose="Import dependencies for AIAgentDetailPage component"]
+// CIL[DOC-RESPONSIBILITY responsibility="Import React hooks, routing, API hooks, and UI components"]
+// CIL[DOC-CONTEXT module="AIAgentDetailPage" layer="presentation" related_files="[\".framework/src/components/ui/dialog.tsx\",\"custom/apps/cortex/pages/operations/OperationsDashboard.tsx\",\"custom/apps/portal/pages/ContentPage.tsx\",\".framework/src/pages/admin/TypeDetailPage.tsx\",\".framework/src/pages/admin/RolesPage.tsx\",\"\\\"]"]
+// CIL[DOC-CONTRACT inputs="none" outputs="Imported modules" errors="none" side_effects="none"]
+// CIL[DOC-MICRO logic_summary="Imports React state management, routing, API hooks, UI components" notable_decisions="[]"]
+// CIL[DOC-CONFIDENCE pass="second" score="0.95" flags="none"]
+// CIL[DOC-STABILITY stability="stable"]
+// CIL[DOC-AUDIENCE audience="developer"]
+// CIL[DOC-VECTOR type="context" content="Layer: presentation. Direct callers: 0. Direct calls: 0. Related files: .framework/src/components/ui/dialog.tsx, custom/apps/cortex/pages/operations/OperationsDashboard.tsx, custom/apps/portal/pages/ContentPage.tsx, .framework/src/pages/admin/TypeDetailPage.tsx, .framework/src/pages/admin/RolesPage.tsx, \."]
+// CIL[DOC-VECTOR type="blast_radius" content="Direct callers: 0. Total affected: 0."]
+// CIL[DOC-VECTOR type="configuration" content="No configuration dependencies."]
+// CIL[DOC-VECTOR type="constraint" content="No test paths identified."]
+// CIL[DOC-VECTOR type="implementation_pattern" content="" status="pending_human_input"]
+// CIL[DOC-VECTOR type="user_journey" content="" status="pending_human_input"]
 import { useState, useEffect } from 'react'
 import { useParams, useNavigate } from 'react-router-dom'
 import { useApi } from '../../hooks/useApi'
@@ -15,29 +31,74 @@ import { Card, CardContent, CardHeader, CardTitle } from '../../components/ui/ca
 import { Skeleton } from '../../components/ui/skeleton'
 import { Alert, AlertDescription, AlertTitle } from '../../components/ui/alert'
 import { ArrowLeft, Bot, AlertCircle } from 'lucide-react'
-
+import { PageInstructions } from '../../components/admin/PageInstructions'
+// CIL[END chunk_id="aiagentdetailpage_module_header_1783668265"]
+// CIL[BEGIN chunk_id="aiagentdetailpage_interface_aiagent_1783668265" type="interface" identity="AIAgent" parent="none"]
+// CIL[DOC-MACRO purpose="Define AIAgent data structure"]
+// CIL[DOC-RESPONSIBILITY responsibility="Type definition for AI agent objects"]
+// CIL[DOC-CONTEXT module="AIAgentDetailPage" layer="types" related_files="[\".framework/src/pages/admin/IntegrationsPage.tsx\",\".framework/functions/_shared/schema-utils.ts\",\".framework/functions/_shared/principal.ts\",\"custom/apps/cortex/functions/custom_cil-embeddings.ts\",\"\\\"]"]
+// CIL[DOC-CONTRACT inputs="none" outputs="AIAgent interface type" errors="none" side_effects="none"]
+// CIL[DOC-MICRO logic_summary="Defines complete AI agent structure with model config and capabilities" notable_decisions="[]"]
+// CIL[DOC-CONFIDENCE pass="second" score="0.95" flags="none"]
+// CIL[DOC-STABILITY stability="stable"]
+// CIL[DOC-VECTOR type="context" content="Layer: types. Direct callers: 0. Direct calls: 0. Related files: .framework/src/pages/admin/IntegrationsPage.tsx, .framework/functions/_shared/schema-utils.ts, .framework/functions/_shared/principal.ts, custom/apps/cortex/functions/custom_cil-embeddings.ts, \."]
+// CIL[DOC-VECTOR type="blast_radius" content="Direct callers: 0. Total affected: 0."]
+// CIL[DOC-VECTOR type="configuration" content="No configuration dependencies."]
+// CIL[DOC-VECTOR type="constraint" content="No test paths identified."]
+// CIL[DOC-VECTOR type="implementation_pattern" content="" status="pending_human_input"]
+// CIL[DOC-VECTOR type="user_journey" content="" status="pending_human_input"]
 interface AIAgent {
   id: string
   name: string
   description?: string
+  app_id?: string
   agent_type: 'chat' | 'analysis' | 'automation' | 'custom'
   model_config: { model: string; max_tokens?: number; temperature?: number }
   system_prompt: string
   tools: string[]
   capabilities?: Record<string, any>
   constraints?: Record<string, any>
+  metadata?: Record<string, any>
   is_active: boolean
   created_at: string
   updated_at: string
 }
-
+// CIL[END chunk_id="aiagentdetailpage_interface_aiagent_1783668265"]
+// CIL[BEGIN chunk_id="aiagentdetailpage_constant_agent_types_1783668265" type="constant" identity="AGENT_TYPES" parent="none"]
+// CIL[DOC-MACRO purpose="Define AI agent type options"]
+// CIL[DOC-RESPONSIBILITY responsibility="Configure available agent type choices"]
+// CIL[DOC-CONTEXT module="AIAgentDetailPage" layer="constants" related_files="[\".framework/src/pages/admin/TypeDetailPage.tsx\",\".framework/migrations/025_retype_threads_messages.sql\",\".framework/functions/_shared/schema-utils.ts\",\"custom/apps/cortex/pages/operations/OperationsDashboard.tsx\",\".framework/src/pages/admin/IntegrationsPage.tsx\",\"\\\"]"]
+// CIL[DOC-CONTRACT inputs="none" outputs="Agent type options" errors="none" side_effects="none"]
+// CIL[DOC-MICRO logic_summary="Defines chat, analysis, automation, and custom agent types" notable_decisions="[]"]
+// CIL[DOC-CONFIDENCE pass="second" score="0.95" flags="none"]
+// CIL[DOC-STABILITY stability="stable"]
+// CIL[DOC-VECTOR type="context" content="Layer: constants. Direct callers: 0. Direct calls: 0. Related files: .framework/src/pages/admin/TypeDetailPage.tsx, .framework/migrations/025_retype_threads_messages.sql, .framework/functions/_shared/schema-utils.ts, custom/apps/cortex/pages/operations/OperationsDashboard.tsx, .framework/src/pages/admin/IntegrationsPage.tsx, \."]
+// CIL[DOC-VECTOR type="blast_radius" content="Direct callers: 0. Total affected: 0."]
+// CIL[DOC-VECTOR type="configuration" content="No configuration dependencies."]
+// CIL[DOC-VECTOR type="constraint" content="No test paths identified."]
+// CIL[DOC-VECTOR type="implementation_pattern" content="" status="pending_human_input"]
+// CIL[DOC-VECTOR type="user_journey" content="" status="pending_human_input"]
 const AGENT_TYPES = [
   { value: 'chat', label: 'Chat' },
   { value: 'analysis', label: 'Analysis' },
   { value: 'automation', label: 'Automation' },
   { value: 'custom', label: 'Custom' }
 ]
-
+// CIL[END chunk_id="aiagentdetailpage_constant_agent_types_1783668265"]
+// CIL[BEGIN chunk_id="aiagentdetailpage_function_aiagentdetailpage_1783668265" type="function" identity="AIAgentDetailPage" parent="none"]
+// CIL[DOC-MACRO purpose="Main AIAgentDetailPage component implementation"]
+// CIL[DOC-RESPONSIBILITY responsibility="Render AI agent detail view with create/edit functionality"]
+// CIL[DOC-CONTEXT module="AIAgentDetailPage" layer="presentation" related_files="[\".framework/src/components/ui/dialog.tsx\",\"custom/apps/portal/pages/ContentPage.tsx\",\".framework/src/pages/admin/RolesPage.tsx\",\"\\\"]"]
+// CIL[DOC-CONTRACT inputs="none" outputs="React component" errors="API failures" side_effects="Navigation, API calls"]
+// CIL[DOC-MICRO logic_summary="Manages CRUD operations for AI agents with form validation and state management" notable_decisions="[]"]
+// CIL[DOC-CONFIDENCE pass="second" score="0.95" flags="none"]
+// CIL[DOC-STABILITY stability="stable"]
+// CIL[DOC-VECTOR type="context" content="Layer: presentation. Direct callers: 0. Direct calls: 0. Related files: .framework/src/components/ui/dialog.tsx, custom/apps/portal/pages/ContentPage.tsx, .framework/src/pages/admin/RolesPage.tsx, \."]
+// CIL[DOC-VECTOR type="blast_radius" content="Direct callers: 0. Total affected: 0."]
+// CIL[DOC-VECTOR type="configuration" content="No configuration dependencies."]
+// CIL[DOC-VECTOR type="constraint" content="No test paths identified."]
+// CIL[DOC-VECTOR type="implementation_pattern" content="" status="pending_human_input"]
+// CIL[DOC-VECTOR type="user_journey" content="" status="pending_human_input"]
 export function AIAgentDetailPage() {
   const { id } = useParams<{ id: string }>()
   const navigate = useNavigate()
@@ -48,9 +109,9 @@ export function AIAgentDetailPage() {
   const { data: agent, loading, error } = useApi<AIAgent>(
     async () => {
       if (isCreateMode) return {
-        id: '', name: '', description: '', agent_type: 'chat' as const,
+        id: '', name: '', description: '', app_id: '', agent_type: 'chat' as const,
         model_config: { model: 'gpt-4', max_tokens: 2048, temperature: 0.7 },
-        system_prompt: '', tools: [], capabilities: {}, constraints: {},
+        system_prompt: '', tools: [], capabilities: {}, constraints: {}, metadata: {},
         is_active: true, created_at: new Date().toISOString(), updated_at: new Date().toISOString()
       }
       const response = await apiFetch(`/api/ai-agents?method=GET&id=${id}`)
@@ -64,11 +125,12 @@ export function AIAgentDetailPage() {
   useEffect(() => {
     if (agent) {
       setEditData({
-        name: agent.name, description: agent.description || '', agent_type: agent.agent_type,
+        name: agent.name, description: agent.description || '', app_id: agent.app_id || '', agent_type: agent.agent_type,
         model_config: agent.model_config || { model: 'gpt-4', max_tokens: 2048, temperature: 0.7 },
         system_prompt: agent.system_prompt || '', tools: (agent.tools || []).join('\n'),
         capabilities: JSON.stringify(agent.capabilities || {}, null, 2),
         constraints: JSON.stringify(agent.constraints || {}, null, 2),
+        metadata: JSON.stringify(agent.metadata || {}, null, 2),
         is_active: agent.is_active
       })
     }
@@ -78,9 +140,11 @@ export function AIAgentDetailPage() {
     try {
       const payload = {
         ...editData,
+        app_id: editData.app_id || null,
         tools: editData.tools?.split('\n').filter(Boolean) || [],
         capabilities: JSON.parse(editData.capabilities || '{}'),
-        constraints: JSON.parse(editData.constraints || '{}')
+        constraints: JSON.parse(editData.constraints || '{}'),
+        metadata: JSON.parse(editData.metadata || '{}')
       }
       const url = isCreateMode ? '/api/ai-agents' : `/api/ai-agents?id=${id}`
       const response = await apiFetch(url, {
@@ -115,6 +179,48 @@ export function AIAgentDetailPage() {
         <h1 className="text-2xl font-bold">{isCreateMode ? 'Create AI Agent' : agent?.name}</h1>
       </div>
       
+      <PageInstructions
+        description="Configure an AI agent with a model, system prompt, and tools."
+        sections={[
+          { title: 'What this AI agent controls', content: 'An AI agent is a reusable model, prompt, and tool configuration that Spine invokes from pipelines, triggers, and chat interfaces. It defines how an LLM behaves, which tools it can call, and any guardrails.' },
+          { title: 'Fields explained', content: <ul className="list-disc pl-4 space-y-1">
+            <li><strong>Name</strong> — string. The display name used in lists and callers. Missing or empty prevents the record from being saved.</li>
+            <li><strong>Type</strong> — select. Categorizes the agent as chat, analysis, automation, or custom. Used to filter and route agents; a missing value defaults to chat.</li>
+            <li><strong>Model</strong> — string. The LLM model name stored in <code>model_config.model</code>. If blank, the API call will fail because no model is targeted.</li>
+            <li><strong>Max Tokens</strong> — number. The maximum response length. Invalid or empty parses to an empty value and may cause provider errors.</li>
+            <li><strong>Temperature</strong> — number between 0 and 2. Lower is more deterministic, higher is more random. Out of range values may be rejected by the provider.</li>
+            <li><strong>Description</strong> — string (optional). Human-readable context for other admins.</li>
+            <li><strong>System Prompt</strong> — text. Defines the agent personality, instructions, and constraints. Empty means the model receives no system message.</li>
+            <li><strong>App ID</strong> — string. Optional owning app UUID; blank means account-scoped.</li>
+            <li><strong>Tools (one per line)</strong> — newline-separated string list. Tool names the agent is allowed to invoke. Unknown or missing tools cause runtime errors.</li>
+            <li><strong>Capabilities</strong> — JSON object. Optional flags or settings the agent can use. Must be valid JSON or save fails.</li>
+            <li><strong>Constraints</strong> — JSON object. Optional guardrails. Must be valid JSON or save fails.</li>
+            <li><strong>Metadata</strong> — JSON object. Optional metadata. Must be valid JSON or save fails.</li>
+            <li><strong>Active</strong> — checkbox. Inactive agents are not available for invocation.</li>
+          </ul> },
+          { title: 'Options and values', content: <ul className="list-disc pl-4 space-y-1">
+            <li><strong>Agent type</strong>: <em>Chat</em> for conversational assistants, <em>Analysis</em> for data reasoning, <em>Automation</em> for pipeline actions, <em>Custom</em> for anything else.</li>
+            <li><strong>Active</strong>: enabled means the agent can be called; disabled means it is hidden from callers and will not run.</li>
+          </ul> },
+          { title: 'Downstream impact', content: <ul className="list-disc pl-4 space-y-1">
+            <li>Pipelines, triggers, and chat UIs reference agents by ID; deleting or changing the model changes their output.</li>
+            <li>Tool names listed here must match registered tool names exactly, otherwise the agent cannot call them.</li>
+            <li>Invalid JSON in Capabilities or Constraints will stop the save and leave the previous config in place.</li>
+          </ul> },
+          { title: 'How to create, save, and validate', content: <ol className="list-decimal pl-4 space-y-1">
+            <li>In create mode, fill every required field, enter at least a model name and system prompt.</li>
+            <li>Add tools one per line; supply optional JSON in Capabilities and Constraints.</li>
+            <li>Click Create. On existing records, click Edit, change fields, then Save.</li>
+            <li>Validation checks JSON syntax, parses Max Tokens and Temperature as numbers, and rejects empty Name/Model.</li>
+          </ol> },
+          { title: 'Common mistakes', content: <ul className="list-disc pl-4 space-y-1">
+            <li>Pasting a multiline tools string as a single comma-separated line.</li>
+            <li>Using invalid JSON in Capabilities or Constraints.</li>
+            <li>Referencing a model name that is not configured in the account, causing calls to fail.</li>
+          </ul> },
+        ]}
+      />
+      
       <div className="flex justify-end gap-2">
         {isEditing ? (
           <><Button variant="outline" onClick={() => isCreateMode ? navigate(-1) : setIsEditing(false)}>Cancel</Button><Button onClick={handleSave}>{isCreateMode ? 'Create' : 'Save'}</Button></>
@@ -125,6 +231,7 @@ export function AIAgentDetailPage() {
         <Card><CardContent className="p-6 space-y-4">
           <div className="grid grid-cols-1 md:grid-cols-2 gap-4">
             <div className="space-y-2"><Label>Name</Label><Input value={editData.name || ''} onChange={e => setEditData({...editData, name: e.target.value})} /></div>
+            <div className="space-y-2"><Label>App ID</Label><Input value={editData.app_id || ''} onChange={e => setEditData({...editData, app_id: e.target.value})} placeholder="Optional app UUID" /></div>
             <div className="space-y-2"><Label>Type</Label><Select value={editData.agent_type || 'chat'} onValueChange={v => setEditData({...editData, agent_type: v})}><SelectTrigger><SelectValue /></SelectTrigger><SelectContent>{AGENT_TYPES.map(t => <SelectItem key={t.value} value={t.value}>{t.label}</SelectItem>)}</SelectContent></Select></div>
             <div className="space-y-2"><Label>Model</Label><Input value={editData.model_config?.model || ''} onChange={e => setEditData({...editData, model_config: {...editData.model_config, model: e.target.value}})} /></div>
             <div className="space-y-2"><Label>Max Tokens</Label><Input type="number" value={editData.model_config?.max_tokens || ''} onChange={e => setEditData({...editData, model_config: {...editData.model_config, max_tokens: parseInt(e.target.value)}})} /></div>
@@ -136,6 +243,7 @@ export function AIAgentDetailPage() {
           <div className="grid grid-cols-1 md:grid-cols-2 gap-4">
             <div className="space-y-2"><Label>Capabilities (JSON)</Label><Textarea value={editData.capabilities || '{}'} onChange={e => setEditData({...editData, capabilities: e.target.value})} rows={4} className="font-mono text-sm" /></div>
             <div className="space-y-2"><Label>Constraints (JSON)</Label><Textarea value={editData.constraints || '{}'} onChange={e => setEditData({...editData, constraints: e.target.value})} rows={4} className="font-mono text-sm" /></div>
+            <div className="space-y-2"><Label>Metadata (JSON)</Label><Textarea value={editData.metadata || '{}'} onChange={e => setEditData({...editData, metadata: e.target.value})} rows={4} className="font-mono text-sm" /></div>
           </div>
           <div className="flex items-center gap-2"><Checkbox id="active" checked={editData.is_active} onCheckedChange={c => setEditData({...editData, is_active: c === true})} /><Label htmlFor="active">Active</Label></div>
         </CardContent></Card>
@@ -159,3 +267,4 @@ export function AIAgentDetailPage() {
     </div>
   )
 }
+// CIL[END chunk_id="aiagentdetailpage_function_aiagentdetailpage_1783668265"]