spine-framework 0.3.125 → 0.3.126

package/.framework/src/components/admin/AdminListPage.tsx

@@ -1,3 +1,21 @@
+
+
+
+// CIL[BEGIN chunk_id="AdminListPage_module_header_1783931090" type="module_header" identity="imports" parent="none"]
+// CIL[DOC-MACRO purpose="Import React and UI components for admin list page"]
+// CIL[DOC-RESPONSIBILITY responsibility="Manage all external module imports for admin list page"]
+// CIL[DOC-CONTEXT module="AdminListPage" layer="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\",\"\\\"]"]
+// CIL[DOC-CONTRACT inputs="none" outputs="Imported modules and components" errors="Import failures" side_effects="Module loading"]
+// CIL[DOC-MICRO logic_summary="Imports React, UI components, icons, and utility functions" 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: 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, \."]
+// 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, { ReactNode } from 'react'
 import { Button } from '../ui/button'
 import { Card, CardContent } from '../ui/card'
@@ -7,11 +25,27 @@ import { Skeleton } from '../ui/skeleton'
 import { Search } from 'lucide-react'
 import { LucideIcon } from 'lucide-react'
 import { AdminStatsCard } from './AdminStatsCard'
+import { PageInstructions } from './PageInstructions'
 import { cn } from '../../lib/utils'
-
+// CIL[END chunk_id="AdminListPage_module_header_1783931090"]
+// CIL[BEGIN chunk_id="AdminListPage_interface_1783931090" type="interface" identity="AdminListPageProps" parent="none"]
+// CIL[DOC-MACRO purpose="Define props interface for AdminListPage component"]
+// CIL[DOC-RESPONSIBILITY responsibility="Type definition for admin list page properties"]
+// CIL[DOC-CONTEXT module="AdminListPage" layer="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 interface" errors="none" side_effects="none"]
+// CIL[DOC-MICRO logic_summary="Defines props for title, stats, search, filters, content, and loading states" notable_decisions="[]"]
+// CIL[DOC-CONFIDENCE pass="second" score="1.00" flags="none"]
+// CIL[DOC-STABILITY stability="stable"]
+// CIL[DOC-VECTOR type="context" content="Layer: 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 AdminListPageProps {
   title: string
   description: string
+  noPageInstructions?: boolean
   newButtonText?: string
   newButtonHref?: string
   onNewClick?: () => void
@@ -37,10 +71,25 @@ interface AdminListPageProps {
   emptyMessage?: string
   emptyIcon?: LucideIcon
 }
-
+// CIL[END chunk_id="AdminListPage_interface_1783931090"]
+// CIL[BEGIN chunk_id="AdminListPage_adminlistpage_1783931090" type="function" identity="AdminListPage" parent="none"]
+// CIL[DOC-MACRO purpose="Admin list page component with stats, search, filters, and content"]
+// CIL[DOC-RESPONSIBILITY responsibility="Render comprehensive admin list interface with all features"]
+// CIL[DOC-CONTEXT module="AdminListPage" layer="component" related_files="[\"custom/apps/portal/pages/ContentPage.tsx\",\".framework/src/pages/admin/TypeDetailPage.tsx\",\".framework/src/pages/admin/RolesPage.tsx\",\"custom/apps/cortex/pages/operations/OperationsDashboard.tsx\",\"\\\"]"]
+// CIL[DOC-CONTRACT inputs="none" outputs="Admin list page JSX" errors="Rendering errors" side_effects="UI rendering"]
+// CIL[DOC-MICRO logic_summary="Renders header, stats cards, search/filters, content with loading/error states" notable_decisions="['comprehensive_layout', 'loading_states']"]
+// CIL[DOC-CONFIDENCE pass="second" score="0.95" flags="none"]
+// CIL[DOC-STABILITY stability="stable"]
+// CIL[DOC-VECTOR type="context" content="Layer: component. Direct callers: 0. Direct calls: 0. Related files: custom/apps/portal/pages/ContentPage.tsx, .framework/src/pages/admin/TypeDetailPage.tsx, .framework/src/pages/admin/RolesPage.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"]
 export function AdminListPage({
   title,
   description,
+  noPageInstructions,
   newButtonText,
   newButtonHref = '#',
   onNewClick,
@@ -56,7 +105,6 @@ export function AdminListPage({
 }: AdminListPageProps) {
   return (
     <div className="space-y-6">
-      {/* Header */}
       <div className="flex justify-between items-center">
         <div>
           <h1 className="text-xl font-semibold">{title}</h1>
@@ -70,7 +118,29 @@ export function AdminListPage({
         )}
       </div>
 
-      {/* Stats Cards */}
+      {!noPageInstructions && (
+        <PageInstructions
+          sections={[
+            {
+              title: 'What this page is for',
+              content: `This page is the administrative list for ${title.toLowerCase()}. It shows all records in the system, their current state, and provides tools to search, filter, and create new records.`,
+            },
+            {
+              title: 'How to find records',
+              content: `Use the search field at the top of the list to look for records by name or keyword. Use the filter dropdowns to narrow the list by status, type, or other categories. Click any column header to sort ascending or descending.`,
+            },
+            {
+              title: 'How to create, view, and edit records',
+              content: `${newButtonText ? `Click the ${newButtonText} button in the top-right to create a new record. ` : ''}Click any row in the table to open its detail page. From the detail page you can review all fields, edit the record, and, if allowed, delete it. Deleting a record usually cannot be undone.`,
+            },
+            {
+              title: 'Understanding the stats',
+              content: `The summary cards above the table show the most important counts for this record type. Use them as a quick health check or to spot trends before drilling into the list.`,
+            },
+          ]}
+        />
+      )}
+
       <div className="grid grid-cols-1 gap-5 sm:grid-cols-2 lg:grid-cols-4">
         {statsCards.map((stat, index) => (
           <AdminStatsCard
@@ -83,11 +153,9 @@ export function AdminListPage({
         ))}
       </div>
 
-      {/* Search and Filters */}
       <Card>
         <CardContent className="p-4">
           <div className="flex flex-col sm:flex-row gap-4">
-            {/* Search */}
             {onSearchChange && (
               <div className="flex-1">
                 <div className="relative">
@@ -102,7 +170,6 @@ export function AdminListPage({
               </div>
             )}
 
-            {/* Filters */}
             {filters.map((filter, index) => (
               <div key={index} className="sm:w-48">
                 <Select value={filter.value} onValueChange={filter.onChange}>
@@ -123,7 +190,6 @@ export function AdminListPage({
         </CardContent>
       </Card>
 
-      {/* Content */}
       <Card>
         {loading ? (
           <div className="p-8 space-y-4">
@@ -149,3 +215,4 @@ export function AdminListPage({
     </div>
   )
 }
+// CIL[END chunk_id="AdminListPage_adminlistpage_1783931090"]

package/.framework/src/components/admin/AdminSidebar.tsx

@@ -1,12 +1,21 @@
-/**
- * @module src/components/admin/AdminSidebar
- * @audience installer
- * @layer frontend-component
- * @stability stable
- *
- * Admin sidebar with proper sections, React Router navigation, and active link highlighting.
- */
 
+
+
+// CIL[BEGIN chunk_id="AdminSidebar_module_header_1783931090" type="module_header" identity="imports" parent="none"]
+// CIL[DOC-MACRO purpose="Import React, routing, and UI components for admin sidebar"]
+// CIL[DOC-RESPONSIBILITY responsibility="Manage all external module imports for admin sidebar"]
+// CIL[DOC-CONTEXT module="AdminSidebar" layer="component" related_files="[\"custom/apps/cortex/pages/operations/OperationsDashboard.tsx\",\".framework/src/components/ui/dialog.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 and icons" errors="Import failures" side_effects="Module loading"]
+// CIL[DOC-MICRO logic_summary="Imports React, routing, Lucide icons, and sidebar 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: component. Direct callers: 0. Direct calls: 0. Related files: custom/apps/cortex/pages/operations/OperationsDashboard.tsx, .framework/src/components/ui/dialog.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 * as React from "react"
 import { Link, useLocation } from "react-router-dom"
 import { 
@@ -29,8 +38,12 @@ import {
   Shield,
   MessageSquare,
   Key,
+  Truck,
   TestTube,
-  UserPlus
+  UserPlus,
+  BookOpen,
+  ChevronRight,
+  ChevronDown
 } from "lucide-react"
 import {
   Sidebar,
@@ -43,11 +56,28 @@ import {
   SidebarMenu,
   SidebarMenuButton,
   SidebarMenuItem,
+  SidebarMenuSub,
+  SidebarMenuSubButton,
+  SidebarMenuSubItem,
   SidebarRail,
 } from "../ui/sidebar"
 import { Button } from "../ui/button"
-
-// Navigation sections with correct admin URLs
+import { Collapsible, CollapsibleContent, CollapsibleTrigger } from "../ui/collapsible"
+// CIL[END chunk_id="AdminSidebar_module_header_1783931090"]
+// CIL[BEGIN chunk_id="AdminSidebar_navigation_sections_1783931090" type="navigation_data" identity="navigation_sections" parent="none"]
+// CIL[DOC-MACRO purpose="Define navigation structure for admin interface"]
+// CIL[DOC-RESPONSIBILITY responsibility="Configure sidebar navigation sections and items"]
+// CIL[DOC-CONTEXT module="AdminSidebar" layer="component" related_files="[\".framework/src/pages/admin/IntegrationsPage.tsx\",\".framework/functions/_shared/schema-utils.ts\",\".framework/src/pages/admin/TypeDetailPage.tsx\",\".framework/functions/_shared/principal.ts\",\".framework/src/pages/admin/RolesPage.tsx\",\"\\\"]"]
+// CIL[DOC-CONTRACT inputs="none" outputs="Navigation data structure" errors="none" side_effects="none"]
+// CIL[DOC-MICRO logic_summary="Organizes admin sections: configs, access, runtime, observability, testing" notable_decisions="['section_organization', 'icon_mapping']"]
+// CIL[DOC-CONFIDENCE pass="second" score="0.95" flags="none"]
+// CIL[DOC-STABILITY stability="stable"]
+// CIL[DOC-VECTOR type="context" content="Layer: component. Direct callers: 0. Direct calls: 0. Related files: .framework/src/pages/admin/IntegrationsPage.tsx, .framework/functions/_shared/schema-utils.ts, .framework/src/pages/admin/TypeDetailPage.tsx, .framework/functions/_shared/principal.ts, .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"]
 const navigationSections = [
   {
     title: "Configs",
@@ -57,12 +87,18 @@ const navigationSections = [
       { title: "Pipelines", url: "/spine-framework/admin/configs/pipelines", icon: Activity },
       { title: "Triggers", url: "/spine-framework/admin/configs/triggers", icon: AlertTriangle },
       { title: "AI Agents", url: "/spine-framework/admin/configs/ai-agents", icon: Brain },
-      { title: "Embeddings", url: "/spine-framework/admin/configs/embeddings", icon: Cpu },
       { title: "Timers", url: "/spine-framework/admin/configs/timers", icon: Timer },
-      { title: "Integrations", url: "/spine-framework/admin/configs/integrations", icon: Puzzle },
+      {
+        title: "Integration Broker",
+        icon: Puzzle,
+        children: [
+          { title: "Integrations", url: "/spine-framework/admin/configs/integrations", icon: Puzzle },
+          { title: "API Keys", url: "/spine-framework/admin/configs/api-keys", icon: Key },
+          { title: "Deliveries", url: "/spine-framework/admin/configs/deliveries", icon: Truck },
+        ]
+      },
       { title: "Roles", url: "/spine-framework/admin/configs/roles", icon: Shield },
       { title: "Prompts", url: "/spine-framework/admin/configs/prompts", icon: MessageSquare },
-      { title: "API Keys", url: "/spine-framework/admin/configs/api-keys", icon: Key },
     ]
   },
   {
@@ -99,13 +135,41 @@ const navigationSections = [
     items: [
       { title: "Test Runs", url: "/spine-framework/admin/testing", icon: TestTube },
     ]
+  },
+  {
+    title: "KB Engine",
+    items: [
+      { title: "Knowledge Base", url: "/spine-framework/admin/kb/kb-spine-public", icon: BookOpen },
+      { title: "Embeddings", url: "/spine-framework/admin/kb/embeddings", icon: Cpu },
+    ]
+  },
+  {
+    title: "CIL",
+    items: [
+      { title: "Projects", url: "/spine-framework/admin/cil", icon: Brain },
+      { title: "Search", url: "/spine-framework/admin/cil/search", icon: FileSearch },
+      { title: "Agent", url: "/spine-framework/admin/cil/agent", icon: MessageSquare },
+    ]
   }
 ]
-
+// CIL[END chunk_id="AdminSidebar_navigation_sections_1783931090"]
+// CIL[BEGIN chunk_id="AdminSidebar_adminsidebar_1783931090" type="function" identity="AdminSidebar" parent="none"]
+// CIL[DOC-MACRO purpose="Admin sidebar component with navigation and active state"]
+// CIL[DOC-RESPONSIBILITY responsibility="Render sidebar navigation with active link highlighting"]
+// CIL[DOC-CONTEXT module="AdminSidebar" layer="component" related_files="[\"custom/apps/portal/pages/ContentPage.tsx\",\".framework/src/components/ui/dialog.tsx\",\".framework/src/pages/admin/RolesPage.tsx\",\".framework/src/pages/admin/TypeDetailPage.tsx\",\"\\\"]"]
+// CIL[DOC-CONTRACT inputs="none" outputs="Admin sidebar JSX" errors="none" side_effects="Navigation rendering"]
+// CIL[DOC-MICRO logic_summary="Handles active state, renders brand header, navigation sections, footer" notable_decisions="['active_link_detection', 'brand_header']"]
+// CIL[DOC-CONFIDENCE pass="second" score="0.95" flags="none"]
+// CIL[DOC-STABILITY stability="stable"]
+// CIL[DOC-VECTOR type="context" content="Layer: component. Direct callers: 0. Direct calls: 0. Related files: custom/apps/portal/pages/ContentPage.tsx, .framework/src/components/ui/dialog.tsx, .framework/src/pages/admin/RolesPage.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"]
 export function AdminSidebar({ ...props }: React.ComponentProps<typeof Sidebar>) {
   const location = useLocation()
 
-  // Check if a URL is active (exact match or starts with path)
   const isActive = (url: string) => {
     return location.pathname === url || location.pathname.startsWith(url + '/')
   }
@@ -113,7 +177,6 @@ export function AdminSidebar({ ...props }: React.ComponentProps<typeof Sidebar>)
   return (
     <Sidebar {...props}>
       <SidebarHeader>
-        {/* Brand Header */}
         <SidebarMenu>
           <SidebarMenuItem>
             <SidebarMenuButton size="lg" asChild>
@@ -130,7 +193,6 @@ export function AdminSidebar({ ...props }: React.ComponentProps<typeof Sidebar>)
           </SidebarMenuItem>
         </SidebarMenu>
 
-        {/* Quick Create Button */}
         <SidebarGroup className="py-2">
           <Button className="w-full" size="sm">
             <PlusIcon className="mr-2 h-4 w-4" />
@@ -140,25 +202,74 @@ export function AdminSidebar({ ...props }: React.ComponentProps<typeof Sidebar>)
       </SidebarHeader>
 
       <SidebarContent>
-        {navigationSections.map((section) => (
-          <SidebarGroup key={section.title}>
-            <SidebarGroupLabel>{section.title}</SidebarGroupLabel>
-            <SidebarGroupContent>
-              <SidebarMenu>
-                {section.items.map((item) => (
-                  <SidebarMenuItem key={item.title}>
-                    <SidebarMenuButton asChild isActive={isActive(item.url)}>
-                      <Link to={item.url}>
-                        <item.icon className="h-4 w-4" />
-                        <span>{item.title}</span>
-                      </Link>
-                    </SidebarMenuButton>
+        {navigationSections.map((section) => {
+          const sectionActive = section.items.some((item: any) =>
+            isActive(item.url) || (item.children && item.children.some((child: any) => isActive(child.url)))
+          )
+          return (
+            <SidebarGroup key={section.title} className="py-0">
+              <Collapsible defaultOpen={sectionActive} className="group/collapsible w-full">
+                <SidebarMenu>
+                  <SidebarMenuItem>
+                    <CollapsibleTrigger asChild>
+                      <SidebarMenuButton className="font-semibold text-sm">
+                        <span>{section.title}</span>
+                        <ChevronRight className="ml-auto h-4 w-4 transition-transform group-data-[state=open]/collapsible:rotate-90" />
+                      </SidebarMenuButton>
+                    </CollapsibleTrigger>
                   </SidebarMenuItem>
-                ))}
-              </SidebarMenu>
-            </SidebarGroupContent>
-          </SidebarGroup>
-        ))}
+                </SidebarMenu>
+                <CollapsibleContent>
+                  <SidebarGroupContent>
+                    <SidebarMenu>
+                      {section.items.map((item: any) => (
+                        item.children ? (
+                          <SidebarMenuItem key={item.title}>
+                            <Collapsible
+                              defaultOpen={item.children.some((child: any) => isActive(child.url))}
+                              className="group/collapsible w-full"
+                            >
+                              <CollapsibleTrigger asChild>
+                                <SidebarMenuButton>
+                                  <item.icon className="h-4 w-4" />
+                                  <span>{item.title}</span>
+                                  <ChevronRight className="ml-auto h-4 w-4 transition-transform group-data-[state=open]/collapsible:rotate-90" />
+                                </SidebarMenuButton>
+                              </CollapsibleTrigger>
+                              <CollapsibleContent>
+                                <SidebarMenuSub>
+                                  {item.children.map((child: any) => (
+                                    <SidebarMenuSubItem key={child.title}>
+                                      <SidebarMenuSubButton asChild isActive={isActive(child.url)}>
+                                        <Link to={child.url}>
+                                          <child.icon className="h-4 w-4" />
+                                          <span>{child.title}</span>
+                                        </Link>
+                                      </SidebarMenuSubButton>
+                                    </SidebarMenuSubItem>
+                                  ))}
+                                </SidebarMenuSub>
+                              </CollapsibleContent>
+                            </Collapsible>
+                          </SidebarMenuItem>
+                        ) : (
+                          <SidebarMenuItem key={item.title}>
+                            <SidebarMenuButton asChild isActive={isActive(item.url)}>
+                              <Link to={item.url}>
+                                <item.icon className="h-4 w-4" />
+                                <span>{item.title}</span>
+                              </Link>
+                            </SidebarMenuButton>
+                          </SidebarMenuItem>
+                        )
+                      ))}
+                    </SidebarMenu>
+                  </SidebarGroupContent>
+                </CollapsibleContent>
+              </Collapsible>
+            </SidebarGroup>
+          )
+        })}
       </SidebarContent>
 
       <SidebarFooter className="p-4">
@@ -171,3 +282,4 @@ export function AdminSidebar({ ...props }: React.ComponentProps<typeof Sidebar>)
     </Sidebar>
   )
 }
+// CIL[END chunk_id="AdminSidebar_adminsidebar_1783931090"]

package/.framework/src/components/admin/AdminStatsCard.tsx

@@ -1,42 +1,60 @@
-/**
- * @module src/components/admin/AdminStatsCard
- * @audience installer
- * @layer frontend-component
- * @stability stable
- *
- * Single stat card used in admin list page headers. Renders an icon,
- * a title, and a numeric or string value inside a white rounded panel.
- * Icon colour defaults to `'text-blue-500'` but can be overridden per card.
- *
- * @seeAlso src/components/admin/AdminListPage.tsx (mounts this component)
- */
 
+
+
+// CIL[BEGIN chunk_id="AdminStatsCard_module_header_1783931090" type="module_header" identity="imports" parent="none"]
+// CIL[DOC-MACRO purpose="Import React and UI components for stats card"]
+// CIL[DOC-RESPONSIBILITY responsibility="Manage all external module imports for stats card"]
+// CIL[DOC-CONTEXT module="AdminStatsCard" layer="component" related_files="[\"custom/apps/cortex/pages/operations/OperationsDashboard.tsx\",\"custom/apps/portal/pages/ContentPage.tsx\",\".framework/src/components/ui/dialog.tsx\",\".framework/src/components/ui/table-primitives.tsx\",\"\\\"]"]
+// CIL[DOC-CONTRACT inputs="none" outputs="Imported modules and types" errors="Import failures" side_effects="Module loading"]
+// CIL[DOC-MICRO logic_summary="Imports React, Lucide icon type, and card 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: component. Direct callers: 0. Direct calls: 0. Related files: custom/apps/cortex/pages/operations/OperationsDashboard.tsx, custom/apps/portal/pages/ContentPage.tsx, .framework/src/components/ui/dialog.tsx, .framework/src/components/ui/table-primitives.tsx, \."]
+// CIL[DOC-VECTOR type="blast_radius" content="Direct callers: 0. Total affected: 0."]
+// CIL[DOC-VECTOR type="configuration" content="No configuration dependencies."]
+// CIL[DOC-VECTOR type="constraint" content="No test paths identified."]
+// CIL[DOC-VECTOR type="implementation_pattern" content="" status="pending_human_input"]
+// CIL[DOC-VECTOR type="user_journey" content="" status="pending_human_input"]
 import React from 'react'
 import { LucideIcon } from 'lucide-react'
 import { Card, CardContent } from '../ui/card'
-
-/**
- * Props for `AdminStatsCard`.
- *
- * @prop title - Stat label
- * @prop value - Numeric or formatted string value to display
- * @prop icon - Lucide icon component
- * @prop iconColor - Tailwind text-colour class (default: `'text-blue-500'`)
- */
+// CIL[END chunk_id="AdminStatsCard_module_header_1783931090"]
+// CIL[BEGIN chunk_id="AdminStatsCard_interface_1783931090" type="interface" identity="AdminStatsCardProps" parent="none"]
+// CIL[DOC-MACRO purpose="Define props interface for AdminStatsCard component"]
+// CIL[DOC-RESPONSIBILITY responsibility="Type definition for stats card properties"]
+// CIL[DOC-CONTEXT module="AdminStatsCard" layer="component" related_files="[\".framework/functions/_shared/schema-utils.ts\",\".framework/src/components/ui/dialog.tsx\",\"custom/apps/portal/pages/ContentPage.tsx\",\".framework/src/components/ui/table-primitives.tsx\",\"\\\"]"]
+// CIL[DOC-CONTRACT inputs="none" outputs="Type interface" errors="none" side_effects="none"]
+// CIL[DOC-MICRO logic_summary="Defines title, value, icon, and optional icon color props" notable_decisions="[]"]
+// CIL[DOC-CONFIDENCE pass="second" score="1.00" flags="none"]
+// CIL[DOC-STABILITY stability="stable"]
+// CIL[DOC-VECTOR type="context" content="Layer: 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/src/components/ui/table-primitives.tsx, \."]
+// CIL[DOC-VECTOR type="blast_radius" content="Direct callers: 0. Total affected: 0."]
+// CIL[DOC-VECTOR type="configuration" content="No configuration dependencies."]
+// CIL[DOC-VECTOR type="constraint" content="No test paths identified."]
+// CIL[DOC-VECTOR type="implementation_pattern" content="" status="pending_human_input"]
+// CIL[DOC-VECTOR type="user_journey" content="" status="pending_human_input"]
 interface AdminStatsCardProps {
   title: string
   value: string | number
   icon: LucideIcon
   iconColor?: string
 }
-
-/**
- * Single stat card.
- *
- * @param props - `AdminStatsCardProps`
- * @returns White rounded card with icon and stat value
- * @sideEffects none (pure rendering)
- */
+// CIL[END chunk_id="AdminStatsCard_interface_1783931090"]
+// CIL[BEGIN chunk_id="AdminStatsCard_adminstatscard_1783931090" type="function" identity="AdminStatsCard" parent="none"]
+// CIL[DOC-MACRO purpose="Single stat card component with icon and value display"]
+// CIL[DOC-RESPONSIBILITY responsibility="Render individual statistics card with icon and formatted value"]
+// CIL[DOC-CONTEXT module="AdminStatsCard" layer="component" related_files="[\"custom/apps/portal/pages/ContentPage.tsx\",\".framework/src/pages/admin/RolesPage.tsx\",\".framework/src/components/ui/dialog.tsx\",\".framework/src/components/ui/table-primitives.tsx\",\"\\\"]"]
+// CIL[DOC-CONTRACT inputs="none" outputs="Stat card JSX" errors="none" side_effects="UI rendering"]
+// CIL[DOC-MICRO logic_summary="Renders card with icon, title, and value in horizontal layout" notable_decisions="['default_icon_color', 'horizontal_layout']"]
+// CIL[DOC-CONFIDENCE pass="second" score="0.95" flags="none"]
+// CIL[DOC-STABILITY stability="stable"]
+// CIL[DOC-VECTOR type="context" content="Layer: component. Direct callers: 0. Direct calls: 0. Related files: custom/apps/portal/pages/ContentPage.tsx, .framework/src/pages/admin/RolesPage.tsx, .framework/src/components/ui/dialog.tsx, .framework/src/components/ui/table-primitives.tsx, \."]
+// CIL[DOC-VECTOR type="blast_radius" content="Direct callers: 0. Total affected: 0."]
+// CIL[DOC-VECTOR type="configuration" content="No configuration dependencies."]
+// CIL[DOC-VECTOR type="constraint" content="No test paths identified."]
+// CIL[DOC-VECTOR type="implementation_pattern" content="" status="pending_human_input"]
+// CIL[DOC-VECTOR type="user_journey" content="" status="pending_human_input"]
 export function AdminStatsCard({ title, value, icon: Icon, iconColor = "text-primary" }: AdminStatsCardProps) {
   return (
     <Card>
@@ -60,3 +78,4 @@ export function AdminStatsCard({ title, value, icon: Icon, iconColor = "text-pri
     </Card>
   )
 }
+// CIL[END chunk_id="AdminStatsCard_adminstatscard_1783931090"]

package/.framework/src/components/admin/PageInstructions.tsx

@@ -0,0 +1,49 @@
+import * as React from 'react'
+import { ChevronDown } from 'lucide-react'
+import { Collapsible, CollapsibleContent, CollapsibleTrigger } from '../ui/collapsible'
+import { Card, CardContent } from '../ui/card'
+
+export interface PageInstructionsSection {
+  title: string
+  content: React.ReactNode
+}
+
+export interface PageInstructionsProps {
+  title?: string
+  description?: React.ReactNode
+  sections?: PageInstructionsSection[]
+}
+
+export function PageInstructions({
+  title = 'Page instructions',
+  description,
+  sections,
+}: PageInstructionsProps) {
+  if (!description && (!sections || sections.length === 0)) return null
+
+  return (
+    <Card>
+      <CardContent className="p-4">
+        <Collapsible>
+          <CollapsibleTrigger className="group flex w-full items-center justify-between text-sm font-medium text-slate-700">
+            <span>{title}</span>
+            <ChevronDown className="h-4 w-4 transition-transform group-data-[state=open]:rotate-180" />
+          </CollapsibleTrigger>
+          <CollapsibleContent className="space-y-4 pt-4">
+            {description && <div className="text-sm text-slate-600">{description}</div>}
+            {sections && sections.length > 0 && (
+              <div className="space-y-3">
+                {sections.map((section, i) => (
+                  <div key={i}>
+                    <div className="text-sm font-semibold text-slate-700">{section.title}</div>
+                    <div className="mt-1 text-sm text-slate-600">{section.content}</div>
+                  </div>
+                ))}
+              </div>
+            )}
+          </CollapsibleContent>
+        </Collapsible>
+      </CardContent>
+    </Card>
+  )
+}

package/.framework/src/components/admin/SortableTableHeader.tsx

@@ -1,7 +1,39 @@
+
+
+
+// CIL[BEGIN chunk_id="SortableTableHeader_module_header_1783931090" type="module_header" identity="imports" parent="none"]
+// CIL[DOC-MACRO purpose="Import React and UI components for sortable table header"]
+// CIL[DOC-RESPONSIBILITY responsibility="Manage all external module imports for sortable header"]
+// CIL[DOC-CONTEXT module="SortableTableHeader" layer="component" related_files="[\".framework/src/components/ui/table-primitives.tsx\",\".framework/migrations/015_simplify_apps_table.sql\",\"custom/apps/cortex/pages/operations/OperationsDashboard.tsx\",\"custom/apps/portal/pages/ContentPage.tsx\",\"\\\"]"]
+// CIL[DOC-CONTRACT inputs="none" outputs="Imported modules and icons" errors="Import failures" side_effects="Module loading"]
+// CIL[DOC-MICRO logic_summary="Imports React, chevron icons, and table head component" 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: component. Direct callers: 0. Direct calls: 0. Related files: .framework/src/components/ui/table-primitives.tsx, .framework/migrations/015_simplify_apps_table.sql, 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"]
 import React from 'react'
 import { ChevronUp, ChevronDown } from 'lucide-react'
 import { TableHead } from '../ui/table'
-
+// CIL[END chunk_id="SortableTableHeader_module_header_1783931090"]
+// CIL[BEGIN chunk_id="SortableTableHeader_interface_1783931090" type="interface" identity="SortableTableHeaderProps" parent="none"]
+// CIL[DOC-MACRO purpose="Define props interface for SortableTableHeader component"]
+// CIL[DOC-RESPONSIBILITY responsibility="Type definition for sortable header properties"]
+// CIL[DOC-CONTEXT module="SortableTableHeader" layer="component" related_files="[\".framework/functions/_shared/schema-utils.ts\",\".framework/src/components/ui/dialog.tsx\",\"custom/apps/portal/pages/ContentPage.tsx\",\".framework/src/components/ui/table-primitives.tsx\",\"\\\"]"]
+// CIL[DOC-CONTRACT inputs="none" outputs="Type interface" errors="none" side_effects="none"]
+// CIL[DOC-MICRO logic_summary="Defines title, sort key, current sort state, and sort callback props" notable_decisions="[]"]
+// CIL[DOC-CONFIDENCE pass="second" score="1.00" flags="none"]
+// CIL[DOC-STABILITY stability="stable"]
+// CIL[DOC-VECTOR type="context" content="Layer: 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/src/components/ui/table-primitives.tsx, \."]
+// CIL[DOC-VECTOR type="blast_radius" content="Direct callers: 0. Total affected: 0."]
+// CIL[DOC-VECTOR type="configuration" content="No configuration dependencies."]
+// CIL[DOC-VECTOR type="constraint" content="No test paths identified."]
+// CIL[DOC-VECTOR type="implementation_pattern" content="" status="pending_human_input"]
+// CIL[DOC-VECTOR type="user_journey" content="" status="pending_human_input"]
 interface SortableTableHeaderProps {
   title: string
   sortKey: string
@@ -9,7 +41,21 @@ interface SortableTableHeaderProps {
   currentSortDirection?: 'asc' | 'desc'
   onSort: (key: string) => void
 }
-
+// CIL[END chunk_id="SortableTableHeader_interface_1783931090"]
+// CIL[BEGIN chunk_id="SortableTableHeader_sortabletableheader_1783931090" type="function" identity="SortableTableHeader" parent="none"]
+// CIL[DOC-MACRO purpose="Sortable table header component with click-to-sort functionality"]
+// CIL[DOC-RESPONSIBILITY responsibility="Render header with sorting indicators and click handlers"]
+// CIL[DOC-CONTEXT module="SortableTableHeader" layer="component" related_files="[\".framework/src/components/ui/table-primitives.tsx\",\".framework/migrations/015_simplify_apps_table.sql\",\".framework/src/components/ui/dialog.tsx\",\"\\\"]"]
+// CIL[DOC-CONTRACT inputs="none" outputs="Sortable header JSX" errors="none" side_effects="Sort callback execution"]
+// CIL[DOC-MICRO logic_summary="Handles sort state, displays chevron indicators, manages click events" notable_decisions="['conditional_sort_indicators', 'click_to_sort']"]
+// CIL[DOC-CONFIDENCE pass="second" score="0.95" flags="none"]
+// CIL[DOC-STABILITY stability="stable"]
+// CIL[DOC-VECTOR type="context" content="Layer: component. Direct callers: 0. Direct calls: 0. Related files: .framework/src/components/ui/table-primitives.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"]
 export function SortableTableHeader({
   title,
   sortKey,
@@ -40,3 +86,4 @@ export function SortableTableHeader({
     </TableHead>
   )
 }
+// CIL[END chunk_id="SortableTableHeader_sortabletableheader_1783931090"]