spine-framework 0.3.125 → 0.3.127

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

@@ -1,18 +1,23 @@
-/**
- * @module src/pages/admin/PromptConfigsPage
- * @audience installer
- * @layer frontend-page
- * @stability stable
- *
- * Admin list page for LLM prompt configurations. Fetches all configs via
- * `/api/prompt-configs?action=list`, applies client-side search, category
- * filter, and sort. Highlights the default config with a star badge.
- * Renders inside `AdminListPage`. Row clicks navigate to
- * `/spine-framework/admin/configs/prompt-configs/:id`.
- *
- * @seeAlso src/pages/admin/PromptConfigDetailPage.tsx
- */
 
+
+
+
+
+// CIL[BEGIN chunk_id="promptconfigspage_module_header_1783666257" type="module_header" identity="imports" parent="none"]
+// CIL[DOC-MACRO purpose="Import React dependencies and UI components"]
+// CIL[DOC-RESPONSIBILITY responsibility="Import all required modules for PromptConfigsPage component"]
+// CIL[DOC-CONTEXT module="PromptConfigsPage" layer="ui" related_files="[\"custom/apps/portal/pages/ContentPage.tsx\",\"custom/apps/cortex/pages/operations/OperationsDashboard.tsx\",\".framework/src/components/ui/dialog.tsx\",\".framework/src/pages/admin/RolesPage.tsx\",\"\\\"]"]
+// CIL[DOC-CONTRACT inputs="none" outputs="React hooks, UI components, utilities" errors="Import errors" side_effects="Module loading"]
+// CIL[DOC-MICRO logic_summary="Imports React, icons, UI components, 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: ui. Direct callers: 0. Direct calls: 0. Related files: custom/apps/portal/pages/ContentPage.tsx, custom/apps/cortex/pages/operations/OperationsDashboard.tsx, .framework/src/components/ui/dialog.tsx, .framework/src/pages/admin/RolesPage.tsx, \."]
+// 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 { Plus, FileText, CheckCircle, Star, Cpu, MessageSquare } from 'lucide-react';
 import { LoadingSpinner } from '../../components/ui/LoadingSpinner'
@@ -22,7 +27,21 @@ import { SortableTableHeader } from '../../components/admin/SortableTableHeader'
 import { formatDateTime } from '../../lib/utils'
 import { useApi } from '../../hooks/useApi'
 import { apiFetch } from '../../lib/api'
-
+// CIL[END chunk_id="promptconfigspage_module_header_1783666257"]
+// CIL[BEGIN chunk_id="promptconfigspage_interface_promptconfig_1783666257" type="interface" identity="PromptConfig" parent="none"]
+// CIL[DOC-MACRO purpose="Define prompt configuration data structure"]
+// CIL[DOC-RESPONSIBILITY responsibility="Type definition for prompt configuration entities"]
+// CIL[DOC-CONTEXT module="PromptConfigsPage" layer="types" related_files="[\".framework/src/pages/admin/IntegrationsPage.tsx\",\"custom/apps/cortex/functions/custom_cil-embeddings.ts\",\".framework/functions/_shared/schema-utils.ts\",\".framework/functions/_shared/principal.ts\",\"\\\"]"]
+// CIL[DOC-CONTRACT inputs="none" outputs="PromptConfig interface" errors="Type errors" side_effects="Type system"]
+// CIL[DOC-MICRO logic_summary="Defines structure for AI prompt configurations with model settings" notable_decisions="[]"]
+// CIL[DOC-CONFIDENCE pass="second" score="0.95" flags="none"]
+// CIL[DOC-STABILITY stability="stable"]
+// CIL[DOC-VECTOR type="context" content="Layer: types. Direct callers: 0. Direct calls: 0. Related files: .framework/src/pages/admin/IntegrationsPage.tsx, custom/apps/cortex/functions/custom_cil-embeddings.ts, .framework/functions/_shared/schema-utils.ts, .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"]
 interface PromptConfig {
   id: string
   name: string
@@ -42,7 +61,21 @@ interface PromptConfig {
   created_at: string
   updated_at: string
 }
-
+// CIL[END chunk_id="promptconfigspage_interface_promptconfig_1783666257"]
+// CIL[BEGIN chunk_id="promptconfigspage_function_promptconfigspage_1783666257" type="function" identity="PromptConfigsPage" parent="none"]
+// CIL[DOC-MACRO purpose="Render the complete prompt configs interface"]
+// CIL[DOC-RESPONSIBILITY responsibility="Main render logic for prompt configs page"]
+// CIL[DOC-CONTEXT module="PromptConfigsPage" layer="ui" related_files="[\".framework/src/pages/admin/RolesPage.tsx\",\"custom/apps/cortex/pages/operations/OperationsDashboard.tsx\",\".framework/functions/_shared/schema-utils.ts\",\"custom/apps/portal/pages/ContentPage.tsx\"]"]
+// CIL[DOC-CONTRACT inputs="none" outputs="JSX structure" errors="Render errors" side_effects="DOM updates"]
+// CIL[DOC-MICRO logic_summary="Renders AdminListPage with stats, filters, and prompt config 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: ui. Direct callers: 0. Direct calls: 0. Related files: .framework/src/pages/admin/RolesPage.tsx, custom/apps/cortex/pages/operations/OperationsDashboard.tsx, .framework/functions/_shared/schema-utils.ts, custom/apps/portal/pages/ContentPage.tsx."]
+// CIL[DOC-VECTOR type="blast_radius" content="Direct callers: 0. Total affected: 0."]
+// CIL[DOC-VECTOR type="configuration" content="No configuration dependencies."]
+// CIL[DOC-VECTOR type="constraint" content="No test paths identified."]
+// CIL[DOC-VECTOR type="implementation_pattern" content="" status="pending_human_input"]
+// CIL[DOC-VECTOR type="user_journey" content="" status="pending_human_input"]
 export function PromptConfigsPage() {
   const [searchTerm, setSearchTerm] = useState('')
   const [selectedStatus, setSelectedStatus] = useState('all')
@@ -50,6 +83,20 @@ export function PromptConfigsPage() {
   const [sortKey, setSortKey] = useState('name')
   const [sortDirection, setSortDirection] = useState<'asc' | 'desc'>('asc')
 
+  // CIL[BEGIN chunk_id="promptconfigspage_hooks_1783666257" type="hooks" identity="useApi" parent="promptconfigspage_function_promptconfigspage_1783666257"]
+// CIL[DOC-MACRO purpose="Fetch prompt configurations from API"]
+// CIL[DOC-RESPONSIBILITY responsibility="Handle useApi"]
+// CIL[DOC-CONTEXT module="PromptConfigsPage" layer="data" related_files="[\"\\\"]"]
+// CIL[DOC-CONTRACT inputs="none" outputs="prompt configs array" errors="API errors" side_effects="HTTP requests"]
+// CIL[DOC-MICRO logic_summary="Uses useApi hook to fetch prompt configurations list" notable_decisions="[]"]
+// CIL[DOC-CONFIDENCE pass="second" score="0.95" flags="none"]
+// CIL[DOC-STABILITY stability="stable"]
+// CIL[DOC-VECTOR type="context" content="Layer: data. Direct callers: 0. Direct calls: 0. Related files: \."]
+// 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: promptConfigs, loading, error, refetch } = useApi<PromptConfig[]>(
     async () => {
       const response = await apiFetch('/api/prompt-configs?action=list')
@@ -59,7 +106,22 @@ export function PromptConfigsPage() {
     },
     { immediate: true }
   )
+// CIL[END chunk_id="promptconfigspage_hooks_1783666257"]
 
+  // CIL[BEGIN chunk_id="promptconfigspage_filters_1783666257" type="filter_logic" identity="filteredPromptConfigs" parent="promptconfigspage_function_promptconfigspage_1783666257"]
+// CIL[DOC-MACRO purpose="Filter and sort prompt configurations"]
+// CIL[DOC-RESPONSIBILITY responsibility="Handle filteredPromptConfigs"]
+// CIL[DOC-CONTEXT module="PromptConfigsPage" layer="logic" related_files="[\".framework/src/pages/admin/RolesPage.tsx\",\"custom/apps/portal/pages/ContentPage.tsx\",\"custom/apps/cortex/pages/operations/OperationsDashboard.tsx\",\".framework/src/components/ui/dialog.tsx\",\"\\\"]"]
+// CIL[DOC-CONTRACT inputs="none" outputs="filtered configs" errors="none" side_effects="none"]
+// CIL[DOC-MICRO logic_summary="Filters configs by search, status, and type; extracts unique types" notable_decisions="[]"]
+// CIL[DOC-CONFIDENCE pass="second" score="0.95" flags="none"]
+// CIL[DOC-STABILITY stability="stable"]
+// CIL[DOC-VECTOR type="context" content="Layer: logic. Direct callers: 0. Direct calls: 0. Related files: .framework/src/pages/admin/RolesPage.tsx, custom/apps/portal/pages/ContentPage.tsx, custom/apps/cortex/pages/operations/OperationsDashboard.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"]
   const filteredPromptConfigs = (promptConfigs || []).filter(config => {
     const matchesSearch = config.name.toLowerCase().includes(searchTerm.toLowerCase()) ||
                          config.slug.toLowerCase().includes(searchTerm.toLowerCase()) ||
@@ -72,7 +134,22 @@ export function PromptConfigsPage() {
   })
 
   const promptTypes = Array.from(new Set((promptConfigs || []).map(c => c.prompt_type).filter(Boolean)))
+// CIL[END chunk_id="promptconfigspage_filters_1783666257"]
 
+  // CIL[BEGIN chunk_id="promptconfigspage_handlers_1783666257" type="event_handlers" identity="handleSort" parent="promptconfigspage_function_promptconfigspage_1783666257"]
+// CIL[DOC-MACRO purpose="Handle sorting and row click events"]
+// CIL[DOC-RESPONSIBILITY responsibility="Handle handleSort"]
+// CIL[DOC-CONTEXT module="handleSort" layer="unknown" related_files="[]"]
+// CIL[DOC-CONTRACT inputs="none" outputs="none" errors="none" side_effects="none"]
+// CIL[DOC-MICRO logic_summary="Implements handleSort" notable_decisions="[]"]
+// CIL[DOC-CONFIDENCE pass="second" score="0.95" flags="none"]
+// CIL[DOC-STABILITY stability="stable"]
+// CIL[DOC-VECTOR type="context" content="Layer: unknown. 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"]
   const handleSort = (key: string) => {
     if (sortKey === key) {
       setSortDirection(sortDirection === 'asc' ? 'desc' : 'asc')
@@ -102,7 +179,22 @@ export function PromptConfigsPage() {
     
     return 0
   })
+// CIL[END chunk_id="promptconfigspage_handlers_1783666257"]
 
+  // CIL[BEGIN chunk_id="promptconfigspage_stats_1783666257" type="stats_config" identity="statsCards" parent="promptconfigspage_function_promptconfigspage_1783666257"]
+// CIL[DOC-MACRO purpose="Configure statistics cards and filter options"]
+// CIL[DOC-RESPONSIBILITY responsibility="Handle statsCards"]
+// CIL[DOC-CONTEXT module="statsCards" layer="unknown" related_files="[]"]
+// CIL[DOC-CONTRACT inputs="none" outputs="none" errors="none" side_effects="none"]
+// CIL[DOC-MICRO logic_summary="Implements statsCards" notable_decisions="[]"]
+// CIL[DOC-CONFIDENCE pass="second" score="0.95" flags="none"]
+// CIL[DOC-STABILITY stability="stable"]
+// CIL[DOC-VECTOR type="context" content="Layer: unknown. 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"]
   const statsCards = [
     {
       title: 'Total Prompts',
@@ -155,7 +247,22 @@ export function PromptConfigsPage() {
       onChange: (v: string) => setSelectedType(v)
     }
   ]
+// CIL[END chunk_id="promptconfigspage_stats_1783666257"]
 
+  // CIL[BEGIN chunk_id="promptconfigspage_render_1783666257" type="render_logic" identity="return" parent="promptconfigspage_function_promptconfigspage_1783666257"]
+// CIL[DOC-MACRO purpose="Render the complete prompt configs interface"]
+// CIL[DOC-RESPONSIBILITY responsibility="Handle return"]
+// CIL[DOC-CONTEXT module="return" layer="unknown" related_files="[]"]
+// CIL[DOC-CONTRACT inputs="none" outputs="none" errors="none" side_effects="none"]
+// CIL[DOC-MICRO logic_summary="Implements return" notable_decisions="[]"]
+// CIL[DOC-CONFIDENCE pass="second" score="0.95" flags="none"]
+// CIL[DOC-STABILITY stability="stable"]
+// CIL[DOC-VECTOR type="context" content="Layer: unknown. 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"]
   return (
     <AdminListPage
       title="Prompt Configs"
@@ -290,3 +397,5 @@ export function PromptConfigsPage() {
     </AdminListPage>
   )
 }
+// CIL[END chunk_id="promptconfigspage_render_1783666257"]
+// CIL[END chunk_id="promptconfigspage_function_promptconfigspage_1783666257"]

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

@@ -1,13 +1,22 @@
-/**
- * @module src/pages/admin/ProperlyDesignedPage
- * @audience installer
- * @layer frontend-page
- * @stability testing
- *
- * A properly designed page that works within the Spine admin layout.
- * Demonstrates shadcn components in a real application context.
- */
 
+
+
+
+// CIL[BEGIN chunk_id="properlydesignedpage_module_header_1783666257" type="module_header" identity="imports" parent="none"]
+// CIL[DOC-MACRO purpose="Import React dependencies and UI components"]
+// CIL[DOC-RESPONSIBILITY responsibility="Import all required modules for ProperlyDesignedPage component"]
+// CIL[DOC-CONTEXT module="ProperlyDesignedPage" layer="ui" related_files="[\"custom/apps/portal/pages/ContentPage.tsx\",\"custom/apps/cortex/pages/operations/OperationsDashboard.tsx\",\".framework/src/components/ui/dialog.tsx\",\".framework/src/components/ui/table-primitives.tsx\",\"\\\"]"]
+// CIL[DOC-CONTRACT inputs="none" outputs="React hooks, UI components, utilities" errors="Import errors" side_effects="Module loading"]
+// CIL[DOC-MICRO logic_summary="Imports React, comprehensive 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: ui. Direct callers: 0. Direct calls: 0. Related files: custom/apps/portal/pages/ContentPage.tsx, custom/apps/cortex/pages/operations/OperationsDashboard.tsx, .framework/src/components/ui/dialog.tsx, .framework/src/components/ui/table-primitives.tsx, \."]
+// CIL[DOC-VECTOR type="blast_radius" content="Direct callers: 0. Total affected: 0."]
+// CIL[DOC-VECTOR type="configuration" content="No configuration dependencies."]
+// CIL[DOC-VECTOR type="constraint" content="No test paths identified."]
+// CIL[DOC-VECTOR type="implementation_pattern" content="" status="pending_human_input"]
+// CIL[DOC-VECTOR type="user_journey" content="" status="pending_human_input"]
 import { useState } from 'react'
 import { Card, CardContent, CardDescription, CardHeader, CardTitle } from '../../components/ui/card'
 import { Button } from '../../components/ui/button'
@@ -77,13 +86,41 @@ import {
   TrendingUp,
   Activity
 } from 'lucide-react'
-
+// CIL[END chunk_id="properlydesignedpage_module_header_1783666257"]
+// CIL[BEGIN chunk_id="properlydesignedpage_function_properlydesignedpage_1783666257" type="function" identity="ProperlyDesignedPage" parent="none"]
+// CIL[DOC-MACRO purpose="Render the complete dashboard interface"]
+// CIL[DOC-RESPONSIBILITY responsibility="Main render logic for comprehensive dashboard page"]
+// CIL[DOC-CONTEXT module="ProperlyDesignedPage" layer="ui" related_files="[\"custom/apps/cortex/pages/operations/OperationsDashboard.tsx\",\".framework/functions/_shared/schema-utils.ts\",\"custom/apps/portal/pages/ContentPage.tsx\",\".framework/functions/_shared/principal.ts\",\".framework/src/components/ui/table-primitives.tsx\",\"\\\"]"]
+// CIL[DOC-CONTRACT inputs="none" outputs="JSX structure" errors="Render errors" side_effects="DOM updates"]
+// CIL[DOC-MICRO logic_summary="Renders header, stats cards, search bar, tabs with multiple content 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: ui. Direct callers: 0. Direct calls: 0. Related files: custom/apps/cortex/pages/operations/OperationsDashboard.tsx, .framework/functions/_shared/schema-utils.ts, custom/apps/portal/pages/ContentPage.tsx, .framework/functions/_shared/principal.ts, .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 ProperlyDesignedPage() {
   const [selectedTab, setSelectedTab] = useState('overview')
   const [searchQuery, setSearchQuery] = useState('')
   const [notifications, setNotifications] = useState(true)
   const [autoSave, setAutoSave] = useState(true)
 
+  // CIL[BEGIN chunk_id="properlydesignedpage_render_1783666257" type="render_logic" identity="return" parent="properlydesignedpage_function_properlydesignedpage_1783666257"]
+// CIL[DOC-MACRO purpose="Render the complete dashboard interface"]
+// CIL[DOC-RESPONSIBILITY responsibility="Handle return"]
+// CIL[DOC-CONTEXT module="ProperlyDesignedPage" layer="ui" related_files="[\"custom/apps/cortex/pages/operations/OperationsDashboard.tsx\",\".framework/functions/_shared/schema-utils.ts\",\"custom/apps/portal/pages/ContentPage.tsx\",\".framework/functions/_shared/principal.ts\",\".framework/src/components/ui/table-primitives.tsx\",\"\\\"]"]
+// CIL[DOC-CONTRACT inputs="none" outputs="JSX structure" errors="Render errors" side_effects="DOM updates"]
+// CIL[DOC-MICRO logic_summary="Renders header, stats cards, search bar, tabs with multiple content 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: ui. Direct callers: 0. Direct calls: 0. Related files: custom/apps/cortex/pages/operations/OperationsDashboard.tsx, .framework/functions/_shared/schema-utils.ts, custom/apps/portal/pages/ContentPage.tsx, .framework/functions/_shared/principal.ts, .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"]
   return (
     <div className="container mx-auto p-6 space-y-6">
       {/* Header Section */}
@@ -432,3 +469,5 @@ export function ProperlyDesignedPage() {
     </div>
   )
 }
+// CIL[END chunk_id="properlydesignedpage_render_1783666257"]
+// CIL[END chunk_id="properlydesignedpage_function_properlydesignedpage_1783666257"]

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

@@ -1,12 +1,23 @@
-/**
- * @module src/pages/admin/RoleDetailPage
- * @audience installer
- * @layer frontend-page
- * @stability stable
- *
- * Create / view / edit page for a single role.
- */
 
+
+
+
+
+// CIL[BEGIN chunk_id="roledetailpage_module_header_1783666257" type="module_header" identity="imports" parent="none"]
+// CIL[DOC-MACRO purpose="Import React dependencies and UI components"]
+// CIL[DOC-RESPONSIBILITY responsibility="Import all required modules for RoleDetailPage component"]
+// CIL[DOC-CONTEXT module="RoleDetailPage" layer="ui" related_files="[\"custom/apps/portal/pages/ContentPage.tsx\",\"custom/apps/cortex/pages/operations/OperationsDashboard.tsx\",\".framework/src/components/ui/dialog.tsx\",\".framework/src/pages/admin/RolesPage.tsx\",\"\\\"]"]
+// CIL[DOC-CONTRACT inputs="none" outputs="React hooks, UI components, utilities" errors="Import errors" side_effects="Module loading"]
+// CIL[DOC-MICRO logic_summary="Imports React, router, 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: ui. Direct callers: 0. Direct calls: 0. Related files: custom/apps/portal/pages/ContentPage.tsx, custom/apps/cortex/pages/operations/OperationsDashboard.tsx, .framework/src/components/ui/dialog.tsx, .framework/src/pages/admin/RolesPage.tsx, \."]
+// CIL[DOC-VECTOR type="blast_radius" content="Direct callers: 0. Total affected: 0."]
+// CIL[DOC-VECTOR type="configuration" content="No configuration dependencies."]
+// CIL[DOC-VECTOR type="constraint" content="No test paths identified."]
+// CIL[DOC-VECTOR type="implementation_pattern" content="" status="pending_human_input"]
+// CIL[DOC-VECTOR type="user_journey" content="" status="pending_human_input"]
 import { useState, useEffect } from 'react'
 import { useParams, useNavigate } from 'react-router-dom'
 import { Button } from '../../components/ui/button'
@@ -21,7 +32,22 @@ import { ArrowLeft, ShieldCheck, AlertCircle } from 'lucide-react'
 import { useApi } from '../../hooks/useApi'
 import { apiFetch } from '../../lib/api'
 import { formatDateTime } from '../../lib/utils'
-
+import { PageInstructions } from '../../components/admin/PageInstructions'
+// CIL[END chunk_id="roledetailpage_module_header_1783666257"]
+// CIL[BEGIN chunk_id="roledetailpage_interface_role_1783666257" type="interface" identity="Role" parent="none"]
+// CIL[DOC-MACRO purpose="Define role data structure"]
+// CIL[DOC-RESPONSIBILITY responsibility="Type definition for role entities"]
+// CIL[DOC-CONTEXT module="RoleDetailPage" layer="types" related_files="[\".framework/src/pages/admin/IntegrationsPage.tsx\",\".framework/src/pages/admin/RolesPage.tsx\",\"\\\"]"]
+// CIL[DOC-CONTRACT inputs="none" outputs="Role interface" errors="Type errors" side_effects="Type system"]
+// CIL[DOC-MICRO logic_summary="Defines structure for role configuration with permissions and 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: types. Direct callers: 0. Direct calls: 0. Related files: .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"]
 interface Role {
   id: string
   name: string
@@ -34,7 +60,21 @@ interface Role {
   created_at: string
   updated_at: string
 }
-
+// CIL[END chunk_id="roledetailpage_interface_role_1783666257"]
+// CIL[BEGIN chunk_id="roledetailpage_function_roledetailpage_1783666257" type="function" identity="RoleDetailPage" parent="none"]
+// CIL[DOC-MACRO purpose="Render the complete role management interface"]
+// CIL[DOC-RESPONSIBILITY responsibility="Main render logic for role detail page"]
+// CIL[DOC-CONTEXT module="RoleDetailPage" layer="ui" related_files="[\".framework/src/pages/admin/RolesPage.tsx\",\"custom/apps/cortex/pages/operations/OperationsDashboard.tsx\"]"]
+// CIL[DOC-CONTRACT inputs="none" outputs="JSX structure" errors="Render errors" side_effects="DOM updates"]
+// CIL[DOC-MICRO logic_summary="Renders loading states, error states, and role form with all fields" notable_decisions="[]"]
+// CIL[DOC-CONFIDENCE pass="second" score="0.95" flags="none"]
+// CIL[DOC-STABILITY stability="stable"]
+// CIL[DOC-VECTOR type="context" content="Layer: ui. Direct callers: 0. Direct calls: 0. Related files: .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 RoleDetailPage() {
   const { id } = useParams<{ id: string }>()
   const navigate = useNavigate()
@@ -52,6 +92,20 @@ export function RoleDetailPage() {
   const [isSubmitting, setIsSubmitting] = useState(false)
   const [error, setError] = useState<string | null>(null)
 
+  // CIL[BEGIN chunk_id="roledetailpage_hooks_1783666257" type="hooks" identity="useApi" parent="roledetailpage_function_roledetailpage_1783666257"]
+// CIL[DOC-MACRO purpose="Fetch role data and manage form state"]
+// CIL[DOC-RESPONSIBILITY responsibility="Handle useApi"]
+// CIL[DOC-CONTEXT module="RoleDetailPage" layer="data" related_files="[\"custom/apps/portal/pages/ContentPage.tsx\",\".framework/src/pages/admin/RolesPage.tsx\",\"\\\"]"]
+// CIL[DOC-CONTRACT inputs="none" outputs="role data, form state" errors="API errors" side_effects="HTTP requests, state updates"]
+// CIL[DOC-MICRO logic_summary="Uses useApi hook to fetch role data and useEffect to sync form state" notable_decisions="[]"]
+// CIL[DOC-CONFIDENCE pass="second" score="0.95" flags="none"]
+// CIL[DOC-STABILITY stability="stable"]
+// CIL[DOC-VECTOR type="context" content="Layer: data. Direct callers: 0. Direct calls: 0. Related files: 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"]
   const { data: role, loading, error: fetchError } = useApi<Role>(
     async () => {
       if (isCreateMode) return null
@@ -76,7 +130,22 @@ export function RoleDetailPage() {
       setPermissionsJson(JSON.stringify(role.permissions || {}, null, 2))
     }
   }, [role])
+// CIL[END chunk_id="roledetailpage_hooks_1783666257"]
 
+  // CIL[BEGIN chunk_id="roledetailpage_handlers_1783666257" type="event_handlers" identity="handleSubmit" parent="roledetailpage_function_roledetailpage_1783666257"]
+// CIL[DOC-MACRO purpose="Handle form submission for role creation/editing"]
+// CIL[DOC-RESPONSIBILITY responsibility="Handle handleSubmit"]
+// CIL[DOC-CONTEXT module="RoleDetailPage" layer="logic" related_files="[\".framework/src/pages/admin/RolesPage.tsx\",\".framework/src/pages/admin/TypeDetailPage.tsx\",\"\\\"]"]
+// CIL[DOC-CONTRACT inputs="none" outputs="API response, navigation" errors="Validation errors, API errors" side_effects="HTTP requests, navigation"]
+// CIL[DOC-MICRO logic_summary="Validates form data, parses permissions, submits to API, handles errors" notable_decisions="[]"]
+// CIL[DOC-CONFIDENCE pass="second" score="0.95" flags="none"]
+// CIL[DOC-STABILITY stability="stable"]
+// CIL[DOC-VECTOR type="context" content="Layer: logic. Direct callers: 0. Direct calls: 0. Related files: .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"]
   const handleSubmit = async (e: React.FormEvent) => {
     e.preventDefault()
     setIsSubmitting(true)
@@ -117,7 +186,22 @@ export function RoleDetailPage() {
       setIsSubmitting(false)
     }
   }
+// CIL[END chunk_id="roledetailpage_handlers_1783666257"]
 
+  // CIL[BEGIN chunk_id="roledetailpage_render_1783666257" type="render_logic" identity="return" parent="roledetailpage_function_roledetailpage_1783666257"]
+// CIL[DOC-MACRO purpose="Render the complete role management interface"]
+// CIL[DOC-RESPONSIBILITY responsibility="Handle return"]
+// CIL[DOC-CONTEXT module="return" layer="unknown" related_files="[]"]
+// CIL[DOC-CONTRACT inputs="none" outputs="none" errors="none" side_effects="none"]
+// CIL[DOC-MICRO logic_summary="Implements return" notable_decisions="[]"]
+// CIL[DOC-CONFIDENCE pass="second" score="0.95" flags="none"]
+// CIL[DOC-STABILITY stability="stable"]
+// CIL[DOC-VECTOR type="context" content="Layer: unknown. 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"]
   if (loading) {
     return (
       <div className="space-y-6">
@@ -155,6 +239,40 @@ export function RoleDetailPage() {
         </h1>
       </div>
 
+      <PageInstructions
+        description="Define a role and set its permissions and metadata."
+        sections={[
+          { title: 'What this role controls', content: 'A role is a named permission set assigned to people. It controls which record types a person can create, read, update, delete, or admin, and whether the role can be assigned in the first place.' },
+          { title: 'Fields explained', content: <ul className="list-disc pl-4 space-y-1">
+            <li><strong>Name</strong> — string, required. The display label such as Sales Manager. Empty name blocks save.</li>
+            <li><strong>Slug</strong> — string, required. A unique URL-friendly identifier. Disabled after creation because permissions and references depend on it.</li>
+            <li><strong>Description</strong> — string. Optional context for other admins.</li>
+            <li><strong>System Role</strong> — checkbox, create-only. Marks a reserved role that cannot be deleted and is protected for core functions.</li>
+            <li><strong>Active</strong> — checkbox. Inactive roles cannot be assigned to people.</li>
+            <li><strong>Permissions (JSON)</strong> — JSON. Maps type slugs to arrays of allowed actions. Invalid JSON or wrong shape will cause save to fail.</li>
+          </ul> },
+          { title: 'Options and values', content: <ul className="list-disc pl-4 space-y-1">
+            <li><strong>Actions per type</strong>: typical values are create, read, update, delete, and admin. Use the array format with a type slug mapped to an array: type_slug: ["read", "write"].</li>
+            <li><strong>System Role</strong>: can only be set during creation and prevents deletion later.</li>
+          </ul> },
+          { title: 'Downstream impact', content: <ul className="list-disc pl-4 space-y-1">
+            <li>People assigned to this role receive the effective permissions immediately after the role is saved.</li>
+            <li>The admin-data API and runtime record UIs evaluate the role permissions for every create, read, update, and delete request.</li>
+            <li>Missing or malformed permissions can lock people out of records or grant unintended access.</li>
+          </ul> },
+          { title: 'How to create, save, and validate', content: <ol className="list-decimal pl-4 space-y-1">
+            <li>In create mode, enter Name and Slug, then set Active and optionally System. Existing roles cannot change the slug.</li>
+            <li>Enter valid Permissions JSON mapping type slugs to action arrays.</li>
+            <li>Click Create Role or Update Role. Save fails if the name/slug are empty, the slug is changed, or the permissions JSON cannot be parsed.</li>
+          </ol> },
+          { title: 'Common mistakes', content: <ul className="list-disc pl-4 space-y-1">
+            <li>Writing permissions as a flat list instead of an object of arrays.</li>
+            <li>Trying to change the slug after creation, which is disabled and will be ignored.</li>
+            <li>Forgetting to mark a role Active, which prevents assignment.</li>
+          </ul> },
+        ]}
+      />
+
       {error && (
         <Alert variant="destructive">
           <AlertCircle className="h-4 w-4" />
@@ -271,3 +389,5 @@ export function RoleDetailPage() {
     </div>
   )
 }
+// CIL[END chunk_id="roledetailpage_render_1783666257"]
+// CIL[END chunk_id="roledetailpage_function_roledetailpage_1783666257"]