spine-framework 0.3.125 → 0.3.127

package/.framework/scripts/app-install-cli.ts

@@ -1,36 +1,51 @@
 #!/usr/bin/env tsx
 
-/**
- * @module scripts/app-install-cli
- * @audience installer
- * @layer cli
- * @stability orphaned
- *
- * Spine App Installation CLI - Validates and executes app installation instruction files.
- * **ORPHANED**: References non-existent schema and template files at `../docs/app-installation/`.
- * 
- * **Intended Purpose**: Validate YAML instruction files against JSON schema and execute
- * multi-step app installations (pack installation, app creation, migrations, verification).
- * 
- * **Current State**: Cannot function - missing required schema.json and template files.
- * 
- * **Dependencies**: commander, js-yaml, ajv for CLI operations and validation.
- * 
- * @tags orphaned, cli, app-installation, validation
- */
 
+
+
+
+
+
+
+// CIL[BEGIN chunk_id="app-install-cli_module_header_1783931090" type="module_header" identity="imports" parent="none"]
+// CIL[DOC-MACRO purpose="Import Node.js modules for CLI app installation tool"]
+// CIL[DOC-RESPONSIBILITY responsibility="Manage all external module imports for CLI operations"]
+// CIL[DOC-CONTEXT module="app-install-cli" layer="cli" related_files="[\".framework/migrations/015_simplify_apps_table.sql\",\"custom/apps/cortex/pages/operations/OperationsDashboard.tsx\",\"custom/apps/portal/pages/ContentPage.tsx\",\".framework/src/pages/admin/TypeDetailPage.tsx\",\"\\\"]"]
+// CIL[DOC-CONTRACT inputs="none" outputs="Imported modules and utilities" errors="Import failures" side_effects="Module loading"]
+// CIL[DOC-MICRO logic_summary="Imports file system, CLI, YAML validation, and ES modules utilities" 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: cli. Direct callers: 0. Direct calls: 0. Related files: .framework/migrations/015_simplify_apps_table.sql, custom/apps/cortex/pages/operations/OperationsDashboard.tsx, custom/apps/portal/pages/ContentPage.tsx, .framework/src/pages/admin/TypeDetailPage.tsx, \."]
+// CIL[DOC-VECTOR type="blast_radius" content="Direct callers: 0. Total affected: 0."]
+// CIL[DOC-VECTOR type="configuration" content="No configuration dependencies."]
+// CIL[DOC-VECTOR type="constraint" content="No test paths identified."]
+// CIL[DOC-VECTOR type="implementation_pattern" content="" status="pending_human_input"]
+// CIL[DOC-VECTOR type="user_journey" content="" status="pending_human_input"]
 import { readFileSync, existsSync, writeFileSync } from 'fs'
 import { resolve, dirname } from 'path'
 import { program } from 'commander'
 import yaml from 'js-yaml'
 import Ajv from 'ajv'
 import { fileURLToPath } from 'url'
-
-// Fix __dirname for ES modules
+// CIL[END chunk_id="app-install-cli_module_header_1783931090"]
+// CIL[BEGIN chunk_id="app-install-cli_setup_1783931090" type="setup" identity="setup" parent="none"]
+// CIL[DOC-MACRO purpose="Initialize CLI environment, schema validation, and type definitions"]
+// CIL[DOC-RESPONSIBILITY responsibility="Set up file paths, schema validator, and installation context"]
+// CIL[DOC-CONTEXT module="app-install-cli" layer="cli" related_files="[\".framework/src/pages/admin/TypeDetailPage.tsx\",\".framework/functions/_shared/schema-utils.ts\",\"custom/apps/portal/pages/ContentPage.tsx\",\"custom/apps/cortex/pages/operations/OperationsDashboard.tsx\",\".framework/functions/_shared/db.ts\",\"\\\"]"]
+// CIL[DOC-CONTRACT inputs="none" outputs="Schema validator, file paths, context interface" errors="Schema loading failures" side_effects="File system reads"]
+// CIL[DOC-MICRO logic_summary="Resolves paths, loads schema, creates validator, defines context interface" notable_decisions="['schema_loading', 'ajv_validation']"]
+// CIL[DOC-CONFIDENCE pass="second" score="0.95" flags="external_symbols_unknown"]
+// CIL[DOC-STABILITY stability="stable"]
+// CIL[DOC-VECTOR type="context" content="Layer: cli. Direct callers: 0. Direct calls: 0. Related files: .framework/src/pages/admin/TypeDetailPage.tsx, .framework/functions/_shared/schema-utils.ts, custom/apps/portal/pages/ContentPage.tsx, custom/apps/cortex/pages/operations/OperationsDashboard.tsx, .framework/functions/_shared/db.ts, \."]
+// CIL[DOC-VECTOR type="blast_radius" content="Direct callers: 0. Total affected: 0."]
+// CIL[DOC-VECTOR type="configuration" content="No configuration dependencies."]
+// CIL[DOC-VECTOR type="constraint" content="No test paths identified."]
+// CIL[DOC-VECTOR type="implementation_pattern" content="" status="pending_human_input"]
+// CIL[DOC-VECTOR type="user_journey" content="" status="pending_human_input"]
 const __filename = fileURLToPath(import.meta.url)
 const __dirname = dirname(__filename)
 
-// Load JSON schema
 const schemaPath = resolve(__dirname, '../docs/app-installation/schema.json')
 const schema = JSON.parse(readFileSync(schemaPath, 'utf8'))
 
@@ -42,22 +57,21 @@ interface InstallationContext {
   PACK_INSTALLATION_ID?: string
   [key: string]: string | undefined
 }
-
-// ─── CHUNK_START: APP_INSTALL_CLI_SUBSTITUTE_VARIABLES ──────────────────────────────────────────────
-/**
- * @chunk-id    APP_INSTALL_CLI_SUBSTITUTE_VARIABLES_1_0_0
- * @version     1.0.0
- * @hash        122ca9e63f2310e8a01f76dc9c962319d8e267d8737c39895425440489a747bd
- * @macro       Variable Substitution Engine
- * @micro       Recursively replaces ${VAR} placeholders with context values
- * @inputs      obj: any — Object containing ${VAR} placeholders
- * @inputs      context: InstallationContext — Variable name to value mapping
- * @outputs     any — Object with all placeholders substituted
- * @depends-on  [none]
- * @depended-by [validateInstructionFile, executeInstallation]
- * @side-effects [none]
- * @tags        orphaned, variable-substitution, template-engine
- */
+// CIL[END chunk_id="app-install-cli_setup_1783931090"]
+// CIL[BEGIN chunk_id="app-install-cli_substitutevariables_1783931090" type="function" identity="substituteVariables" parent="none"]
+// CIL[DOC-MACRO purpose="Recursively substitute ${VAR} placeholders with context values"]
+// CIL[DOC-RESPONSIBILITY responsibility="Variable template substitution engine for installation configs"]
+// CIL[DOC-CONTEXT module="app-install-cli" layer="cli" related_files="[\".framework/functions/_shared/schema-utils.ts\",\".framework/src/components/ui/dialog.tsx\",\".framework/functions/_shared/principal.ts\",\".framework/functions/_shared/db.ts\",\".framework/src/components/ui/table-primitives.tsx\",\"\\\"]"]
+// CIL[DOC-CONTRACT inputs="none" outputs="substituted object" errors="none" side_effects="none"]
+// CIL[DOC-MICRO logic_summary="Handles strings, arrays, and objects recursively with regex replacement" notable_decisions="['recursive_substitution', 'fallback_to_match']"]
+// CIL[DOC-CONFIDENCE pass="second" score="0.95" flags="none"]
+// CIL[DOC-STABILITY stability="stable"]
+// CIL[DOC-VECTOR type="context" content="Layer: cli. Direct callers: 2. Direct calls: 0. Related files: .framework/functions/_shared/schema-utils.ts, .framework/src/components/ui/dialog.tsx, .framework/functions/_shared/principal.ts, .framework/functions/_shared/db.ts, .framework/src/components/ui/table-primitives.tsx, \."]
+// CIL[DOC-VECTOR type="blast_radius" content="Direct callers: 2. Total affected: 2."]
+// CIL[DOC-VECTOR type="configuration" content="No configuration dependencies."]
+// CIL[DOC-VECTOR type="constraint" content="No test paths identified."]
+// CIL[DOC-VECTOR type="implementation_pattern" content="" status="pending_human_input"]
+// CIL[DOC-VECTOR type="user_journey" content="" status="pending_human_input"]
 function substituteVariables(obj: any, context: InstallationContext): any {
   if (typeof obj === 'string') {
     return obj.replace(/\$\{([^}]+)\}/g, (match, varName) => {
@@ -74,22 +88,21 @@ function substituteVariables(obj: any, context: InstallationContext): any {
   }
   return obj
 }
-// ─── CHUNK_END: APP_INSTALL_CLI_SUBSTITUTE_VARIABLES ────────────────────────────────────────────────
-
-// ─── CHUNK_START: APP_INSTALL_CLI_VALIDATE_INSTRUCTION_FILE ──────────────────────────────────────────────
-/**
- * @chunk-id    APP_INSTALL_CLI_VALIDATE_INSTRUCTION_FILE_1_0_0
- * @version     1.0.0
- * @hash        c673609fd3442632d832e0c4c3ef2dbda0a51e381bb469e55b7e2cc59005b5e2
- * @macro       Installation File Validation
- * @micro       Validates YAML instruction files against JSON schema
- * @inputs      filePath: string — Path to YAML instruction file
- * @outputs     boolean — true if valid, false otherwise
- * @depends-on  [schema, validate, substituteVariables]
- * @depended-by [executeInstallation]
- * @side-effects [console output, file system reads]
- * @tags        orphaned, validation, yaml, json-schema
- */
+// CIL[END chunk_id="app-install-cli_substitutevariables_1783931090"]
+// CIL[BEGIN chunk_id="app-install-cli_validateinstructionfile_1783931090" type="function" identity="validateInstructionFile" parent="none"]
+// CIL[DOC-MACRO purpose="Validate YAML instruction files against JSON schema"]
+// CIL[DOC-RESPONSIBILITY responsibility="Schema validation and file existence checking"]
+// CIL[DOC-CONTEXT module="app-install-cli" layer="cli" related_files="[\".framework/functions/_shared/schema-utils.ts\",\".framework/src/pages/admin/TypeDetailPage.tsx\",\"\\\"]"]
+// CIL[DOC-CONTRACT inputs="none" outputs="validation result" errors="File not found, validation failures" side_effects="Console output, process.exit"]
+// CIL[DOC-MICRO logic_summary="Checks file existence, loads YAML, validates against schema, exits on failure" notable_decisions="['process_exit_on_failure', 'schema_validation']"]
+// CIL[DOC-CONFIDENCE pass="second" score="0.95" flags="external_symbols_unknown"]
+// CIL[DOC-STABILITY stability="stable"]
+// CIL[DOC-VECTOR type="context" content="Layer: cli. Direct callers: 1. Direct calls: 0. Related files: .framework/functions/_shared/schema-utils.ts, .framework/src/pages/admin/TypeDetailPage.tsx, \."]
+// CIL[DOC-VECTOR type="blast_radius" content="Direct callers: 1. Total affected: 1."]
+// CIL[DOC-VECTOR type="configuration" content="No configuration dependencies."]
+// CIL[DOC-VECTOR type="constraint" content="No test paths identified."]
+// CIL[DOC-VECTOR type="implementation_pattern" content="" status="pending_human_input"]
+// CIL[DOC-VECTOR type="user_journey" content="" status="pending_human_input"]
 async function validateInstructionFile(filePath: string): Promise<void> {
   try {
     console.log(`🔍 Validating ${filePath}...`)
@@ -102,7 +115,6 @@ async function validateInstructionFile(filePath: string): Promise<void> {
     const content = readFileSync(filePath, 'utf8')
     const data = yaml.load(content) as any
 
-    // Validate against schema
     if (!validate(data)) {
       console.error('❌ Validation failed:')
       console.error(JSON.stringify(validate.errors, null, 2))
@@ -115,34 +127,30 @@ async function validateInstructionFile(filePath: string): Promise<void> {
     process.exit(1)
   }
 }
-// ─── CHUNK_END: APP_INSTALL_CLI_VALIDATE_INSTRUCTION_FILE ────────────────────────────────────────────────
-
-// ─── CHUNK_START: APP_INSTALL_CLI_EXECUTE_INSTALLATION ──────────────────────────────────────────────
-/**
- * @chunk-id    APP_INSTALL_CLI_EXECUTE_INSTALLATION_1_0_0
- * @version     1.0.0
- * @hash        c84aa57769569e4b00ebde4d8b29b7059e6b0d6e8eb3d82cfa51c15e1451e04a
- * @macro       Multi-Step App Installation Executor
- * @micro       Orchestrates pack installation, app creation, migrations, and verification
- * @inputs      filePath: string — Path to YAML instruction file
- * @inputs      options: any — CLI options including accountId
- * @outputs     void — Console output only
- * @depends-on  [validateInstructionFile, substituteVariables, yaml, fs]
- * @depended-by [CLI program command handler]
- * @side-effects [console output, file system reads, process.exit on failure]
- * @tags        orphaned, installation, orchestration, multi-step
- */
+// CIL[END chunk_id="app-install-cli_validateinstructionfile_1783931090"]
+// CIL[BEGIN chunk_id="app-install-cli_executeinstallation_1783931090" type="function" identity="executeInstallation" parent="none"]
+// CIL[DOC-MACRO purpose="Execute multi-step app installation from instruction files"]
+// CIL[DOC-RESPONSIBILITY responsibility="Orchestrate complete app installation workflow"]
+// CIL[DOC-CONTEXT module="app-install-cli" layer="cli" related_files="[\".framework/migrations/015_simplify_apps_table.sql\",\"custom/apps/portal/pages/ContentPage.tsx\",\"custom/apps/cortex/pages/operations/OperationsDashboard.tsx\",\"custom/apps/cortex/functions/custom_cil-embeddings.ts\",\"\\\"]"]
+// CIL[DOC-CONTRACT inputs="none" outputs="installation result" errors="Installation failures" side_effects="Console output, process.exit"]
+// CIL[DOC-MICRO logic_summary="Validates, sets context, simulates pack install, creates apps, runs migrations, verifies" notable_decisions="['simulated_installation', 'step_by_step_execution']"]
+// CIL[DOC-CONFIDENCE pass="second" score="0.95" flags="complex_dependencies"]
+// CIL[DOC-STABILITY stability="stable"]
+// CIL[DOC-VECTOR type="context" content="Layer: cli. Direct callers: 0. Direct calls: 0. Related files: .framework/migrations/015_simplify_apps_table.sql, custom/apps/portal/pages/ContentPage.tsx, 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"]
 async function executeInstallation(filePath: string, options: any): Promise<void> {
   try {
     console.log(`🚀 Executing installation from ${filePath}...`)
 
-    // First validate
     await validateInstructionFile(filePath)
 
     const content = readFileSync(filePath, 'utf8')
     const instructions = yaml.load(content) as any
 
-    // Set up context
     const context: InstallationContext = {
       TARGET_ACCOUNT_ID: options.accountId,
       ...instructions.variables
@@ -153,17 +161,14 @@ async function executeInstallation(filePath: string, options: any): Promise<void
     console.log(`  Target Account: ${context.TARGET_ACCOUNT_ID}`)
     console.log()
 
-    // Step 1: Pack installation
     console.log('📦 Step 1: Installing pack...')
     const packInstall = substituteVariables(instructions.installation.pack_installation, context)
     console.log('  Pack installation config:', JSON.stringify(packInstall, null, 2))
     
-    // Simulate pack installation - in real implementation, this would call the API
     const packInstallationId = 'simulated-pack-id-' + Date.now()
     context.PACK_INSTALLATION_ID = packInstallationId
     console.log(`  ✅ Pack installed with ID: ${packInstallationId}`)
 
-    // Step 2: App creation
     console.log('⚙️  Step 2: Creating app definitions...')
     if (instructions.installation.app_creation) {
       for (const appDef of instructions.installation.app_creation) {
@@ -174,7 +179,6 @@ async function executeInstallation(filePath: string, options: any): Promise<void
       }
     }
 
-    // Step 3: Migrations
     console.log('🔄 Step 3: Running migrations...')
     if (instructions.installation.migrations) {
       for (const migration of instructions.installation.migrations) {
@@ -187,7 +191,6 @@ async function executeInstallation(filePath: string, options: any): Promise<void
       }
     }
 
-    // Step 4: Verification
     console.log('✅ Step 4: Verifying installation...')
     if (instructions.installation.verification) {
       for (const verification of instructions.installation.verification) {
@@ -207,23 +210,21 @@ async function executeInstallation(filePath: string, options: any): Promise<void
     process.exit(1)
   }
 }
-// ─── CHUNK_END: APP_INSTALL_CLI_EXECUTE_INSTALLATION ────────────────────────────────────────────────
-
-// ─── CHUNK_START: APP_INSTALL_CLI_GENERATE_TEMPLATE ──────────────────────────────────────────────
-/**
- * @chunk-id    APP_INSTALL_CLI_GENERATE_TEMPLATE_1_0_0
- * @version     1.0.0
- * @hash        4ea17e0556f329f835cec106f09cb570c9e4ea8a92bc82e5fe9ccf4b5dd52aa9
- * @macro       Template Generator
- * @micro       Outputs YAML templates for app installations or migrations
- * @inputs      type: string — Template type ("app" or "migration")
- * @inputs      options: any — CLI options including output file path
- * @outputs     void — Console output or file write
- * @depends-on  [fs, path]
- * @depended-by [CLI program command handler]
- * @side-effects [console output, file system reads/writes, process.exit on failure]
- * @tags        orphaned, template-generation, yaml, cli
- */
+// CIL[END chunk_id="app-install-cli_executeinstallation_1783931090"]
+// CIL[BEGIN chunk_id="app-install-cli_generatetemplate_1783931090" type="function" identity="generateTemplate" parent="none"]
+// CIL[DOC-MACRO purpose="Generate YAML templates for app installations or migrations"]
+// CIL[DOC-RESPONSIBILITY responsibility="Template generation and file output management"]
+// CIL[DOC-CONTEXT module="app-install-cli" layer="cli" related_files="[]"]
+// CIL[DOC-CONTRACT inputs="none" outputs="template content" errors="Template loading failures" side_effects="File writes, console output"]
+// CIL[DOC-MICRO logic_summary="Resolves template paths, loads files, outputs to file or stdout" notable_decisions="['template_type_switching', 'output_option_handling']"]
+// CIL[DOC-CONFIDENCE pass="second" score="0.95" flags="external_symbols_unknown"]
+// CIL[DOC-STABILITY stability="stable"]
+// CIL[DOC-VECTOR type="context" content="Layer: cli. 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"]
 async function generateTemplate(type: string, options: any): Promise<void> {
   try {
     const templateDir = resolve(__dirname, '../docs/app-installation/templates')
@@ -254,9 +255,21 @@ async function generateTemplate(type: string, options: any): Promise<void> {
     process.exit(1)
   }
 }
-// ─── CHUNK_END: APP_INSTALL_CLI_GENERATE_TEMPLATE ────────────────────────────────────────────────
-
-// CLI setup
+// CIL[END chunk_id="app-install-cli_generatetemplate_1783931090"]
+// CIL[BEGIN chunk_id="app-install-cli_cli_setup_1783931090" type="cli_setup" identity="cli_setup" parent="none"]
+// CIL[DOC-MACRO purpose="Define CLI commands and argument parsing"]
+// CIL[DOC-RESPONSIBILITY responsibility="Set up commander.js CLI interface with commands and options"]
+// CIL[DOC-CONTEXT module="app-install-cli" layer="cli" related_files="[]"]
+// CIL[DOC-CONTRACT inputs="none" outputs="CLI interface" errors="Command parsing errors" side_effects="CLI execution"]
+// CIL[DOC-MICRO logic_summary="Configures validate, install, and template commands with arguments and options" notable_decisions="['commander_setup', 'action_binding']"]
+// CIL[DOC-CONFIDENCE pass="second" score="0.95" flags="none"]
+// CIL[DOC-STABILITY stability="stable"]
+// CIL[DOC-VECTOR type="context" content="Layer: cli. 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"]
 program
   .name('app-install-cli')
   .description('Spine App Installation CLI - Validate and execute app installation instructions')
@@ -284,3 +297,4 @@ program
   .action(generateTemplate)
 
 program.parse()
+// CIL[END chunk_id="app-install-cli_cli_setup_1783931090"]

package/.framework/src/App.tsx

@@ -1,3 +1,22 @@
+
+
+
+
+// CIL[BEGIN chunk_id="App_module_header_1783931090" type="module_header" identity="imports" parent="none"]
+// CIL[DOC-MACRO purpose="Import React and routing dependencies for main app component"]
+// CIL[DOC-RESPONSIBILITY responsibility="Manage all external module imports and lazy loading"]
+// CIL[DOC-CONTEXT module="App" layer="entry-point" 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 and lazy components" errors="Import failures" side_effects="Module loading"]
+// CIL[DOC-MICRO logic_summary="Imports React hooks, routing components, pages, and app shell components" notable_decisions="['lazy_load_admin_app']"]
+// 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: entry-point. 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 { Suspense, lazy, useEffect } from 'react'
 import { Routes, Route, Navigate, useNavigate, useLocation } from 'react-router-dom'
 import { useAuth } from './contexts/AuthContext'
@@ -15,9 +34,22 @@ import { CustomAppLoader } from './components/CustomAppLoader'
 import { GenericAppShell } from './components/app-shell/GenericAppShell'
 import { APIPage } from './pages/spine-framework/APIPage'
 import { CLIPage } from './pages/spine-framework/CLIPage'
-
 const AdminApp = lazy(() => import('./apps/admin/index'))
-
+// CIL[END chunk_id="App_module_header_1783931090"]
+// CIL[BEGIN chunk_id="App_app_1783931090" type="function" identity="App" parent="none"]
+// CIL[DOC-MACRO purpose="Root app component handling authentication state and routing"]
+// CIL[DOC-RESPONSIBILITY responsibility="Manage global app state, auth flows, and route selection"]
+// CIL[DOC-CONTEXT module="App" layer="entry-point" related_files="[\"custom/apps/portal/pages/ContentPage.tsx\",\".framework/migrations/015_simplify_apps_table.sql\",\".framework/src/components/ui/dialog.tsx\",\"custom/apps/cortex/pages/operations/OperationsDashboard.tsx\",\"\\\"]"]
+// CIL[DOC-CONTRACT inputs="none" outputs="JSX routes based on auth state" errors="Auth context failures" side_effects="Navigation, route rendering"]
+// CIL[DOC-MICRO logic_summary="Shows loading, handles auth states, routes to appropriate components" notable_decisions="['ternary_auth_routing', 'setup_mode_check']"]
+// CIL[DOC-CONFIDENCE pass="second" score="0.95" flags="none"]
+// CIL[DOC-STABILITY stability="stable"]
+// CIL[DOC-VECTOR type="context" content="Layer: entry-point. Direct callers: 0. Direct calls: 0. Related files: custom/apps/portal/pages/ContentPage.tsx, .framework/migrations/015_simplify_apps_table.sql, .framework/src/components/ui/dialog.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"]
 function App() {
   const { user, isLoading } = useAuth()
 
@@ -40,7 +72,6 @@ function App() {
           <Route path="/register" element={<RegisterPage />} />
           <Route path="/forgot-password" element={<ForgotPasswordPage />} />
           <Route path="/auth/confirm" element={<AuthConfirmPage />} />
-          {/* / shows setup instructions only when VITE_SETUP_MODE=true */}
           <Route
             path="/"
             element={
@@ -52,7 +83,6 @@ function App() {
           <Route path="*" element={<Navigate to="/login" replace />} />
         </Routes>
       ) : user.status === 'pending' ? (
-        // Access request submitted but not yet approved — block full app access
         <Routes>
           <Route path="*" element={<PendingApprovalPage />} />
         </Routes>
@@ -62,22 +92,32 @@ function App() {
     </AppsRegistryProvider>
   )
 }
-
+// CIL[END chunk_id="App_app_1783931090"]
+// CIL[BEGIN chunk_id="App_authenticatedrouter_1783931090" type="function" identity="AuthenticatedRouter" parent="none"]
+// CIL[DOC-LEARNING topic="App:renderer_switch" content="The public.apps.renderer field switches routing: 'custom' uses CustomAppLoader and loads custom/apps/<slug>/index.tsx; 'generic' uses GenericAppShell and builds a schema-driven UI from nav_items."]
+// CIL[DOC-MACRO purpose="Handle authenticated user routing and dynamic app loading"]
+// CIL[DOC-RESPONSIBILITY responsibility="Manage app registry, route sorting, and dynamic component rendering"]
+// CIL[DOC-CONTEXT module="App" layer="routing" 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="Dynamic routes for authenticated apps" errors="App loading failures" side_effects="Navigation, lazy loading"]
+// CIL[DOC-MICRO logic_summary="Loads apps, sorts routes, handles redirects, renders dynamic app components" notable_decisions="['route_prefix_sorting', 'renderer_type_switching']"]
+// CIL[DOC-CONFIDENCE pass="second" score="0.95" flags="none"]
+// CIL[DOC-STABILITY stability="stable"]
+// CIL[DOC-VECTOR type="context" content="Layer: routing. 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"]
 function AuthenticatedRouter() {
   const { user } = useAuth()
   const { routableApps: apps, loading } = useAppsRegistry()
   const navigate = useNavigate()
   const location = useLocation()
 
-  // Where to send an already-authenticated user who lands on /login or /register.
-  // System admins go to the framework admin namespace; everyone else goes to the
-  // first app they are allowed to access (routableApps is already role-filtered).
   const defaultRedirect = user?.roles?.includes('system_admin')
     ? '/spine-framework/admin'
     : (apps[0]?.route_prefix || '/')
 
-  // Redirect away from auth pages once apps have loaded.
-  // This fires reliably after loading completes, regardless of render timing.
   useEffect(() => {
     if (!loading && ['/login', '/register'].includes(location.pathname)) {
       navigate(defaultRedirect, { replace: true })
@@ -95,35 +135,28 @@ function AuthenticatedRouter() {
     )
   }
 
-  // Sort: longer explicit prefixes first (most specific), root (/) last.
-  // The /spine-framework namespace is registered statically before dynamic routes
-  // so it always wins — but also filter it from dynamic registration to be safe.
   const sorted = [...apps]
     .filter(app => app.slug !== 'spine-framework' && !app.route_prefix?.startsWith('/spine-framework'))
     .sort((a, b) => {
-      if (a.route_prefix === '/') return 1   // root always last
+      if (a.route_prefix === '/') return 1
       if (b.route_prefix === '/') return -1
       return (b.route_prefix?.length || 0) - (a.route_prefix?.length || 0)
     })
 
-  // Build a valid route path: prefix "/" must become "/*", not "//*"
   const toRoutePath = (prefix: string) => prefix === '/' ? '/*' : `${prefix}/*`
 
   return (
     <Suspense fallback={<div className="min-h-screen flex items-center justify-center"><LoadingSpinner /></div>}>
       <Routes>
-        {/* ── Spine Framework namespace — registered first, always wins over /* ── */}
         <Route path="/spine-framework/admin/*" element={<AdminApp />} />
         <Route path="/spine-framework/api" element={<APIPage />} />
         <Route path="/spine-framework/cli" element={<CLIPage />} />
 
-        {/* Auth routes: redirect handled by useEffect above, but keep as fallback */}
         <Route path="/login" element={<Navigate to={defaultRedirect} replace />} />
         <Route path="/register" element={<RegisterPage />} />
         <Route path="/forgot-password" element={<ForgotPasswordPage />} />
         <Route path="/auth/confirm" element={<AuthConfirmPage />} />
 
-        {/* Dynamic app routes — no framework opinions about / or /dashboard */}
         {sorted.map(app => {
           const prefix = app.route_prefix!
 
@@ -158,11 +191,25 @@ function AuthenticatedRouter() {
           return null
         })}
 
-        {/* No apps claim this path */}
         <Route path="*" element={<NotFoundPage />} />
       </Routes>
     </Suspense>
   )
 }
-
+// CIL[END chunk_id="App_authenticatedrouter_1783931090"]
+// CIL[BEGIN chunk_id="App_export_1783931090" type="export" identity="export_default" parent="none"]
+// CIL[DOC-MACRO purpose="Export the main App component as default"]
+// CIL[DOC-RESPONSIBILITY responsibility="Provide the entry point for the React application"]
+// CIL[DOC-CONTEXT module="App" layer="entry-point" related_files="[\"custom/apps/cortex/pages/operations/OperationsDashboard.tsx\",\".framework/migrations/015_simplify_apps_table.sql\",\"custom/apps/portal/pages/ContentPage.tsx\",\".framework/src/components/ui/table-primitives.tsx\",\"\\\"]"]
+// CIL[DOC-CONTRACT inputs="none" outputs="App component" errors="none" side_effects="Application bootstrap"]
+// CIL[DOC-MICRO logic_summary="Default export of the root App component" notable_decisions="[]"]
+// CIL[DOC-CONFIDENCE pass="second" score="1.00" flags="none"]
+// CIL[DOC-STABILITY stability="stable"]
+// CIL[DOC-VECTOR type="context" content="Layer: entry-point. Direct callers: 0. Direct calls: 0. Related files: custom/apps/cortex/pages/operations/OperationsDashboard.tsx, .framework/migrations/015_simplify_apps_table.sql, 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"]
 export default App
+// CIL[END chunk_id="App_export_1783931090"]