spine-framework 0.3.125 → 0.3.126

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

@@ -1,18 +1,25 @@
-/**
- * @module src/pages/admin/AlertsConfigPage
- * @audience installer
- * @layer frontend-page
- * @stability stable
- *
- * Alert rule configuration page. Fetches configured alert rules via
- * `/api/admin-data?action=alerts`, supports create / edit / delete via
- * an inline modal form. Rules define thresholds (metric, operator,
- * threshold value) and notification channels. Renders inside
- * `AdminListPage`.
- *
- * @seeAlso src/pages/admin/ObservabilityDashboard.tsx
- */
 
+
+
+
+
+
+
+// CIL[BEGIN chunk_id="alertsconfigpage_module_header_1783668265" type="module_header" identity="module_header" parent="none"]
+// CIL[DOC-MACRO purpose="Import dependencies for AlertsConfigPage component"]
+// CIL[DOC-RESPONSIBILITY responsibility="Import React hooks, UI components, and utilities"]
+// CIL[DOC-CONTEXT module="AlertsConfigPage" 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, UI components, API hooks, 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: 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 React, { useState } from 'react'
 import {
   Bell,
@@ -30,7 +37,21 @@ import { AdminListPage } from '../../components/admin/AdminListPage'
 import { useApi } from '../../hooks/useApi'
 import { apiFetch } from '../../lib/api'
 import { formatDateTime } from '../../lib/utils'
-
+// CIL[END chunk_id="alertsconfigpage_module_header_1783668265"]
+// CIL[BEGIN chunk_id="alertsconfigpage_interface_thresholdalert_1783668265" type="interface" identity="ThresholdAlert" parent="none"]
+// CIL[DOC-MACRO purpose="Define ThresholdAlert data structure"]
+// CIL[DOC-RESPONSIBILITY responsibility="Type definition for threshold alert objects"]
+// CIL[DOC-CONTEXT module="AlertsConfigPage" 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="ThresholdAlert interface type" errors="none" side_effects="none"]
+// CIL[DOC-MICRO logic_summary="Defines alert structure with metric configuration and status" 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 ThresholdAlert {
   id: string
   title: string
@@ -47,12 +68,40 @@ interface ThresholdAlert {
   created_at: string
   updated_at: string
 }
-
+// CIL[END chunk_id="alertsconfigpage_interface_thresholdalert_1783668265"]
+// CIL[BEGIN chunk_id="alertsconfigpage_interface_pipeline_1783668265" type="interface" identity="Pipeline" parent="none"]
+// CIL[DOC-MACRO purpose="Define Pipeline data structure"]
+// CIL[DOC-RESPONSIBILITY responsibility="Type definition for pipeline objects"]
+// CIL[DOC-CONTEXT module="AlertsConfigPage" 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="Pipeline interface type" errors="none" side_effects="none"]
+// CIL[DOC-MICRO logic_summary="Defines basic pipeline structure with id and name" 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 Pipeline {
   id: string
   name: string
 }
-
+// CIL[END chunk_id="alertsconfigpage_interface_pipeline_1783668265"]
+// CIL[BEGIN chunk_id="alertsconfigpage_constant_metric_labels_1783668265" type="constant" identity="METRIC_LABELS" parent="none"]
+// CIL[DOC-MACRO purpose="Define metric and operator label mappings"]
+// CIL[DOC-RESPONSIBILITY responsibility="Configure display labels for metrics and operators"]
+// CIL[DOC-CONTEXT module="AlertsConfigPage" layer="constants" related_files="[\"custom/apps/portal/pages/ContentPage.tsx\",\".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="Label mappings" errors="none" side_effects="none"]
+// CIL[DOC-MICRO logic_summary="Defines human-readable labels for metrics, operators, and units" 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: custom/apps/portal/pages/ContentPage.tsx, .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"]
 const METRIC_LABELS: Record<string, string> = {
   error_rate: 'Error Rate',
   latency_p95: 'Latency (P95)',
@@ -69,13 +118,26 @@ const UNIT_LABELS: Record<string, string> = {
   latency_p95: 'ms',
   pipeline_failure_rate: '%',
 }
-
+// CIL[END chunk_id="alertsconfigpage_constant_metric_labels_1783668265"]
+// CIL[BEGIN chunk_id="alertsconfigpage_function_alertsconfigpage_1783668265" type="function" identity="AlertsConfigPage" parent="none"]
+// CIL[DOC-MACRO purpose="Main AlertsConfigPage component implementation"]
+// CIL[DOC-RESPONSIBILITY responsibility="Render threshold alerts management interface with CRUD operations"]
+// CIL[DOC-CONTEXT module="AlertsConfigPage" layer="presentation" related_files="[]"]
+// CIL[DOC-CONTRACT inputs="none" outputs="React component" errors="API failures" side_effects="API calls, state management"]
+// CIL[DOC-MICRO logic_summary="Manages alerts state, handles create/edit/delete, renders alert list with modal" 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: none."]
+// 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 AlertsConfigPage() {
   const [isModalOpen, setIsModalOpen] = useState(false)
   const [editingAlert, setEditingAlert] = useState<ThresholdAlert | null>(null)
   const [isDeleting, setIsDeleting] = useState(false)
 
-  // Fetch threshold alerts (items with type = threshold_alert)
   const { data: alerts, loading, error, refetch } = useApi<ThresholdAlert[]>(
     async () => {
       const response = await apiFetch('/api/admin-data?entity=items&type_slug=threshold_alert')
@@ -88,7 +150,6 @@ export function AlertsConfigPage() {
     { immediate: true }
   )
 
-  // Fetch available pipelines for dropdown
   const { data: pipelines } = useApi<Pipeline[]>(
     async () => {
       const response = await apiFetch('/api/pipelines?action=list')
@@ -102,7 +163,7 @@ export function AlertsConfigPage() {
   const handleSave = async (formData: any) => {
     try {
       const payload = {
-        type_id: 'threshold_alert', // Will be resolved server-side
+        type_id: 'threshold_alert',
         title: formData.title,
         description: formData.description,
         status: formData.is_active ? 'active' : 'inactive',
@@ -117,14 +178,12 @@ export function AlertsConfigPage() {
       }
 
       if (editingAlert) {
-        // Update existing
         const response = await apiFetch(`/api/admin-data?entity=items&id=${editingAlert.id}`, {
           method: 'PUT',
           body: JSON.stringify(payload),
         })
         if (!response.ok) throw new Error('Failed to update alert')
       } else {
-        // Create new
         const response = await apiFetch('/api/admin-data?entity=items', {
           method: 'POST',
           body: JSON.stringify(payload),
@@ -315,7 +374,6 @@ export function AlertsConfigPage() {
         </div>
       )}
 
-      {/* Create/Edit Modal */}
       <AlertModal
         isOpen={isModalOpen}
         onClose={() => {
@@ -329,7 +387,21 @@ export function AlertsConfigPage() {
     </AdminListPage>
   )
 }
-
+// CIL[END chunk_id="alertsconfigpage_function_alertsconfigpage_1783668265"]
+// CIL[BEGIN chunk_id="alertsconfigpage_interface_alertmodalprops_1783668265" type="interface" identity="AlertModalProps" parent="none"]
+// CIL[DOC-MACRO purpose="Define AlertModal component props"]
+// CIL[DOC-RESPONSIBILITY responsibility="Type definition for AlertModal component properties"]
+// CIL[DOC-CONTEXT module="AlertsConfigPage" layer="types" related_files="[]"]
+// CIL[DOC-CONTRACT inputs="none" outputs="AlertModalProps interface type" errors="none" side_effects="none"]
+// CIL[DOC-MICRO logic_summary="Defines props for alert modal with state and callback handlers" 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: none."]
+// 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 AlertModalProps {
   isOpen: boolean
   onClose: () => void
@@ -337,7 +409,21 @@ interface AlertModalProps {
   alert: ThresholdAlert | null
   pipelines: Pipeline[]
 }
-
+// CIL[END chunk_id="alertsconfigpage_interface_alertmodalprops_1783668265"]
+// CIL[BEGIN chunk_id="alertsconfigpage_function_alertmodal_1783668265" type="function" identity="AlertModal" parent="none"]
+// CIL[DOC-MACRO purpose="AlertModal component implementation"]
+// CIL[DOC-RESPONSIBILITY responsibility="Render modal for creating/editing threshold alerts"]
+// CIL[DOC-CONTEXT module="AlertsConfigPage" layer="presentation" related_files="[]"]
+// CIL[DOC-CONTRACT inputs="none" outputs="React component" errors="Form validation" side_effects="Form submission"]
+// CIL[DOC-MICRO logic_summary="Manages form state for alert configuration with metric selection" 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: none."]
+// 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"]
 function AlertModal({ isOpen, onClose, onSave, alert, pipelines }: AlertModalProps) {
   const [formData, setFormData] = useState({
     title: '',
@@ -521,3 +607,4 @@ function AlertModal({ isOpen, onClose, onSave, alert, pipelines }: AlertModalPro
     </Modal>
   )
 }
+// CIL[END chunk_id="alertsconfigpage_function_alertmodal_1783668265"]

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

@@ -1,3 +1,21 @@
+
+
+
+// CIL[BEGIN chunk_id="appdetailpage_module_header_1783668265" type="module_header" identity="module_header" parent="none"]
+// CIL[DOC-MACRO purpose="Import dependencies for AppDetailPage component"]
+// CIL[DOC-RESPONSIBILITY responsibility="Import React hooks, routing, API hooks, and UI components"]
+// CIL[DOC-CONTEXT module="AppDetailPage" 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 React, { useState, useEffect } from 'react'
 import { useParams, useNavigate } from 'react-router-dom'
 import { useApi } from '../../hooks/useApi'
@@ -20,7 +38,22 @@ import {
 } from '../../components/ui/select'
 import { ArrowLeft, Pencil, Trash2, AlertCircle } from 'lucide-react';
 import { formatDateTime } from '../../lib/utils'
-
+import { PageInstructions } from '../../components/admin/PageInstructions'
+// CIL[END chunk_id="appdetailpage_module_header_1783668265"]
+// CIL[BEGIN chunk_id="appdetailpage_interface_app_1783668265" type="interface" identity="App" parent="none"]
+// CIL[DOC-MACRO purpose="Define App data structure"]
+// CIL[DOC-RESPONSIBILITY responsibility="Type definition for app objects"]
+// CIL[DOC-CONTEXT module="AppDetailPage" layer="types" related_files="[\".framework/src/pages/admin/IntegrationsPage.tsx\",\"custom/apps/cortex/functions/custom_cil-embeddings.ts\",\"custom/apps/portal/pages/ContentPage.tsx\",\"custom/apps/cortex/pages/operations/OperationsDashboard.tsx\",\"\\\"]"]
+// CIL[DOC-CONTRACT inputs="none" outputs="App interface type" errors="none" side_effects="none"]
+// CIL[DOC-MICRO logic_summary="Defines complete app structure with metadata, config, and stats" 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, custom/apps/cortex/functions/custom_cil-embeddings.ts, 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"]
 interface App {
   id: string
   slug: string
@@ -38,14 +71,32 @@ interface App {
   created_at: string
   updated_at?: string
   config?: Record<string, any>
-  is_public?: boolean
+  nav_items?: any[]
+  integration_deps?: any[]
+  metadata?: Record<string, any>
+  route_prefix?: string
+  renderer?: 'generic' | 'custom' | 'none'
   item_count?: number
   user_count?: number
   account_name?: string
   created_by?: string
   account_id?: string
 }
-
+// CIL[END chunk_id="appdetailpage_interface_app_1783668265"]
+// CIL[BEGIN chunk_id="appdetailpage_function_appdetailpage_1783668265" type="function" identity="AppDetailPage" parent="none"]
+// CIL[DOC-MACRO purpose="Main AppDetailPage component implementation"]
+// CIL[DOC-RESPONSIBILITY responsibility="Render app detail view with create/edit/delete functionality"]
+// CIL[DOC-CONTEXT module="AppDetailPage" 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 apps 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 AppDetailPage() {
   const { id } = useParams<{ id: string }>()
   const navigate = useNavigate()
@@ -67,7 +118,11 @@ export function AppDetailPage() {
     is_system: false,
     min_role: 'member',
     config: {},
-    is_public: false
+    nav_items: [],
+    integration_deps: [],
+    metadata: {},
+    route_prefix: '',
+    renderer: 'generic'
   })
   const [configText, setConfigText] = useState(JSON.stringify({}, null, 2))
 
@@ -90,7 +145,11 @@ export function AppDetailPage() {
           min_role: 'member',
           created_at: new Date().toISOString(),
           config: {},
-          is_public: false
+          nav_items: [],
+          integration_deps: [],
+          metadata: {},
+          route_prefix: '',
+          renderer: 'generic'
         }
       }
       const uuidRegex = /^[0-9a-f]{8}-[0-9a-f]{4}-[1-5][0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$/i
@@ -126,7 +185,11 @@ export function AppDetailPage() {
         is_system: app.is_system,
         min_role: app.min_role,
         config: app.config || {},
-        is_public: app.is_public || false
+        nav_items: app.nav_items || [],
+        integration_deps: app.integration_deps || [],
+        metadata: app.metadata || {},
+        route_prefix: app.route_prefix || '',
+        renderer: app.renderer || 'generic'
       }
       setEditData(initialData)
       setConfigText(JSON.stringify(app.config || {}, null, 2))
@@ -142,7 +205,7 @@ export function AppDetailPage() {
         console.warn('Invalid JSON in config field, using default:', error)
       }
       
-      const { is_public: _ip, item_count: _ic, user_count: _uc, account_name: _an, ...cleanData } = editData
+      const { item_count: _ic, user_count: _uc, account_name: _an, ...cleanData } = editData
       const saveData = { ...cleanData, config: parsedConfig }
       const url = isCreateMode 
         ? '/api/apps?action=create'
@@ -190,7 +253,11 @@ export function AppDetailPage() {
         is_system: app.is_system,
         min_role: app.min_role,
         config: app.config || {},
-        is_public: app.is_public || false
+        nav_items: app.nav_items || [],
+        integration_deps: app.integration_deps || [],
+        metadata: app.metadata || {},
+        route_prefix: app.route_prefix || '',
+        renderer: app.renderer || 'generic'
       })
       setConfigText(JSON.stringify(app.config || {}, null, 2))
     }
@@ -285,6 +352,55 @@ export function AppDetailPage() {
         </div>
       </div>
 
+      <PageInstructions
+        description="Configure an app, its metadata, and runtime settings."
+        sections={[
+          { title: 'What this app controls', content: 'An app is a registered application in Spine. It controls navigation visibility, which people can use it, and the JSON configuration that the app or its runtime types consume.' },
+          { title: 'Fields explained', content: <ul className="list-disc pl-4 space-y-1">
+            <li><strong>Name</strong> — string. The display name in the app switcher and registry.</li>
+            <li><strong>Slug</strong> — string. A unique URL-friendly identifier. Should be set at creation and rarely changed.</li>
+            <li><strong>Description</strong> — string. Optional short text shown in the app list.</li>
+            <li><strong>App Type</strong> — select. system, custom, or marketplace. Drives how the app is treated by the platform.</li>
+            <li><strong>Source</strong> — select. system, custom, or marketplace. Tracks where the app package came from.</li>
+            <li><strong>Min Role</strong> — select. member, admin, or owner. The lowest role that can see or access the app.</li>
+            <li><strong>Version</strong> — string. The current app version shown in the registry.</li>
+            <li><strong>Active</strong> — select true/false. Inactive apps are hidden and cannot be opened.</li>
+            <li><strong>System</strong> — select true/false. Marks apps that are part of the platform and should not be treated as tenant-managed.</li>
+            <li><strong>Icon</strong> — string. An icon name used by the UI. Invalid names show no icon.</li>
+            <li><strong>Color</strong> — select. The theme color for the app tile.</li>
+            <li><strong>Route Prefix</strong> — string. Optional URL prefix for the app (defaults to /slug).</li>
+            <li><strong>Renderer</strong> — select. generic, custom, or none. generic uses the design schema to render pages.</li>
+            <li><strong>Configuration (JSON)</strong> — JSON. Runtime configuration for the app or its generic renderer.</li>
+            <li><strong>Nav Items (JSON)</strong> — JSON. Array of navigation items for the app shell.</li>
+            <li><strong>Integration Deps (JSON)</strong> — JSON. Array of integration slugs the app depends on.</li>
+            <li><strong>Metadata (JSON)</strong> — JSON. Free-form metadata associated with the app.</li>
+          </ul> },
+          { title: 'Options and values', content: <ul className="list-disc pl-4 space-y-1">
+            <li><strong>Type/Source</strong>: <em>system</em> for built-in apps, <em>custom</em> for account-built apps, <em>marketplace</em> for installed apps.</li>
+            <li><strong>Min Role</strong>: <em>member</em> is most permissive, <em>admin</em> for admins, <em>owner</em> for account owners.</li>
+            <li><strong>Active</strong>: choose Active to publish, Inactive to hide.</li>
+            <li><strong>System</strong>: choose System to protect the app from tenant deletion.</li>
+            <li><strong>Color</strong>: blue, green, red, yellow, purple, pink, indigo, gray, slate.</li>
+          </ul> },
+          { title: 'Downstream impact', content: <ul className="list-disc pl-4 space-y-1">
+            <li>The app registry and shell navigation read these fields to decide which apps to show and who can open them.</li>
+            <li>Generic apps use the Configuration JSON and related types to render lists and detail pages.</li>
+            <li>Custom apps may read the slug and config to initialize routes. A missing slug or bad config can break the app.</li>
+          </ul> },
+          { title: 'How to create, save, and validate', content: <ol className="list-decimal pl-4 space-y-1">
+            <li>In create mode, fill the App Information card and enter a unique slug, then choose Type, Source, and Min Role.</li>
+            <li>Edit the Configuration JSON with valid JSON; the form warns about invalid syntax on save.</li>
+            <li>Click Create to save, or Save Changes when editing. Use Delete to remove the app after a confirmation.</li>
+            <li>Validation checks required fields and that the Configuration JSON is parseable.</li>
+          </ol> },
+          { title: 'Common mistakes', content: <ul className="list-disc pl-4 space-y-1">
+            <li>Reusing a slug that already exists, causing a unique constraint error.</li>
+            <li>Switching an app to Inactive while people are using it.</li>
+            <li>Pasting non-JSON text or trailing commas in the Configuration JSON.</li>
+          </ul> },
+        ]}
+      />
+
       <Card>
         <CardHeader>
           <CardTitle>App Information</CardTitle>
@@ -491,3 +607,4 @@ export function AppDetailPage() {
     </div>
   )
 }
+// CIL[END chunk_id="appdetailpage_function_appdetailpage_1783668265"]

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

@@ -1,3 +1,21 @@
+
+
+
+// CIL[BEGIN chunk_id="appspage_module_header_1783668265" type="module_header" identity="module_header" parent="none"]
+// CIL[DOC-MACRO purpose="Import dependencies for AppsPage component"]
+// CIL[DOC-RESPONSIBILITY responsibility="Import React hooks, UI components, and utilities"]
+// CIL[DOC-CONTEXT module="AppsPage" layer="presentation" 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\",\"custom/apps/portal/pages/CoursesPage.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/layout/Sidebar.tsx, .framework/src/components/ui/dialog.tsx, custom/apps/cortex/pages/operations/OperationsDashboard.tsx, custom/apps/portal/pages/ContentPage.tsx, custom/apps/portal/pages/CoursesPage.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 } from 'react'
 import { useNavigate } from 'react-router-dom'
 import { useApi } from '../../hooks/useApi'
@@ -25,7 +43,21 @@ import {
 } from '../../components/ui/table'
 import { AdminListPage } from '../../components/admin/AdminListPage'
 import { SortableTableHeader } from '../../components/admin/SortableTableHeader'
-
+// CIL[END chunk_id="appspage_module_header_1783668265"]
+// CIL[BEGIN chunk_id="appspage_interface_app_1783668265" type="interface" identity="App" parent="none"]
+// CIL[DOC-MACRO purpose="Define App data structure"]
+// CIL[DOC-RESPONSIBILITY responsibility="Type definition for app objects"]
+// CIL[DOC-CONTEXT module="AppsPage" layer="types" related_files="[\".framework/src/pages/admin/IntegrationsPage.tsx\",\"custom/apps/cortex/functions/custom_cil-embeddings.ts\",\"custom/apps/portal/pages/ContentPage.tsx\",\"custom/apps/cortex/pages/operations/OperationsDashboard.tsx\",\"custom/apps/portal/pages/CoursesPage.tsx\",\"\\\"]"]
+// CIL[DOC-CONTRACT inputs="none" outputs="App interface type" errors="none" side_effects="none"]
+// CIL[DOC-MICRO logic_summary="Defines complete app structure with metadata and stats" 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, custom/apps/cortex/functions/custom_cil-embeddings.ts, custom/apps/portal/pages/ContentPage.tsx, custom/apps/cortex/pages/operations/OperationsDashboard.tsx, custom/apps/portal/pages/CoursesPage.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 App {
   id: string
   slug: string
@@ -44,7 +76,21 @@ interface App {
   item_count: number
   user_count: number
 }
-
+// CIL[END chunk_id="appspage_interface_app_1783668265"]
+// CIL[BEGIN chunk_id="appspage_function_appspage_1783668265" type="function" identity="AppsPage" parent="none"]
+// CIL[DOC-MACRO purpose="Main AppsPage component implementation"]
+// CIL[DOC-RESPONSIBILITY responsibility="Render app management interface with filtering, sorting, and stats"]
+// CIL[DOC-CONTEXT module="AppsPage" layer="presentation" related_files="[\".framework/src/components/ui/dialog.tsx\",\".framework/src/components/layout/Sidebar.tsx\",\"custom/apps/portal/pages/ContentPage.tsx\",\"custom/apps/portal/pages/CoursesPage.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 state, fetches apps, handles filtering/sorting, renders table" 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, .framework/src/components/layout/Sidebar.tsx, custom/apps/portal/pages/ContentPage.tsx, custom/apps/portal/pages/CoursesPage.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 AppsPage() {
   const navigate = useNavigate()
   const [searchTerm, setSearchTerm] = useState('')
@@ -353,3 +399,4 @@ export function AppsPage() {
     </AdminListPage>
   )
 }
+// CIL[END chunk_id="appspage_function_appspage_1783668265"]