spine-framework 0.3.125 → 0.3.126

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

@@ -1,6 +1,21 @@
-/**
- * @module src/pages/admin/TriggerDetailPage
- */
+
+
+
+// CIL[BEGIN chunk_id="triggerdetailpage_moduleheader_1783664706" type="module_header" identity="module_header" parent="none"]
+// CIL[DOC-MACRO purpose="Import dependencies for TriggerDetailPage component"]
+// CIL[DOC-RESPONSIBILITY responsibility="Provide all external dependencies and UI components"]
+// CIL[DOC-CONTEXT module="TriggerDetailPage" layer="frontend-page" 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="React components and utilities" errors="none" side_effects="none"]
+// CIL[DOC-MICRO logic_summary="Imports React hooks, navigation, API utilities, and 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: frontend-page. 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 { apiFetch } from '../../lib/api'
@@ -16,24 +31,50 @@ import { Alert, AlertDescription, AlertTitle } from '../../components/ui/alert'
 import { Badge } from '../../components/ui/badge'
 import { ArrowLeft, Zap, AlertCircle } from 'lucide-react'
 import { formatDateTime } from '../../lib/utils'
-
+import { PageInstructions } from '../../components/admin/PageInstructions'
+// CIL[END chunk_id="triggerdetailpage_moduleheader_1783664706"]
+// CIL[BEGIN chunk_id="triggerdetailpage_trigger_1783664706" type="interface" identity="Trigger" parent="none"]
+// CIL[DOC-MACRO purpose="Define the Trigger data structure for trigger management"]
+// CIL[DOC-RESPONSIBILITY responsibility="Provide type definition for event/schedule/webhook triggers"]
+// CIL[DOC-CONTEXT module="TriggerDetailPage" layer="frontend-page" related_files="[\".framework/src/pages/admin/IntegrationsPage.tsx\",\".framework/functions/_shared/principal.ts\",\"custom/apps/cortex/pages/operations/OperationsDashboard.tsx\",\".framework/functions/_shared/schema-utils.ts\",\".framework/src/pages/admin/TypeDetailPage.tsx\",\"\\\"]"]
+// CIL[DOC-CONTRACT inputs="none" outputs="Trigger interface" errors="none" side_effects="none"]
+// CIL[DOC-MICRO logic_summary="Defines trigger structure with event configuration and action settings" 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/IntegrationsPage.tsx, .framework/functions/_shared/principal.ts, custom/apps/cortex/pages/operations/OperationsDashboard.tsx, .framework/functions/_shared/schema-utils.ts, .framework/src/pages/admin/TypeDetailPage.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 Trigger {
   id: string
   name: string
   description?: string
+  app_id?: string
   event_type: string
-  entity_type?: string
-  condition?: Record<string, any>
-  action_type: string
-  action_config: Record<string, any>
+  pipeline_id?: string
+  config?: Record<string, any>
+  metadata?: Record<string, any>
   is_active: boolean
-  priority: number
-  debounce_ms?: number
-  rate_limit_per_minute?: number
   created_at: string
   updated_at: string
 }
-
+// CIL[END chunk_id="triggerdetailpage_trigger_1783664706"]
+// CIL[BEGIN chunk_id="triggerdetailpage_triggerdetailpage_1783664706" type="function" identity="TriggerDetailPage" parent="none"]
+// CIL[DOC-MACRO purpose="Create/view/edit/delete page for single trigger records"]
+// CIL[DOC-RESPONSIBILITY responsibility="Manage trigger CRUD operations with form handling and validation"]
+// CIL[DOC-CONTEXT module="TriggerDetailPage" layer="frontend-page" related_files="[\".framework/src/pages/admin/TypeDetailPage.tsx\",\"custom/apps/portal/pages/ContentPage.tsx\",\"custom/apps/cortex/pages/operations/OperationsDashboard.tsx\",\".framework/src/pages/admin/RolesPage.tsx\",\"\\\"]"]
+// CIL[DOC-CONTRACT inputs="none" outputs="React component with trigger form" errors="API failures, validation errors" side_effects="API calls, navigation"]
+// CIL[DOC-MICRO logic_summary="Form handling with trigger configuration and action settings" 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/TypeDetailPage.tsx, custom/apps/portal/pages/ContentPage.tsx, custom/apps/cortex/pages/operations/OperationsDashboard.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 TriggerDetailPage() {
   const { id } = useParams<{ id: string }>()
   const navigate = useNavigate()
@@ -43,8 +84,7 @@ export function TriggerDetailPage() {
   const [error, setError] = useState<string | null>(null)
   const [isEditing, setIsEditing] = useState(isCreateMode)
   const [formData, setFormData] = useState({
-    name: '', description: '', event_type: '', entity_type: '', condition: '{}', action_type: '',
-    action_config: '{}', is_active: true, priority: 0, debounce_ms: 0, rate_limit_per_minute: 0
+    name: '', description: '', app_id: '', event_type: '', pipeline_id: '', config: '{}', metadata: '{}', is_active: true
   })
 
   useEffect(() => {
@@ -61,10 +101,14 @@ export function TriggerDetailPage() {
         const data = result.data
         setTrigger(data)
         setFormData({
-          name: data.name, description: data.description || '', event_type: data.event_type, entity_type: data.entity_type || '',
-          condition: JSON.stringify(data.condition || {}, null, 2), action_type: data.action_type,
-          action_config: JSON.stringify(data.action_config || {}, null, 2), is_active: data.is_active, priority: data.priority || 0,
-          debounce_ms: data.debounce_ms || 0, rate_limit_per_minute: data.rate_limit_per_minute || 0
+          name: data.name,
+          description: data.description || '',
+          app_id: data.app_id || '',
+          event_type: data.event_type,
+          pipeline_id: data.pipeline_id || '',
+          config: JSON.stringify(data.config || {}, null, 2),
+          metadata: JSON.stringify(data.metadata || {}, null, 2),
+          is_active: data.is_active ?? true
         })
       } catch (err) {
         setError(err instanceof Error ? err.message : 'Failed to load trigger')
@@ -77,14 +121,25 @@ export function TriggerDetailPage() {
 
   const handleSave = async () => {
     try {
-      let parsedCondition = {}, parsedActionConfig = {}
-      try { parsedCondition = JSON.parse(formData.condition) } catch {}
-      try { parsedActionConfig = JSON.parse(formData.action_config) } catch {}
+      let parsedConfig = {}
+      let parsedMetadata = {}
+      try { parsedConfig = JSON.parse(formData.config) } catch {}
+      try { parsedMetadata = JSON.parse(formData.metadata) } catch {}
       const url = isCreateMode ? '/api/triggers?action=create' : `/api/triggers?action=update&id=${id}`
       const method = isCreateMode ? 'POST' : 'PATCH'
+      const saveData = {
+        name: formData.name,
+        description: formData.description,
+        app_id: formData.app_id || null,
+        event_type: formData.event_type,
+        pipeline_id: formData.pipeline_id || null,
+        config: parsedConfig,
+        metadata: parsedMetadata,
+        is_active: formData.is_active
+      }
       const response = await apiFetch(url, {
         method, headers: { 'Content-Type': 'application/json' },
-        body: JSON.stringify({ ...formData, condition: parsedCondition, action_config: parsedActionConfig })
+        body: JSON.stringify(saveData)
       })
       if (!response.ok) throw new Error('Failed to save trigger')
       if (isCreateMode) {
@@ -121,29 +176,62 @@ export function TriggerDetailPage() {
         </div>
       </div>
 
-      <Card><CardContent className="p-6">
+      <PageInstructions
+        description="Define a trigger that reacts to events and invokes a pipeline."
+        sections={[
+          { title: 'What this trigger controls', content: 'A trigger listens for a Spine event_type and, when active, hands the event payload to a pipeline for processing. The config and metadata JSON objects configure the trigger engine.' },
+          { title: 'Fields explained', content: <ul className="list-disc pl-4 space-y-1">
+            <li><strong>Name</strong> — string. The display name. Missing name prevents saving.</li>
+            <li><strong>Event Type</strong> — string. The event to listen to, e.g. item.created. Must match the emitted event name exactly.</li>
+            <li><strong>App ID</strong> — string. Optional owning app UUID; blank means account-scoped.</li>
+            <li><strong>Pipeline ID</strong> — string. The pipeline to invoke when the trigger fires.</li>
+            <li><strong>Active</strong> — checkbox. Inactive triggers ignore all events.</li>
+            <li><strong>Description</strong> — string. Optional notes.</li>
+            <li><strong>Config (JSON)</strong> — JSON. Trigger engine configuration, e.g. filters or payload mapping.</li>
+            <li><strong>Metadata (JSON)</strong> — JSON. Optional metadata about the trigger.</li>
+          </ul> },
+          { title: 'Options and values', content: <ul className="list-disc pl-4 space-y-1">
+            <li><strong>Active</strong>: enabled means the trigger subscribes to the event bus; disabled means it is ignored.</li>
+          </ul> },
+          { title: 'Downstream impact', content: <ul className="list-disc pl-4 space-y-1">
+            <li>The event bus routes matching events to active triggers. A wrong Event Type means no execution.</li>
+            <li>Pipeline ID must refer to an existing pipeline; otherwise the event is dropped.</li>
+            <li>Config JSON is passed to the trigger engine; bad config can cause repeated failures.</li>
+          </ul> },
+          { title: 'How to create, save, and validate', content: <ol className="list-decimal pl-4 space-y-1">
+            <li>In create mode, enter the name, event type, and pipeline ID, and provide Config and Metadata as valid JSON.</li>
+            <li>Click Create or Save. The form validates JSON and required fields.</li>
+            <li>After saving, the trigger subscribes to the event bus when active.</li>
+          </ol> },
+          { title: 'Common mistakes', content: <ul className="list-disc pl-4 space-y-1">
+            <li>Using a typo in the Event Type so the trigger never matches.</li>
+            <li>Forgetting to set Active after saving.</li>
+            <li>Writing Config as a string instead of a JSON object.</li>
+          </ul> },
+        ]}
+      />
+
+      <Card><CardContent className="p-6 space-y-6">
         <div className="grid grid-cols-1 md:grid-cols-2 gap-6">
           <div className="space-y-4">
             <h3 className="text-sm font-medium text-muted-foreground">Trigger</h3>
             <div className="space-y-2"><Label>Name</Label>{isEditing ? <Input value={formData.name} onChange={e => setFormData({...formData, name: e.target.value})} /> : <div className="text-sm">{trigger?.name}</div>}</div>
+            <div className="space-y-2"><Label>App ID</Label>{isEditing ? <Input value={formData.app_id} onChange={e => setFormData({...formData, app_id: e.target.value})} placeholder="Optional app UUID" /> : <div className="text-sm font-mono">{trigger?.app_id || '—'}</div>}</div>
             <div className="space-y-2"><Label>Event Type</Label>{isEditing ? <Input value={formData.event_type} onChange={e => setFormData({...formData, event_type: e.target.value})} placeholder="e.g., item.created" /> : <Badge>{trigger?.event_type}</Badge>}</div>
-            <div className="space-y-2"><Label>Entity Type</Label>{isEditing ? <Input value={formData.entity_type} onChange={e => setFormData({...formData, entity_type: e.target.value})} placeholder="e.g., item" /> : <div className="text-sm">{trigger?.entity_type || '—'}</div>}</div>
             <div className="space-y-2"><Label>Active</Label>{isEditing ? <div className="flex items-center gap-2"><Checkbox id="active" checked={formData.is_active} onCheckedChange={c => setFormData({...formData, is_active: c === true})} /><Label htmlFor="active">Enabled</Label></div> : <div className="text-sm">{trigger?.is_active ? 'Yes' : 'No'}</div>}</div>
           </div>
           <div className="space-y-4">
             <h3 className="text-sm font-medium text-muted-foreground">Action</h3>
-            <div className="space-y-2"><Label>Action Type</Label>{isEditing ? <Input value={formData.action_type} onChange={e => setFormData({...formData, action_type: e.target.value})} placeholder="e.g., function.execute" /> : <Badge variant="secondary">{trigger?.action_type}</Badge>}</div>
-            <div className="space-y-2"><Label>Priority</Label>{isEditing ? <Input type="number" value={formData.priority} onChange={e => setFormData({...formData, priority: parseInt(e.target.value)})} /> : <div className="text-sm">{trigger?.priority}</div>}</div>
-            <div className="space-y-2"><Label>Debounce (ms)</Label>{isEditing ? <Input type="number" value={formData.debounce_ms} onChange={e => setFormData({...formData, debounce_ms: parseInt(e.target.value)})} /> : <div className="text-sm">{trigger?.debounce_ms}ms</div>}</div>
-            <div className="space-y-2"><Label>Rate Limit (/min)</Label>{isEditing ? <Input type="number" value={formData.rate_limit_per_minute} onChange={e => setFormData({...formData, rate_limit_per_minute: parseInt(e.target.value)})} /> : <div className="text-sm">{trigger?.rate_limit_per_minute}</div>}</div>
+            <div className="space-y-2"><Label>Pipeline ID</Label>{isEditing ? <Input value={formData.pipeline_id} onChange={e => setFormData({...formData, pipeline_id: e.target.value})} placeholder="Pipeline to invoke" /> : <div className="text-sm font-mono">{trigger?.pipeline_id || '—'}</div>}</div>
           </div>
         </div>
         <div className="mt-6 space-y-2"><Label>Description</Label>{isEditing ? <Textarea value={formData.description} onChange={e => setFormData({...formData, description: e.target.value})} rows={2} /> : <div className="text-sm">{trigger?.description || '—'}</div>}</div>
         <div className="mt-6 grid grid-cols-1 md:grid-cols-2 gap-4">
-          <div className="space-y-2"><Label>Condition (JSON)</Label>{isEditing ? <Textarea value={formData.condition} onChange={e => setFormData({...formData, condition: e.target.value})} rows={6} className="font-mono text-sm" /> : <pre className="text-sm bg-muted p-3 rounded">{JSON.stringify(trigger?.condition || {}, null, 2)}</pre>}</div>
-          <div className="space-y-2"><Label>Action Config (JSON)</Label>{isEditing ? <Textarea value={formData.action_config} onChange={e => setFormData({...formData, action_config: e.target.value})} rows={6} className="font-mono text-sm" /> : <pre className="text-sm bg-muted p-3 rounded">{JSON.stringify(trigger?.action_config || {}, null, 2)}</pre>}</div>
+          <div className="space-y-2"><Label>Config (JSON)</Label>{isEditing ? <Textarea value={formData.config} onChange={e => setFormData({...formData, config: e.target.value})} rows={6} className="font-mono text-sm" /> : <pre className="text-sm bg-muted p-3 rounded">{JSON.stringify(trigger?.config || {}, null, 2)}</pre>}</div>
+          <div className="space-y-2"><Label>Metadata (JSON)</Label>{isEditing ? <Textarea value={formData.metadata} onChange={e => setFormData({...formData, metadata: e.target.value})} rows={6} className="font-mono text-sm" /> : <pre className="text-sm bg-muted p-3 rounded">{JSON.stringify(trigger?.metadata || {}, null, 2)}</pre>}</div>
         </div>
       </CardContent></Card>
     </div>
   )
 }
+// CIL[END chunk_id="triggerdetailpage_triggerdetailpage_1783664706"]

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

@@ -1,18 +1,22 @@
-/**
- * @module src/pages/admin/TriggersPage
- * @audience installer
- * @layer frontend-page
- * @stability stable
- *
- * Admin list page for event/schedule/webhook triggers. Fetches all
- * triggers via `/api/triggers?action=list`, applies client-side search,
- * trigger-type filter, and sort. Supports inline enable/disable toggle.
- * Renders inside `AdminListPage`. Row clicks navigate to
- * `/spine-framework/admin/configs/triggers/:id`.
- *
- * @seeAlso src/pages/admin/TriggerDetailPage.tsx
- */
 
+
+
+
+// CIL[BEGIN chunk_id="triggerspage_moduleheader_1783664706" type="module_header" identity="module_header" parent="none"]
+// CIL[DOC-MACRO purpose="Import dependencies for TriggersPage component"]
+// CIL[DOC-RESPONSIBILITY responsibility="Provide all external dependencies and UI components"]
+// CIL[DOC-CONTEXT module="TriggersPage" layer="frontend-page" related_files="[\".framework/src/components/layout/Sidebar.tsx\",\".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\",\"\\\"]"]
+// CIL[DOC-CONTRACT inputs="none" outputs="React components and utilities" errors="none" side_effects="none"]
+// CIL[DOC-MICRO logic_summary="Imports React hooks, navigation, API utilities, icons, and 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: frontend-page. Direct callers: 0. Direct calls: 0. Related files: .framework/src/components/layout/Sidebar.tsx, .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, \."]
+// 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 } from 'react'
 import { useNavigate } from 'react-router-dom'
 import { useApi } from '../../hooks/useApi'
@@ -25,7 +29,21 @@ import { Badge } from '../../components/ui/badge'
 import { formatDateTime } from '../../lib/utils'
 import { AdminListPage } from '../../components/admin/AdminListPage'
 import { SortableTableHeader } from '../../components/admin/SortableTableHeader'
-
+// CIL[END chunk_id="triggerspage_moduleheader_1783664706"]
+// CIL[BEGIN chunk_id="triggerspage_trigger_1783664706" type="interface" identity="Trigger" parent="none"]
+// CIL[DOC-MACRO purpose="Define the Trigger data structure for trigger management"]
+// CIL[DOC-RESPONSIBILITY responsibility="Provide type definition for event/schedule/webhook triggers"]
+// CIL[DOC-CONTEXT module="TriggersPage" layer="frontend-page" related_files="[\".framework/src/pages/admin/IntegrationsPage.tsx\",\".framework/functions/_shared/principal.ts\",\"custom/apps/cortex/pages/operations/OperationsDashboard.tsx\",\".framework/functions/_shared/schema-utils.ts\",\".framework/src/pages/admin/TypeDetailPage.tsx\",\"\\\"]"]
+// CIL[DOC-CONTRACT inputs="none" outputs="Trigger interface" errors="none" side_effects="none"]
+// CIL[DOC-MICRO logic_summary="Defines comprehensive trigger structure with execution tracking" 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/IntegrationsPage.tsx, .framework/functions/_shared/principal.ts, custom/apps/cortex/pages/operations/OperationsDashboard.tsx, .framework/functions/_shared/schema-utils.ts, .framework/src/pages/admin/TypeDetailPage.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 Trigger {
   id: string
   name: string
@@ -43,7 +61,21 @@ interface Trigger {
   last_execution?: string
   next_execution?: string
 }
-
+// CIL[END chunk_id="triggerspage_trigger_1783664706"]
+// CIL[BEGIN chunk_id="triggerspage_triggerexecution_1783664706" type="interface" identity="TriggerExecution" parent="none"]
+// CIL[DOC-MACRO purpose="Define the TriggerExecution data structure for execution tracking"]
+// CIL[DOC-RESPONSIBILITY responsibility="Provide type definition for trigger execution records"]
+// CIL[DOC-CONTEXT module="TriggersPage" layer="frontend-page" related_files="[\".framework/src/pages/admin/IntegrationsPage.tsx\",\".framework/functions/_shared/principal.ts\",\"custom/apps/cortex/pages/operations/OperationsDashboard.tsx\",\".framework/functions/_shared/schema-utils.ts\",\".framework/src/components/layout/Sidebar.tsx\",\"\\\"]"]
+// CIL[DOC-CONTRACT inputs="none" outputs="TriggerExecution interface" errors="none" side_effects="none"]
+// CIL[DOC-MICRO logic_summary="Defines execution tracking structure with status and results" 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/IntegrationsPage.tsx, .framework/functions/_shared/principal.ts, custom/apps/cortex/pages/operations/OperationsDashboard.tsx, .framework/functions/_shared/schema-utils.ts, .framework/src/components/layout/Sidebar.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 TriggerExecution {
   id: string
   trigger_id: string
@@ -54,7 +86,21 @@ interface TriggerExecution {
   result?: Record<string, any>
   error?: string
 }
-
+// CIL[END chunk_id="triggerspage_triggerexecution_1783664706"]
+// CIL[BEGIN chunk_id="triggerspage_triggerspage_1783664706" type="function" identity="TriggersPage" parent="none"]
+// CIL[DOC-MACRO purpose="Admin list page for managing automated triggers for workflows"]
+// CIL[DOC-RESPONSIBILITY responsibility="Fetch, filter, sort, and display triggers with navigation"]
+// CIL[DOC-CONTEXT module="TriggersPage" layer="frontend-page" related_files="[\".framework/src/pages/admin/TypeDetailPage.tsx\",\"custom/apps/cortex/pages/operations/OperationsDashboard.tsx\",\"custom/apps/portal/pages/ContentPage.tsx\",\".framework/src/pages/admin/RolesPage.tsx\",\"\\\"]"]
+// CIL[DOC-CONTRACT inputs="none" outputs="React component with trigger list" errors="API failures" side_effects="API calls, navigation"]
+// CIL[DOC-MICRO logic_summary="Client-side filtering, sorting, and stats calculation for triggers" 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/TypeDetailPage.tsx, custom/apps/cortex/pages/operations/OperationsDashboard.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 TriggersPage() {
   console.log('TriggersPage rendering...')
   const navigate = useNavigate()
@@ -64,7 +110,6 @@ export function TriggersPage() {
   const [sortKey, setSortKey] = useState('name')
   const [sortDirection, setSortDirection] = useState<'asc' | 'desc'>('asc')
 
-  // Fetch triggers from API
   const { data: triggers, loading, error, refetch } = useApi<Trigger[]>(
     async ({ signal }: { signal?: AbortSignal }) => {
       try {
@@ -81,7 +126,6 @@ export function TriggersPage() {
         const result = await response.json()
         console.log('Raw API result:', result)
         
-        // Handle both nested and direct responses
         const triggers = result.data || result
         console.log('Triggers after processing:', triggers)
         
@@ -379,3 +423,4 @@ export function TriggersPage() {
     </AdminListPage>
   )
 }
+// CIL[END chunk_id="triggerspage_triggerspage_1783664706"]

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

@@ -1,12 +1,22 @@
-/**
- * @module src/pages/admin/TypeDetailPage
- * @audience installer
- * @layer frontend-page
- * @stability stable
- *
- * Create / view / edit / delete page for a single type record.
- */
 
+
+
+
+// CIL[BEGIN chunk_id="typedetailpage_moduleheader_1783664706" type="module_header" identity="module_header" parent="none"]
+// CIL[DOC-MACRO purpose="Import dependencies for TypeDetailPage component"]
+// CIL[DOC-RESPONSIBILITY responsibility="Provide all external dependencies and UI components"]
+// CIL[DOC-CONTEXT module="TypeDetailPage" layer="frontend-page" 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/RolesPage.tsx\",\"\\\"]"]
+// CIL[DOC-CONTRACT inputs="none" outputs="React components and utilities" errors="none" side_effects="none"]
+// CIL[DOC-MICRO logic_summary="Imports React hooks, navigation, API utilities, and 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: frontend-page. 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/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 React, { useState, useEffect } from 'react'
 import { useParams, useNavigate } from 'react-router-dom'
 import { useApi } from '../../hooks/useApi'
@@ -26,7 +36,22 @@ import { Alert, AlertDescription, AlertTitle } from '../../components/ui/alert'
 import { DataTable } from '../../components/ui/DataTable'
 import { ArrowLeft, Pencil, Trash2, AlertCircle } from 'lucide-react'
 import { formatDateTime } from '../../lib/utils'
-
+import { PageInstructions } from '../../components/admin/PageInstructions'
+// CIL[END chunk_id="typedetailpage_moduleheader_1783664706"]
+// CIL[BEGIN chunk_id="typedetailpage_type_1783664706" type="interface" identity="Type" parent="none"]
+// CIL[DOC-MACRO purpose="Define the Type data structure for type management"]
+// CIL[DOC-RESPONSIBILITY responsibility="Provide type definition for item/account/person types"]
+// CIL[DOC-CONTEXT module="TypeDetailPage" layer="frontend-page" related_files="[\".framework/migrations/025_retype_threads_messages.sql\",\"custom/apps/cortex/pages/operations/OperationsDashboard.tsx\",\".framework/src/pages/admin/IntegrationsPage.tsx\",\".framework/functions/_shared/schema-utils.ts\",\"\\\"]"]
+// CIL[DOC-CONTRACT inputs="none" outputs="Type interface" errors="none" side_effects="none"]
+// CIL[DOC-MICRO logic_summary="Defines comprehensive type structure with design schema and permissions" 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: 1. Direct calls: 0. Related files: .framework/migrations/025_retype_threads_messages.sql, custom/apps/cortex/pages/operations/OperationsDashboard.tsx, .framework/src/pages/admin/IntegrationsPage.tsx, .framework/functions/_shared/schema-utils.ts, \."]
+// CIL[DOC-VECTOR type="blast_radius" content="Direct callers: 1. Total affected: 1."]
+// 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 Type {
   id: string
   name: string
@@ -39,6 +64,8 @@ interface Type {
     fields: Record<string, any>
     record_permissions?: Record<string, string[]>
   }
+  validation_schema?: Record<string, any>
+  view_config?: Record<string, any>
   ownership: string
   is_active: boolean
   app_id?: string
@@ -46,7 +73,21 @@ interface Type {
   created_at: string
   updated_at: string
 }
-
+// CIL[END chunk_id="typedetailpage_type_1783664706"]
+// CIL[BEGIN chunk_id="typedetailpage_typeitem_1783664706" type="interface" identity="TypeItem" parent="none"]
+// CIL[DOC-MACRO purpose="Define the TypeItem data structure for item instances"]
+// CIL[DOC-RESPONSIBILITY responsibility="Provide type definition for type item records"]
+// CIL[DOC-CONTEXT module="TypeDetailPage" layer="frontend-page" related_files="[\".framework/src/pages/admin/IntegrationsPage.tsx\",\".framework/functions/_shared/principal.ts\",\"custom/apps/cortex/pages/operations/OperationsDashboard.tsx\",\".framework/functions/_shared/schema-utils.ts\",\"\\\"]"]
+// CIL[DOC-CONTRACT inputs="none" outputs="TypeItem interface" errors="none" side_effects="none"]
+// CIL[DOC-MICRO logic_summary="Defines item structure with data, metadata, and ownership" 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/IntegrationsPage.tsx, .framework/functions/_shared/principal.ts, custom/apps/cortex/pages/operations/OperationsDashboard.tsx, .framework/functions/_shared/schema-utils.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 TypeItem {
   id: string
   item_type_id: string
@@ -57,7 +98,21 @@ interface TypeItem {
   created_by: string
   account_id: string
 }
-
+// CIL[END chunk_id="typedetailpage_typeitem_1783664706"]
+// CIL[BEGIN chunk_id="typedetailpage_typedetailpage_1783664706" type="function" identity="TypeDetailPage" parent="none"]
+// CIL[DOC-MACRO purpose="Create/view/edit/delete page for single type records"]
+// CIL[DOC-RESPONSIBILITY responsibility="Manage type CRUD operations with form handling and validation"]
+// CIL[DOC-CONTEXT module="TypeDetailPage" layer="frontend-page" related_files="[\"custom/apps/cortex/pages/operations/OperationsDashboard.tsx\",\"custom/apps/portal/pages/ContentPage.tsx\",\".framework/src/pages/admin/RolesPage.tsx\",\"\\\"]"]
+// CIL[DOC-CONTRACT inputs="none" outputs="React component with type form" errors="API failures, validation errors" side_effects="API calls, navigation"]
+// CIL[DOC-MICRO logic_summary="Complex form handling with schema validation and item 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: 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/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 TypeDetailPage() {
   const { id, kind } = useParams<{ id: string, kind: string }>()
   const navigate = useNavigate()
@@ -73,12 +128,14 @@ export function TypeDetailPage() {
     icon: '',
     color: '',
     kind: typeKind,
-    schema: { fields: {} },
+    design_schema: { fields: {} },
+    view_config: {},
     ownership: 'app',
     app_id: '',
     is_active: true
   })
   const [schemaText, setSchemaText] = useState(JSON.stringify({ fields: {} }, null, 2))
+  const [viewConfigText, setViewConfigText] = useState(JSON.stringify({}, null, 2))
   const [availableApps, setAvailableApps] = useState<Array<{id: string, name: string}>>([])
 
   React.useEffect(() => {
@@ -153,11 +210,13 @@ export function TypeDetailPage() {
         color: type.color || '',
         kind: type.kind || 'item',
         design_schema: type.design_schema || { fields: {} },
+        view_config: type.view_config || {},
         ownership: type.ownership || 'system',
         app_id: type.app_id || '',
         is_active: type.is_active ?? true
       })
       setSchemaText(JSON.stringify(type.design_schema || { fields: {} }, null, 2))
+      setViewConfigText(JSON.stringify(type.view_config || {}, null, 2))
     }
   }, [type])
 
@@ -169,14 +228,21 @@ export function TypeDetailPage() {
         throw new Error('App selection is required when ownership is not "System"')
       }
       let parsedSchema = { fields: {} }
+      let parsedViewConfig = {}
       try {
         parsedSchema = JSON.parse(schemaText)
       } catch (error) {
         console.warn('Invalid JSON in schema field, using default:', error)
       }
+      try {
+        parsedViewConfig = JSON.parse(viewConfigText)
+      } catch (error) {
+        console.warn('Invalid JSON in view config field, using default:', error)
+      }
       const saveData = {
         ...editData,
         design_schema: parsedSchema,
+        view_config: parsedViewConfig,
         app_id: editData.app_id || null
       }
       const url = isCreateMode 
@@ -216,11 +282,13 @@ export function TypeDetailPage() {
         icon: type.icon || '',
         color: type.color || '',
         design_schema: type.design_schema || { fields: {} },
+        view_config: type.view_config || {},
         ownership: type.ownership || 'system',
         app_id: type.app_id || '',
         is_active: type.is_active ?? true
       })
       setSchemaText(JSON.stringify(type.design_schema || { fields: {} }, null, 2))
+      setViewConfigText(JSON.stringify(type.view_config || {}, null, 2))
     }
     setIsEditing(false)
   }
@@ -373,6 +441,48 @@ export function TypeDetailPage() {
         </div>
       </div>
 
+      <PageInstructions
+        description="Manage type schemas, fields, and permissions for items, accounts, or people."
+        sections={[
+          { title: 'What this type controls', content: 'A type is the design schema for a runtime record kind. It defines the fields, default list/detail views, record permissions, icon, color, and metadata that the generic admin and runtime UIs use to create, validate, and display records.' },
+          { title: 'Fields explained', content: <ul className="list-disc pl-4 space-y-1">
+            <li><strong>Name</strong> — string. The display label for the type. Empty name blocks save.</li>
+            <li><strong>Slug</strong> — string. A unique, URL-friendly identifier scoped by kind. Used for type resolution and must be globally unique.</li>
+            <li><strong>Description</strong> — string. Optional human-readable context.</li>
+            <li><strong>Kind</strong> — select. item, account, person, thread, or message. Determines which runtime table the type governs.</li>
+            <li><strong>Ownership</strong> — select. system, app, or tenant. Controls the data scope and who can manage the type.</li>
+            <li><strong>Is Active</strong> — checkbox. Inactive types cannot have records created.</li>
+            <li><strong>App ID</strong> — select. Optional owning app. None means a system type. Selecting an app scopes the type to that app.</li>
+            <li><strong>Icon</strong> — string. An icon name for the UI stored in the types row.</li>
+            <li><strong>Color</strong> — select. The theme color for the type stored in the types row.</li>
+            <li><strong>Created / Updated</strong> — read-only timestamps.</li>
+            <li><strong>Design Schema (JSON)</strong> — JSON. The full design_schema with fields, views, and record_permissions. The validation_schema is regenerated from this on save.</li>
+            <li><strong>View Config (JSON)</strong> — JSON. Optional view_config object stored alongside the design schema.</li>
+          </ul> },
+          { title: 'Options and values', content: <ul className="list-disc pl-4 space-y-1">
+            <li><strong>Kind</strong>: <em>item</em> for records, <em>account</em> for accounts, <em>person</em> for people, <em>thread</em> for threads, <em>message</em> for messages.</li>
+            <li><strong>Ownership</strong>: <em>system</em> for platform types, <em>app</em> for an app, <em>tenant</em> for account-specific.</li>
+            <li><strong>Color</strong>: blue, green, red, yellow, purple, pink, indigo, gray, slate.</li>
+            <li><strong>Design Schema</strong>: must include fields, default_list, default_detail, and record_permissions to satisfy the generic UI.</li>
+          </ul> },
+          { title: 'Downstream impact', content: <ul className="list-disc pl-4 space-y-1">
+            <li>Generic List and Detail pages render directly from this schema. A missing view or bad field will break those pages.</li>
+            <li>Record creation and validation use the design schema. Bad permissions or data_type values can cause permission errors or failed saves.</li>
+            <li>Other apps, pipelines, and triggers resolve types by slug; duplicate or changed slugs break those lookups.</li>
+          </ul> },
+          { title: 'How to create, save, and validate', content: <ol className="list-decimal pl-4 space-y-1">
+            <li>In create mode, choose a kind, name, slug, and ownership, then fill the Design Schema and optional View Config JSON.</li>
+            <li>Click Create or Save Changes. The form validates that the JSON is valid; the API regenerates validation_schema from design_schema.</li>
+            <li>Delete is disabled for system-owned types. Delete opens a confirmation modal for others.</li>
+          </ol> },
+          { title: 'Common mistakes', content: <ul className="list-disc pl-4 space-y-1">
+            <li>Reusing a slug for the same kind, which breaks type resolution.</li>
+            <li>Missing default_list or default_detail in the design schema, causing the generic UI to fail.</li>
+            <li>Using an unknown data_type or display_type, leading to validation or rendering errors.</li>
+          </ul> },
+        ]}
+      />
+
       {isEditing ? (
         <>
           <Card>
@@ -514,15 +624,27 @@ export function TypeDetailPage() {
               
               <div className="mt-8 space-y-2">
                 <h3 className="text-sm font-medium text-muted-foreground">Schema Definition</h3>
-                <Label>Schema</Label>
+                <Label>Design Schema</Label>
                 <Textarea
                   value={schemaText}
                   onChange={(e) => setSchemaText(e.target.value)}
                   className="font-mono text-sm"
                   rows={8}
-                  placeholder='Enter JSON schema with fields object'
+                  placeholder='Enter JSON design schema with fields, views, and record_permissions'
+                />
+                <p className="text-xs text-muted-foreground">JSON schema defining the fields, list/detail views, and record permissions for this type. The validation_schema is generated from this on save.</p>
+              </div>
+
+              <div className="mt-8 space-y-2">
+                <Label>View Config</Label>
+                <Textarea
+                  value={viewConfigText}
+                  onChange={(e) => setViewConfigText(e.target.value)}
+                  className="font-mono text-sm"
+                  rows={4}
+                  placeholder='Enter optional view_config JSON'
                 />
-                <p className="text-xs text-muted-foreground">JSON schema defining the fields for this type.</p>
+                <p className="text-xs text-muted-foreground">Optional JSON view configuration stored alongside the design schema.</p>
               </div>
             </CardContent>
           </Card>
@@ -692,3 +814,4 @@ export function TypeDetailPage() {
     </div>
   )
 }
+// CIL[END chunk_id="typedetailpage_typedetailpage_1783664706"]