spine-framework 0.3.125 → 0.3.127

package/.framework/src/components/app-shell/GenericAppShell.tsx

@@ -1,9 +1,43 @@
+
+
+
+
+
+// CIL[BEGIN chunk_id="genericappshell_module_header_1783930597" type="module_header" identity="imports" parent="none"]
+// CIL[DOC-MACRO purpose="Import React hooks and routing components for app shell"]
+// CIL[DOC-RESPONSIBILITY responsibility="Provide state management and routing dependencies"]
+// CIL[DOC-CONTEXT module="generic-app-shell" layer="frontend-component" related_files="[\"custom/apps/portal/pages/ContentPage.tsx\",\"custom/apps/cortex/pages/operations/OperationsDashboard.tsx\",\".framework/migrations/015_simplify_apps_table.sql\",\".framework/src/components/ui/dialog.tsx\",\"\\\"]"]
+// CIL[DOC-CONTRACT inputs="none" outputs="Imported modules" errors="none" side_effects="none"]
+// CIL[DOC-MICRO logic_summary="Imports React hooks, routing components, and app-specific pages" 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-component. 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, .framework/src/components/ui/dialog.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 { Routes, Route, Navigate, useNavigate, useLocation } from 'react-router-dom'
 import { AppRecord } from '../../hooks/useApps'
 import { GenericListPage } from './GenericListPage'
 import { GenericDetailPage } from './GenericDetailPage'
-
+// CIL[END chunk_id="genericappshell_module_header_1783930597"]
+// CIL[BEGIN chunk_id="genericappshell_navitem_1783930597" type="interface" identity="NavItem" parent="none"]
+// CIL[DOC-MACRO purpose="Define navigation item structure for app shell"]
+// CIL[DOC-RESPONSIBILITY responsibility="Specify navigation properties and routing metadata"]
+// CIL[DOC-CONTEXT module="generic-app-shell" layer="frontend-component" related_files="[\".framework/migrations/015_simplify_apps_table.sql\",\".framework/src/pages/admin/IntegrationsPage.tsx\",\"custom/apps/cortex/pages/operations/OperationsDashboard.tsx\",\"custom/apps/portal/pages/ContentPage.tsx\",\"\\\"]"]
+// CIL[DOC-CONTRACT inputs="none" outputs="Type definition" errors="none" side_effects="none"]
+// CIL[DOC-MICRO logic_summary="Interface with id, label, path, and optional type/view metadata" 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-component. Direct callers: 0. Direct calls: 0. Related files: .framework/migrations/015_simplify_apps_table.sql, .framework/src/pages/admin/IntegrationsPage.tsx, custom/apps/cortex/pages/operations/OperationsDashboard.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"]
 interface NavItem {
   id: string
   label: string
@@ -13,16 +47,39 @@ interface NavItem {
   view?: string
   min_role?: string
 }
-
+// CIL[END chunk_id="genericappshell_navitem_1783930597"]
+// CIL[BEGIN chunk_id="genericappshell_genericappshellprops_1783930597" type="interface" identity="GenericAppShellProps" parent="none"]
+// CIL[DOC-MACRO purpose="Define props interface for generic app shell component"]
+// CIL[DOC-RESPONSIBILITY responsibility="Specify app configuration input for shell"]
+// CIL[DOC-CONTEXT module="generic-app-shell" layer="frontend-component" related_files="[\"custom/apps/portal/pages/ContentPage.tsx\",\".framework/migrations/015_simplify_apps_table.sql\",\".framework/functions/_shared/schema-utils.ts\",\"custom/apps/cortex/pages/operations/OperationsDashboard.tsx\",\"\\\"]"]
+// CIL[DOC-CONTRACT inputs="none" outputs="Type definition" errors="none" side_effects="none"]
+// CIL[DOC-MICRO logic_summary="Simple interface requiring app record with navigation configuration" 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-component. Direct callers: 0. Direct calls: 0. Related files: custom/apps/portal/pages/ContentPage.tsx, .framework/migrations/015_simplify_apps_table.sql, .framework/functions/_shared/schema-utils.ts, 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 GenericAppShellProps {
   app: AppRecord
 }
-
-/**
- * Data-driven app shell. Reads nav_items from the app record to build
- * a sidebar and child routes. Each nav entry with a type_slug renders
- * a GenericListPage (at path) and GenericDetailPage (at path/:id).
- */
+// CIL[END chunk_id="genericappshell_genericappshellprops_1783930597"]
+// CIL[BEGIN chunk_id="genericappshell_genericappshell_1783930597" type="function" identity="GenericAppShell" parent="none"]
+// CIL[DOC-MACRO purpose="Data-driven app shell with sidebar navigation and routing"]
+// CIL[DOC-RESPONSIBILITY responsibility="Create complete app layout from app configuration"]
+// CIL[DOC-CONTEXT module="generic-app-shell" layer="frontend-component" related_files="[\"custom/apps/portal/pages/ContentPage.tsx\",\".framework/migrations/015_simplify_apps_table.sql\",\"custom/apps/cortex/pages/operations/OperationsDashboard.tsx\",\"custom/apps/cortex/functions/custom_cil-embeddings.ts\",\"\\\"]"]
+// CIL[DOC-CONTRACT inputs="none" outputs="JSX app shell with routes" errors="none" side_effects="Renders navigation, handles routing, manages sidebar state"]
+// CIL[DOC-MICRO logic_summary="Builds sidebar from nav_items, generates routes for list/detail pages, handles mobile responsiveness" 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-component. Direct callers: 0. Direct calls: 0. Related files: custom/apps/portal/pages/ContentPage.tsx, .framework/migrations/015_simplify_apps_table.sql, custom/apps/cortex/pages/operations/OperationsDashboard.tsx, 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"]
 export function GenericAppShell({ app }: GenericAppShellProps) {
   const navigate = useNavigate()
   const location = useLocation()
@@ -30,10 +87,10 @@ export function GenericAppShell({ app }: GenericAppShellProps) {
 
   const navItems: NavItem[] = (app.nav_items || []) as NavItem[]
 
-  // Derive relative paths from app's route_prefix
+  
   const prefix = app.route_prefix || `/${app.slug}`
 
-  // Check if a nav item is active
+  
   const isActive = (item: NavItem) => {
     const fullPath = item.path.startsWith('/') ? item.path : `${prefix}/${item.path}`
     return location.pathname.startsWith(fullPath)
@@ -120,7 +177,7 @@ export function GenericAppShell({ app }: GenericAppShellProps) {
 
             {/* Generate list + detail routes for each nav item with type_slug */}
             {navItems.filter(item => item.type_slug).map(item => {
-              // Strip leading prefix to get relative route path
+              
               const relativePath = item.path.startsWith(prefix)
                 ? item.path.slice(prefix.length).replace(/^\//, '')
                 : item.path.replace(/^\//, '')
@@ -179,3 +236,4 @@ export function GenericAppShell({ app }: GenericAppShellProps) {
     </div>
   )
 }
+// CIL[END chunk_id="genericappshell_genericappshell_1783930597"]

package/.framework/src/components/app-shell/GenericDetailPage.tsx

@@ -1,20 +1,64 @@
+
+
+
+
+// CIL[BEGIN chunk_id="genericdetailpage_module_header_1783930597" type="module_header" identity="imports" parent="none"]
+// CIL[DOC-MACRO purpose="Import React hooks and routing components for detail page"]
+// CIL[DOC-RESPONSIBILITY responsibility="Provide state management and navigation dependencies"]
+// CIL[DOC-CONTEXT module="generic-detail-page" layer="frontend-component" 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/components/ui/dialog.tsx\",\"\\\"]"]
+// CIL[DOC-CONTRACT inputs="none" outputs="Imported modules" errors="none" side_effects="none"]
+// CIL[DOC-MICRO logic_summary="Imports React hooks, routing components, and entity record hook" 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-component. 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/components/ui/dialog.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, useSearchParams, useNavigate } from 'react-router-dom'
 import { useEntityRecord } from '../../hooks/useEntityRecord'
 import { DataDetailHeader } from '../runtime/DataDetailHeader'
 import { SchemaDetailForm } from '../runtime/SchemaDetailForm'
-
+// CIL[END chunk_id="genericdetailpage_module_header_1783930597"]
+// CIL[BEGIN chunk_id="genericdetailpage_genericdetailpageprops_1783930597" type="interface" identity="GenericDetailPageProps" parent="none"]
+// CIL[DOC-MACRO purpose="Define props interface for generic detail page component"]
+// CIL[DOC-RESPONSIBILITY responsibility="Specify configuration for schema-driven detail display"]
+// CIL[DOC-CONTEXT module="generic-detail-page" layer="frontend-component" related_files="[\"custom/apps/portal/pages/ContentPage.tsx\",\".framework/src/pages/admin/TypeDetailPage.tsx\",\"custom/apps/cortex/pages/operations/OperationsDashboard.tsx\",\".framework/functions/_shared/schema-utils.ts\",\".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 with type slug, optional view, and creation mode flag" 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-component. Direct callers: 0. Direct calls: 0. Related files: custom/apps/portal/pages/ContentPage.tsx, .framework/src/pages/admin/TypeDetailPage.tsx, custom/apps/cortex/pages/operations/OperationsDashboard.tsx, .framework/functions/_shared/schema-utils.ts, .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 GenericDetailPageProps {
   typeSlug: string
   viewSlug?: string
   isCreating?: boolean
 }
-
-/**
- * Schema-driven detail page for the Generic App Shell.
- * Reuses the same runtime components as admin (DataDetailHeader, SchemaDetailForm)
- * but scoped to a specific type from the app's nav_items.
- */
+// CIL[END chunk_id="genericdetailpage_genericdetailpageprops_1783930597"]
+// CIL[BEGIN chunk_id="genericdetailpage_genericdetailpage_1783930597" type="function" identity="GenericDetailPage" parent="none"]
+// CIL[DOC-LEARNING topic="runtime-type:generic/detail_view" content="GenericDetailPage renders record.design_schema.views.default_detail.sections. Each section has a title and a fields map. field.system=true means the value is read from the record row; otherwise from record.data. FieldRenderer uses field.data_type and the view's display_type to choose the widget."]
+// CIL[DOC-NOTE type="design_schema_caveat" content="Without views.default_detail or fields missing from the schema, the detail page will be blank. The page falls back to useSchemaRecord defaults only for new records."]
+// CIL[DOC-MACRO purpose="Schema-driven detail page with form for create/edit/view"]
+// CIL[DOC-RESPONSIBILITY responsibility="Handle CRUD operations and form state for entity records"]
+// CIL[DOC-CONTEXT module="generic-detail-page" layer="frontend-component" 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/IntegrationsPage.tsx\",\".framework/src/pages/admin/RolesPage.tsx\",\"\\\"]"]
+// CIL[DOC-CONTRACT inputs="none" outputs="JSX detail page with form" errors="Loading/saving errors" side_effects="Data fetching, form state management, navigation"]
+// CIL[DOC-MICRO logic_summary="Manages record CRUD, form state, edit modes, renders runtime components" 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-component. 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/IntegrationsPage.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 GenericDetailPage({ typeSlug, viewSlug, isCreating: forceCreate }: GenericDetailPageProps) {
   const { id } = useParams<{ id: string }>()
   const navigate = useNavigate()
@@ -48,21 +92,21 @@ export function GenericDetailPage({ typeSlug, viewSlug, isCreating: forceCreate
     deleting
   } = useEntityRecord('items', id, config)
 
-  // Extract schema and view from the record itself
+  
   const schema = record?.design_schema || null
   const resolvedDetailView = viewSlug
     ? schema?.views?.[viewSlug] || schema?.views?.default_detail
     : schema?.views?.default_detail
   const view = resolvedDetailView || null
 
-  // Derive display title
+  
   const displayField = schema?.display_field || config.displayField
   const FALLBACK_FIELDS = ['full_name', 'display_name', 'name', 'title', 'slug', 'email']
   const recordTitle = record?.[displayField]
     ?? FALLBACK_FIELDS.map(f => record?.[f]).find(v => v != null)
     ?? 'Untitled'
 
-  // Lifted form state
+  
   const [formData, setFormData] = useState<Record<string, any>>({})
 
   useEffect(() => {
@@ -198,3 +242,4 @@ export function GenericDetailPage({ typeSlug, viewSlug, isCreating: forceCreate
     </div>
   )
 }
+// CIL[END chunk_id="genericdetailpage_genericdetailpage_1783930597"]

package/.framework/src/components/app-shell/GenericListPage.tsx

@@ -1,32 +1,77 @@
+
+
+
+
+// CIL[BEGIN chunk_id="genericlistpage_module_header_1783930597" type="module_header" identity="imports" parent="none"]
+// CIL[DOC-MACRO purpose="Import hooks and runtime components for generic list page"]
+// CIL[DOC-RESPONSIBILITY responsibility="Provide data fetching and UI rendering dependencies"]
+// CIL[DOC-CONTEXT module="generic-list-page" layer="frontend-component" 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/components/ui/dialog.tsx\",\"\\\"]"]
+// CIL[DOC-CONTRACT inputs="none" outputs="Imported modules" errors="none" side_effects="none"]
+// CIL[DOC-MICRO logic_summary="Imports schema hook, entity list hook, and runtime 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-component. 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/components/ui/dialog.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 { useListSchema } from '../../hooks/useListSchema'
 import { useEntityList } from '../../hooks/useEntityList'
 import { DataHeader } from '../runtime/DataHeader'
 import { DataStats } from '../runtime/DataStats'
 import { DataFilters } from '../runtime/DataFilters'
 import { DataTable } from '../runtime/DataTable'
-
+import { PageInstructions } from '../admin/PageInstructions'
+// CIL[END chunk_id="genericlistpage_module_header_1783930597"]
+// CIL[BEGIN chunk_id="genericlistpage_genericlistpageprops_1783930597" type="interface" identity="GenericListPageProps" parent="none"]
+// CIL[DOC-MACRO purpose="Define props interface for generic list page component"]
+// CIL[DOC-RESPONSIBILITY responsibility="Specify configuration for schema-driven list display"]
+// CIL[DOC-CONTEXT module="generic-list-page" layer="frontend-component" related_files="[\"custom/apps/portal/pages/ContentPage.tsx\",\"custom/apps/cortex/pages/operations/OperationsDashboard.tsx\",\".framework/src/pages/admin/TypeDetailPage.tsx\",\".framework/functions/_shared/schema-utils.ts\",\".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 with type slug, view configuration, and routing paths" 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-component. 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/functions/_shared/schema-utils.ts, .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 GenericListPageProps {
   typeSlug: string
   viewSlug?: string
   appPrefix: string
   detailPath: string
 }
-
-/**
- * Schema-driven list page for the Generic App Shell.
- * Resolves the type's design_schema and renders using the specified view
- * (or default_list if not specified).
- */
+// CIL[END chunk_id="genericlistpage_genericlistpageprops_1783930597"]
+// CIL[BEGIN chunk_id="genericlistpage_genericlistpage_1783930597" type="function" identity="GenericListPage" parent="none"]
+// CIL[DOC-LEARNING topic="runtime-type:generic/list_view" content="GenericListPage uses record.design_schema.views.default_list with type list and display table/card/board. It reads fields map for display_type, sortable, and searchable. It also uses default_sort, stats, filters, and group_by when present."]
+// CIL[DOC-NOTE type="design_schema_caveat" content="A missing default_list view causes the list to render no columns unless useListSchema falls back to the types table. display_type must be one FieldRenderer recognizes or the cell falls back to text."]
+// CIL[DOC-MACRO purpose="Schema-driven list page with data table and filters"]
+// CIL[DOC-RESPONSIBILITY responsibility="Render list view based on type schema and view configuration"]
+// CIL[DOC-CONTEXT module="generic-list-page" layer="frontend-component" related_files="[\"custom/apps/portal/pages/ContentPage.tsx\",\"custom/apps/cortex/pages/operations/OperationsDashboard.tsx\",\".framework/src/pages/admin/IntegrationsPage.tsx\",\".framework/migrations/015_simplify_apps_table.sql\",\".framework/src/pages/admin/TypeDetailPage.tsx\",\"\\\"]"]
+// CIL[DOC-CONTRACT inputs="none" outputs="JSX list page with data table" errors="Schema loading errors" side_effects="Data fetching, renders UI components"]
+// CIL[DOC-MICRO logic_summary="Resolves schema and view, builds config, fetches data, renders runtime components" 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-component. 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/IntegrationsPage.tsx, .framework/migrations/015_simplify_apps_table.sql, .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"]
 export function GenericListPage({ typeSlug, viewSlug, appPrefix, detailPath }: GenericListPageProps) {
   const resolvedViewSlug = viewSlug || 'default_list'
 
-  // Resolve schema and view — uses the same hook as admin runtime
+  
   const { schema, view, loading: schemaLoading, error: schemaError } = useListSchema({
     entity: 'items',
     viewSlug: resolvedViewSlug
   })
 
-  // Build config from resolved schema + view
+  
   const config = view && schema ? {
     entity: 'items',
     typeSlug,
@@ -86,6 +131,27 @@ export function GenericListPage({ typeSlug, viewSlug, appPrefix, detailPath }: G
         newButtonHref={`${appPrefix}/${detailPath}/new`}
       />
 
+      <PageInstructions
+        sections={[
+          {
+            title: 'What this page is for',
+            content: `This page lists all ${typeSlug} records for this app. It displays the stored records, their field values, and current status based on the app type schema.`,
+          },
+          {
+            title: 'How to find records',
+            content: `Use the filters above the table to narrow results. Click any column header to sort ascending or descending. The available columns and filters are defined by the type's design schema.`,
+          },
+          {
+            title: 'How to create, view, and edit records',
+            content: `Click the New button in the top-right to create a new ${typeSlug}. Click any row to open its detail view. From the detail view you can edit field values or delete the record. Permissions may restrict which actions are available to your role.`,
+          },
+          {
+            title: 'Understanding the stats',
+            content: `The cards above the table show summary counts and key metrics for this record type. Use them to quickly assess volume and status before drilling into the list.`,
+          },
+        ]}
+      />
+
       <DataStats
         stats={config.list.stats}
         data={data}
@@ -114,3 +180,4 @@ export function GenericListPage({ typeSlug, viewSlug, appPrefix, detailPath }: G
     </div>
   )
 }
+// CIL[END chunk_id="genericlistpage_genericlistpage_1783930597"]

package/.framework/src/components/app-sidebar.tsx

@@ -1,3 +1,22 @@
+
+
+
+
+// CIL[BEGIN chunk_id="app-sidebar_module_header_1783930597" type="module_header" identity="imports" parent="none"]
+// CIL[DOC-MACRO purpose="Import React and UI components for sidebar navigation"]
+// CIL[DOC-RESPONSIBILITY responsibility="Provide all external dependencies for the sidebar component"]
+// CIL[DOC-CONTEXT module="app-sidebar" layer="frontend-component" related_files="[\".framework/src/components/layout/Sidebar.tsx\",\"custom/apps/cortex/pages/operations/OperationsDashboard.tsx\",\"custom/apps/portal/pages/ContentPage.tsx\",\".framework/src/components/ui/dialog.tsx\",\".framework/src/pages/admin/TypeDetailPage.tsx\",\"\\\"]"]
+// CIL[DOC-CONTRACT inputs="none" outputs="Imported modules" errors="none" side_effects="none"]
+// CIL[DOC-MICRO logic_summary="Imports React, UI components, and icons needed for sidebar" 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-component. Direct callers: 0. Direct calls: 0. Related files: .framework/src/components/layout/Sidebar.tsx, custom/apps/cortex/pages/operations/OperationsDashboard.tsx, custom/apps/portal/pages/ContentPage.tsx, .framework/src/components/ui/dialog.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 * as React from "react"
 
 import { SearchForm } from "./search-form"
@@ -20,8 +39,21 @@ import {
   SidebarRail,
 } from "./ui/sidebar"
 import { GalleryVerticalEndIcon, PlusIcon, MinusIcon } from "lucide-react"
-
-// This is sample data.
+// CIL[END chunk_id="app-sidebar_module_header_1783930597"]
+// CIL[BEGIN chunk_id="app-sidebar_data_1783930597" type="constant" identity="data" parent="none"]
+// CIL[DOC-MACRO purpose="Define navigation structure for documentation sidebar"]
+// CIL[DOC-RESPONSIBILITY responsibility="Provide hierarchical navigation data with sections and items"]
+// CIL[DOC-CONTEXT module="app-sidebar" layer="frontend-component" related_files="[\".framework/src/components/layout/Sidebar.tsx\",\".framework/src/pages/admin/IntegrationsPage.tsx\",\".framework/functions/_shared/principal.ts\",\".framework/functions/_shared/schema-utils.ts\",\".framework/src/pages/admin/TypeDetailPage.tsx\",\"\\\"]"]
+// CIL[DOC-CONTRACT inputs="none" outputs="Navigation data object" errors="none" side_effects="none"]
+// CIL[DOC-MICRO logic_summary="Static navigation tree with Getting Started, Build Your Application, API Reference, Architecture, and Community sections" 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-component. Direct callers: 0. Direct calls: 0. Related files: .framework/src/components/layout/Sidebar.tsx, .framework/src/pages/admin/IntegrationsPage.tsx, .framework/functions/_shared/principal.ts, .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"]
 const data = {
   navMain: [
     {
@@ -161,7 +193,21 @@ const data = {
     },
   ],
 }
-
+// CIL[END chunk_id="app-sidebar_data_1783930597"]
+// CIL[BEGIN chunk_id="app-sidebar_appsidebar_1783930597" type="function" identity="AppSidebar" parent="none"]
+// CIL[DOC-MACRO purpose="Render main navigation sidebar with collapsible sections"]
+// CIL[DOC-RESPONSIBILITY responsibility="Create sidebar UI with header, navigation items, and search"]
+// CIL[DOC-CONTEXT module="app-sidebar" layer="frontend-component" related_files="[\".framework/src/components/layout/Sidebar.tsx\",\"custom/apps/portal/pages/ContentPage.tsx\",\".framework/functions/_shared/schema-utils.ts\",\".framework/src/pages/admin/RolesPage.tsx\",\".framework/src/components/ui/dialog.tsx\",\"\\\"]"]
+// CIL[DOC-CONTRACT inputs="none" outputs="JSX sidebar component" errors="none" side_effects="Renders navigation UI"]
+// CIL[DOC-MICRO logic_summary="Maps navigation data to collapsible sidebar sections with icons and active states" 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-component. Direct callers: 0. Direct calls: 0. Related files: .framework/src/components/layout/Sidebar.tsx, custom/apps/portal/pages/ContentPage.tsx, .framework/functions/_shared/schema-utils.ts, .framework/src/pages/admin/RolesPage.tsx, .framework/src/components/ui/dialog.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 AppSidebar({ ...props }: React.ComponentProps<typeof Sidebar>) {
   return (
     <Sidebar {...props}>
@@ -226,3 +272,4 @@ export function AppSidebar({ ...props }: React.ComponentProps<typeof Sidebar>) {
     </Sidebar>
   )
 }
+// CIL[END chunk_id="app-sidebar_appsidebar_1783930597"]

package/.framework/src/components/auth/ProtectedRoute.tsx

@@ -1,55 +1,62 @@
-/**
- * @module src/components/auth/ProtectedRoute
- * @audience installer
- * @layer frontend-component
- * @stability stable
- *
- * React Router route guard that enforces authentication and optional
- * system-admin role checks. Wrap any `<Route>` element that requires
- * a logged-in user.
- *
- * **Auth check:** If `AuthContext.user` is null (not yet logged in or
- * session expired), redirects to `/login` using `<Navigate replace>`.
- *
- * **System-admin check:** When `requireSystemAdmin=true`, verifies that
- * `user.roles` includes `'system_admin'`. On failure it renders an
- * access-denied screen rather than redirecting, to avoid redirect loops.
- *
- * @example
- * ```tsx
- * <Route path="/admin" element={
- *   <ProtectedRoute requireSystemAdmin>
- *     <AdminLayout />
- *   </ProtectedRoute>
- * } />
- * ```
- *
- * @seeAlso src/contexts/AuthContext.tsx
- */
 
+
+
+
+
+
+
+// CIL[BEGIN chunk_id="protectedroute_module_header_1783930597" type="module_header" identity="imports" parent="none"]
+// CIL[DOC-MACRO purpose="Import React and routing components for authentication"]
+// CIL[DOC-RESPONSIBILITY responsibility="Provide core dependencies for route protection"]
+// CIL[DOC-CONTEXT module="protected-route" layer="frontend-component" 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/TypeDetailPage.tsx\",\".framework/functions/_shared/principal.ts\",\"\\\"]"]
+// CIL[DOC-CONTRACT inputs="none" outputs="Imported modules" errors="none" side_effects="none"]
+// CIL[DOC-MICRO logic_summary="Imports React, Navigate for routing, and useAuth hook" 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-component. 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/TypeDetailPage.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 { Navigate } from 'react-router-dom'
 import { useAuth } from '../../contexts/AuthContext'
-
-/**
- * Props for `ProtectedRoute`.
- *
- * @prop children - The protected route content
- * @prop requireSystemAdmin - If true, also requires the `system_admin` role
- */
+// CIL[END chunk_id="protectedroute_module_header_1783930597"]
+// CIL[BEGIN chunk_id="protectedroute_protectedrouteprops_1783930597" type="interface" identity="ProtectedRouteProps" parent="none"]
+// CIL[DOC-MACRO purpose="Define props interface for route protection component"]
+// CIL[DOC-RESPONSIBILITY responsibility="Specify configurable options for protected routes"]
+// CIL[DOC-CONTEXT module="protected-route" layer="frontend-component" related_files="[\".framework/functions/_shared/schema-utils.ts\",\".framework/src/components/ui/dialog.tsx\",\"custom/apps/portal/pages/ContentPage.tsx\",\".framework/functions/_shared/principal.ts\",\"custom/apps/cortex/pages/operations/OperationsDashboard.tsx\",\"\\\"]"]
+// CIL[DOC-CONTRACT inputs="none" outputs="Type definition" errors="none" side_effects="none"]
+// CIL[DOC-MICRO logic_summary="Interface with optional system admin requirement flag" 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-component. Direct callers: 0. Direct calls: 0. Related files: .framework/functions/_shared/schema-utils.ts, .framework/src/components/ui/dialog.tsx, custom/apps/portal/pages/ContentPage.tsx, .framework/functions/_shared/principal.ts, 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 ProtectedRouteProps {
   children: React.ReactNode
   requireSystemAdmin?: boolean
 }
-
-/**
- * Route guard component.
- *
- * @param props - `ProtectedRouteProps`
- * @returns `children` when authorised, a redirect to `/login` when
- *   unauthenticated, or an access-denied screen when role check fails
- * @sideEffects none (navigation is declarative via `<Navigate>`)
- */
+// CIL[END chunk_id="protectedroute_protectedrouteprops_1783930597"]
+// CIL[BEGIN chunk_id="protectedroute_protectedroute_1783930597" type="function" identity="ProtectedRoute" parent="none"]
+// CIL[DOC-MACRO purpose="Route guard component enforcing authentication and role checks"]
+// CIL[DOC-RESPONSIBILITY responsibility="Protect routes from unauthorized access with optional admin validation"]
+// CIL[DOC-CONTEXT module="protected-route" layer="frontend-component" related_files="[\".framework/src/pages/admin/RolesPage.tsx\",\"custom/apps/portal/pages/ContentPage.tsx\",\".framework/src/components/ui/dialog.tsx\",\"\\\"]"]
+// CIL[DOC-CONTRACT inputs="none" outputs="Protected content or redirect/denial UI" errors="none" side_effects="Navigation redirects, renders access denied UI"]
+// CIL[DOC-MICRO logic_summary="Checks user auth state and optional system_admin role, redirects to login or shows access denied" 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-component. Direct callers: 0. Direct calls: 0. Related files: .framework/src/pages/admin/RolesPage.tsx, custom/apps/portal/pages/ContentPage.tsx, .framework/src/components/ui/dialog.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 ProtectedRoute({ children, requireSystemAdmin = false }: ProtectedRouteProps) {
   const { user } = useAuth()
 
@@ -58,7 +65,7 @@ export function ProtectedRoute({ children, requireSystemAdmin = false }: Protect
   }
 
   if (requireSystemAdmin && !user.roles?.includes('system_admin')) {
-    // Show access denied message instead of redirect to avoid loops
+    
     return (
       <div className="min-h-screen flex items-center justify-center bg-slate-50">
         <div className="text-center p-8">
@@ -86,3 +93,4 @@ export function ProtectedRoute({ children, requireSystemAdmin = false }: Protect
 
   return <>{children}</>
 }
+// CIL[END chunk_id="protectedroute_protectedroute_1783930597"]