spine-framework 0.3.124 → 0.3.126

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

@@ -1,20 +1,30 @@
-/**
- * @module src/pages/admin/TestingDashboard
- * @audience installer
- * @layer frontend-page
- * @stability stable
- *
- * Admin Testing dashboard. Shows per-suite health cards (unit, integration,
- * api, ui) and a table of the 20 most recent test runs. Read-only — tests
- * are triggered by the agentic IDE, not from this UI.
- *
- * Route: /admin/testing
- *
- * @seeAlso src/pages/admin/TestRunDetailPage.tsx
- * @seeAlso functions/tests.ts (data source)
- * @seeAlso migrations_dayzero/008_test_runs.sql
- */
 
+
+
+
+
+
+
+
+
+
+
+
+// CIL[BEGIN chunk_id="testingdashboard_module_header_1783665503" type="module_header" identity="module_header" parent="none"]
+// CIL[DOC-MACRO purpose="Import React, router, API hooks and define testing interfaces"]
+// CIL[DOC-RESPONSIBILITY responsibility="Provide React components and test data types"]
+// CIL[DOC-CONTEXT module="TestingDashboard" layer="frontend-page" related_files="[\"custom/apps/cortex/pages/operations/OperationsDashboard.tsx\",\"custom/apps/portal/pages/ContentPage.tsx\",\".framework/src/pages/admin/IntegrationsPage.tsx\",\".framework/functions/_shared/principal.ts\",\".framework/functions/_shared/schema-utils.ts\",\"\\\"]"]
+// CIL[DOC-CONTRACT inputs="none" outputs="React components and test interfaces" errors="none" side_effects="none"]
+// CIL[DOC-MICRO logic_summary="Imports testing dependencies and defines SuiteStat and TestRun types" notable_decisions="[]"]
+// CIL[DOC-CONFIDENCE pass="second" score="0.95" flags="none"]
+// CIL[DOC-STABILITY stability="stable"]
+// CIL[DOC-AUDIENCE audience="developer"]
+// CIL[DOC-VECTOR type="context" content="Layer: frontend-page. Direct callers: 0. Direct calls: 0. Related files: custom/apps/cortex/pages/operations/OperationsDashboard.tsx, custom/apps/portal/pages/ContentPage.tsx, .framework/src/pages/admin/IntegrationsPage.tsx, .framework/functions/_shared/principal.ts, .framework/functions/_shared/schema-utils.ts, \."]
+// CIL[DOC-VECTOR type="blast_radius" content="Direct callers: 0. Total affected: 0."]
+// CIL[DOC-VECTOR type="configuration" content="No configuration dependencies."]
+// CIL[DOC-VECTOR type="constraint" content="No test paths identified."]
+// CIL[DOC-VECTOR type="implementation_pattern" content="" status="pending_human_input"]
+// CIL[DOC-VECTOR type="user_journey" content="" status="pending_human_input"]
 import React from 'react'
 import { useNavigate } from 'react-router-dom'
 import { useApi } from '../../hooks/useApi'
@@ -24,8 +34,6 @@ import { FlaskConical, CheckCircle, XCircle, Clock, RefreshCw } from 'lucide-rea
 import { LoadingSpinner } from '../../components/ui/LoadingSpinner'
 import { formatDateTime } from '../../lib/utils'
 
-// ─── TYPES ───────────────────────────────────────────────────────────────────
-
 interface SuiteStat {
   suite:        string
   total_runs:   number
@@ -49,9 +57,22 @@ interface TestRun {
   skipped:      number | null
   triggered_by: string | null
 }
-
-// ─── HELPERS ─────────────────────────────────────────────────────────────────
-
+import { PageInstructions } from '../../components/admin/PageInstructions'
+// CIL[END chunk_id="testingdashboard_module_header_1783665503"]
+// CIL[BEGIN chunk_id="testingdashboard_helpers_1783665503" type="module" identity="helpers" parent="none"]
+// CIL[DOC-MACRO purpose="Provide helper constants and utility functions for testing dashboard"]
+// CIL[DOC-RESPONSIBILITY responsibility="Define suite labels, status badge, and duration formatting"]
+// CIL[DOC-CONTEXT module="TestingDashboard" layer="frontend-page" related_files="[\"custom/apps/cortex/pages/operations/OperationsDashboard.tsx\",\"custom/apps/portal/pages/ContentPage.tsx\",\"custom/apps/cortex/functions/custom_cil-embeddings.ts\",\".framework/functions/_shared/principal.ts\",\".framework/functions/_shared/schema-utils.ts\",\"\\\"]"]
+// CIL[DOC-CONTRACT inputs="none" outputs="formatted UI elements" errors="none" side_effects="none"]
+// CIL[DOC-MICRO logic_summary="Creates status badges, duration labels, and suite name mappings" notable_decisions="[]"]
+// CIL[DOC-CONFIDENCE pass="second" score="0.95" flags="none"]
+// CIL[DOC-STABILITY stability="stable"]
+// CIL[DOC-VECTOR type="context" content="Layer: frontend-page. Direct callers: 0. Direct calls: 0. Related files: custom/apps/cortex/pages/operations/OperationsDashboard.tsx, custom/apps/portal/pages/ContentPage.tsx, custom/apps/cortex/functions/custom_cil-embeddings.ts, .framework/functions/_shared/principal.ts, .framework/functions/_shared/schema-utils.ts, \."]
+// CIL[DOC-VECTOR type="blast_radius" content="Direct callers: 0. Total affected: 0."]
+// CIL[DOC-VECTOR type="configuration" content="No configuration dependencies."]
+// CIL[DOC-VECTOR type="constraint" content="No test paths identified."]
+// CIL[DOC-VECTOR type="implementation_pattern" content="" status="pending_human_input"]
+// CIL[DOC-VECTOR type="user_journey" content="" status="pending_human_input"]
 const SUITE_LABELS: Record<string, string> = {
   unit:        'Unit',
   integration: 'Integration',
@@ -78,9 +99,21 @@ function durationLabel(ms: number | null): string {
   if (ms < 1000) return `${ms}ms`
   return `${(ms / 1000).toFixed(1)}s`
 }
-
-// ─── SUITE HEALTH CARD ───────────────────────────────────────────────────────
-
+// CIL[END chunk_id="testingdashboard_helpers_1783665503"]
+// CIL[BEGIN chunk_id="testingdashboard_suitecard_1783665503" type="function" identity="SuiteCard" parent="none"]
+// CIL[DOC-MACRO purpose="Render test suite health card with status and statistics"]
+// CIL[DOC-RESPONSIBILITY responsibility="Display suite stats in a formatted card component"]
+// CIL[DOC-CONTEXT module="TestingDashboard" layer="frontend-page" related_files="[\"custom/apps/portal/pages/ContentPage.tsx\",\".framework/src/pages/admin/RolesPage.tsx\",\"custom/apps/cortex/pages/operations/OperationsDashboard.tsx\",\".framework/src/pages/admin/IntegrationsPage.tsx\",\"\\\"]"]
+// CIL[DOC-CONTRACT inputs="none" outputs="JSX card element" errors="none" side_effects="none"]
+// CIL[DOC-MICRO logic_summary="Calculates pass rate and renders suite status with metrics" notable_decisions="[]"]
+// CIL[DOC-CONFIDENCE pass="second" score="0.95" flags="none"]
+// CIL[DOC-STABILITY stability="stable"]
+// CIL[DOC-VECTOR type="context" content="Layer: frontend-page. Direct callers: 0. Direct calls: 0. Related files: custom/apps/portal/pages/ContentPage.tsx, .framework/src/pages/admin/RolesPage.tsx, custom/apps/cortex/pages/operations/OperationsDashboard.tsx, .framework/src/pages/admin/IntegrationsPage.tsx, \."]
+// CIL[DOC-VECTOR type="blast_radius" content="Direct callers: 0. Total affected: 0."]
+// CIL[DOC-VECTOR type="configuration" content="No configuration dependencies."]
+// CIL[DOC-VECTOR type="constraint" content="No test paths identified."]
+// CIL[DOC-VECTOR type="implementation_pattern" content="" status="pending_human_input"]
+// CIL[DOC-VECTOR type="user_journey" content="" status="pending_human_input"]
 function SuiteCard({ stat }: { stat: SuiteStat }) {
   const label = SUITE_LABELS[stat.suite] ?? stat.suite
   const passRate = stat.last_total
@@ -113,9 +146,21 @@ function SuiteCard({ stat }: { stat: SuiteStat }) {
     </div>
   )
 }
-
-// ─── PAGE ────────────────────────────────────────────────────────────────────
-
+// CIL[END chunk_id="testingdashboard_suitecard_1783665503"]
+// CIL[BEGIN chunk_id="testingdashboard_testingdashboard_1783665503" type="function" identity="TestingDashboard" parent="none"]
+// CIL[DOC-MACRO purpose="Render testing dashboard with suite health cards and recent runs table"]
+// CIL[DOC-RESPONSIBILITY responsibility="Display suite stats, recent runs, and navigation to test details"]
+// CIL[DOC-CONTEXT module="TestingDashboard" layer="frontend-page" related_files="[\"custom/apps/portal/pages/ContentPage.tsx\",\"custom/apps/cortex/pages/operations/OperationsDashboard.tsx\",\".framework/src/pages/admin/RolesPage.tsx\",\".framework/src/components/ui/dialog.tsx\",\".framework/functions/_shared/principal.ts\",\"\\\"]"]
+// CIL[DOC-CONTRACT inputs="none" outputs="Complete dashboard UI" errors="none" side_effects="none"]
+// CIL[DOC-MICRO logic_summary="Renders header, suite cards grid, and recent runs table with navigation" notable_decisions="[]"]
+// CIL[DOC-CONFIDENCE pass="second" score="0.95" flags="none"]
+// CIL[DOC-STABILITY stability="stable"]
+// CIL[DOC-VECTOR type="context" content="Layer: frontend-page. 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/RolesPage.tsx, .framework/src/components/ui/dialog.tsx, .framework/functions/_shared/principal.ts, \."]
+// CIL[DOC-VECTOR type="blast_radius" content="Direct callers: 0. Total affected: 0."]
+// CIL[DOC-VECTOR type="configuration" content="No configuration dependencies."]
+// CIL[DOC-VECTOR type="constraint" content="No test paths identified."]
+// CIL[DOC-VECTOR type="implementation_pattern" content="" status="pending_human_input"]
+// CIL[DOC-VECTOR type="user_journey" content="" status="pending_human_input"]
 export default function TestingDashboard() {
   const navigate = useNavigate()
 
@@ -136,10 +181,23 @@ export default function TestingDashboard() {
     refreshRuns()
   }
 
-  // API returns { data: { data: [...], error: null }, error: null, meta: {...} }
   const stats: SuiteStat[] = (statsData as any)?.data?.data ?? []
   const runs: TestRun[]    = (runsData as any)?.data?.data  ?? []
 
+  // CIL[BEGIN chunk_id="testingdashboard_return_1783665503" type="jsx" identity="return" parent="testingdashboard_testingdashboard_1783665503"]
+// CIL[DOC-MACRO purpose="Render testing dashboard with suite health cards and recent runs table"]
+// CIL[DOC-RESPONSIBILITY responsibility="Handle return"]
+// CIL[DOC-CONTEXT module="TestingDashboard" layer="frontend-page" related_files="[\"custom/apps/portal/pages/ContentPage.tsx\",\"custom/apps/cortex/pages/operations/OperationsDashboard.tsx\",\".framework/src/pages/admin/RolesPage.tsx\",\".framework/src/components/ui/dialog.tsx\",\".framework/functions/_shared/principal.ts\",\"\\\"]"]
+// CIL[DOC-CONTRACT inputs="none" outputs="Complete dashboard UI" errors="none" side_effects="none"]
+// CIL[DOC-MICRO logic_summary="Renders header, suite cards grid, and recent runs table with navigation" notable_decisions="[]"]
+// CIL[DOC-CONFIDENCE pass="second" score="0.95" flags="none"]
+// CIL[DOC-STABILITY stability="stable"]
+// CIL[DOC-VECTOR type="context" content="Layer: frontend-page. 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/RolesPage.tsx, .framework/src/components/ui/dialog.tsx, .framework/functions/_shared/principal.ts, \."]
+// CIL[DOC-VECTOR type="blast_radius" content="Direct callers: 0. Total affected: 0."]
+// CIL[DOC-VECTOR type="configuration" content="No configuration dependencies."]
+// CIL[DOC-VECTOR type="constraint" content="No test paths identified."]
+// CIL[DOC-VECTOR type="implementation_pattern" content="" status="pending_human_input"]
+// CIL[DOC-VECTOR type="user_journey" content="" status="pending_human_input"]
   return (
     <div className="p-6 max-w-6xl mx-auto">
       {/* Header */}
@@ -157,6 +215,16 @@ export default function TestingDashboard() {
         </button>
       </div>
 
+      <PageInstructions
+        description="Run and review Spine test suites."
+        sections={[
+          { title: 'What this page is for', content: 'This page displays the health and history of the unit, integration, API, and UI test suites.' },
+          { title: 'How to read the cards', content: 'The suite health cards show the most recent run status, pass rate, total runs, and last run time. Colors indicate passed, failed, running, or unknown states.' },
+          { title: 'How to use this page', content: 'Click the Refresh button to reload stats and runs. Click a row in the Recent Runs table to view individual test case results. Suites are triggered from the IDE or CI pipeline.' },
+          { title: 'Important notes', content: 'A pass rate below 100% is shown in red. Empty states mean no runs have been recorded yet for that suite.' },
+        ]}
+      />
+
       {/* Suite health cards */}
       {statsLoading ? (
         <div className="flex justify-center py-8"><LoadingSpinner /></div>
@@ -254,4 +322,6 @@ export default function TestingDashboard() {
       )}
     </div>
   )
+// CIL[END chunk_id="testingdashboard_return_1783665503"]
 }
+// CIL[END chunk_id="testingdashboard_testingdashboard_1783665503"]

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

@@ -1,6 +1,22 @@
-/**
- * @module src/pages/admin/TimerDetailPage
- */
+
+
+
+
+// CIL[BEGIN chunk_id="timerdetailpage_moduleheader_1783664706" type="module_header" identity="module_header" parent="none"]
+// CIL[DOC-MACRO purpose="Import dependencies for TimerDetailPage component"]
+// CIL[DOC-RESPONSIBILITY responsibility="Provide all external dependencies and UI components"]
+// CIL[DOC-CONTEXT module="TimerDetailPage" layer="frontend-page" related_files="[\".framework/src/components/ui/dialog.tsx\",\"custom/apps/cortex/pages/operations/OperationsDashboard.tsx\",\"custom/apps/portal/pages/ContentPage.tsx\",\".framework/src/pages/admin/TypeDetailPage.tsx\",\".framework/src/pages/admin/RolesPage.tsx\",\"\\\"]"]
+// CIL[DOC-CONTRACT inputs="none" outputs="React components and utilities" errors="none" side_effects="none"]
+// CIL[DOC-MICRO logic_summary="Imports React hooks, navigation, API utilities, and UI components" notable_decisions="[]"]
+// CIL[DOC-CONFIDENCE pass="second" score="0.95" flags="none"]
+// CIL[DOC-STABILITY stability="stable"]
+// CIL[DOC-AUDIENCE audience="developer"]
+// CIL[DOC-VECTOR type="context" content="Layer: frontend-page. Direct callers: 0. Direct calls: 0. Related files: .framework/src/components/ui/dialog.tsx, custom/apps/cortex/pages/operations/OperationsDashboard.tsx, custom/apps/portal/pages/ContentPage.tsx, .framework/src/pages/admin/TypeDetailPage.tsx, .framework/src/pages/admin/RolesPage.tsx, \."]
+// CIL[DOC-VECTOR type="blast_radius" content="Direct callers: 0. Total affected: 0."]
+// CIL[DOC-VECTOR type="configuration" content="No configuration dependencies."]
+// CIL[DOC-VECTOR type="constraint" content="No test paths identified."]
+// CIL[DOC-VECTOR type="implementation_pattern" content="" status="pending_human_input"]
+// CIL[DOC-VECTOR type="user_journey" content="" status="pending_human_input"]
 import { useState, useEffect } from 'react'
 import { useParams, useNavigate } from 'react-router-dom'
 import { apiFetch } from '../../lib/api'
@@ -16,31 +32,70 @@ import { Alert, AlertDescription, AlertTitle } from '../../components/ui/alert'
 import { Badge } from '../../components/ui/badge'
 import { ArrowLeft, Clock, AlertCircle } from 'lucide-react'
 import { formatDateTime } from '../../lib/utils'
-
+import { PageInstructions } from '../../components/admin/PageInstructions'
+// CIL[END chunk_id="timerdetailpage_moduleheader_1783664706"]
+// CIL[BEGIN chunk_id="timerdetailpage_timer_1783664706" type="interface" identity="Timer" parent="none"]
+// CIL[DOC-MACRO purpose="Define the Timer data structure for timer management"]
+// CIL[DOC-RESPONSIBILITY responsibility="Provide type definition for scheduled/recurring timers"]
+// CIL[DOC-CONTEXT module="TimerDetailPage" layer="frontend-page" related_files="[\".framework/src/pages/admin/IntegrationsPage.tsx\",\".framework/functions/_shared/principal.ts\",\"custom/apps/cortex/pages/operations/OperationsDashboard.tsx\",\".framework/functions/_shared/schema-utils.ts\",\".framework/src/pages/admin/TypeDetailPage.tsx\",\"\\\"]"]
+// CIL[DOC-CONTRACT inputs="none" outputs="Timer interface" errors="none" side_effects="none"]
+// CIL[DOC-MICRO logic_summary="Defines timer structure with execution tracking and target configuration" notable_decisions="[]"]
+// CIL[DOC-CONFIDENCE pass="second" score="0.95" flags="none"]
+// CIL[DOC-STABILITY stability="stable"]
+// CIL[DOC-VECTOR type="context" content="Layer: frontend-page. Direct callers: 0. Direct calls: 0. Related files: .framework/src/pages/admin/IntegrationsPage.tsx, .framework/functions/_shared/principal.ts, custom/apps/cortex/pages/operations/OperationsDashboard.tsx, .framework/functions/_shared/schema-utils.ts, .framework/src/pages/admin/TypeDetailPage.tsx, \."]
+// CIL[DOC-VECTOR type="blast_radius" content="Direct callers: 0. Total affected: 0."]
+// CIL[DOC-VECTOR type="configuration" content="No configuration dependencies."]
+// CIL[DOC-VECTOR type="constraint" content="No test paths identified."]
+// CIL[DOC-VECTOR type="implementation_pattern" content="" status="pending_human_input"]
+// CIL[DOC-VECTOR type="user_journey" content="" status="pending_human_input"]
 interface Timer {
   id: string
   name: string
   description?: string
-  schedule: string
+  app_id?: string
   timer_type: 'interval' | 'cron' | 'once'
-  interval_seconds?: number
-  next_run?: string
-  last_run?: string
-  last_run_status?: 'success' | 'failed'
+  config?: Record<string, any>
+  pipeline_id?: string
+  metadata?: Record<string, any>
   is_active: boolean
-  target_type: string
-  target_action: string
-  target_config: Record<string, any>
   created_at: string
   updated_at: string
 }
-
+// CIL[END chunk_id="timerdetailpage_timer_1783664706"]
+// CIL[BEGIN chunk_id="timerdetailpage_timertypes_1783664706" type="constant" identity="TIMER_TYPES" parent="none"]
+// CIL[DOC-MACRO purpose="Define timer type options for form selection"]
+// CIL[DOC-RESPONSIBILITY responsibility="Provide timer type configuration options"]
+// CIL[DOC-CONTEXT module="TimerDetailPage" layer="frontend-page" related_files="[\".framework/src/pages/admin/TypeDetailPage.tsx\",\".framework/functions/_shared/schema-utils.ts\",\".framework/functions/_shared/principal.ts\",\".framework/migrations/025_retype_threads_messages.sql\",\"custom/apps/cortex/pages/operations/OperationsDashboard.tsx\",\"\\\"]"]
+// CIL[DOC-CONTRACT inputs="none" outputs="TIMER_TYPES constant" errors="none" side_effects="none"]
+// CIL[DOC-MICRO logic_summary="Defines available timer types: interval, cron, and one-time" notable_decisions="[]"]
+// CIL[DOC-CONFIDENCE pass="second" score="0.95" flags="none"]
+// CIL[DOC-STABILITY stability="stable"]
+// CIL[DOC-VECTOR type="context" content="Layer: frontend-page. Direct callers: 0. Direct calls: 0. Related files: .framework/src/pages/admin/TypeDetailPage.tsx, .framework/functions/_shared/schema-utils.ts, .framework/functions/_shared/principal.ts, .framework/migrations/025_retype_threads_messages.sql, 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"]
 const TIMER_TYPES = [
   { value: 'interval', label: 'Interval' },
   { value: 'cron', label: 'Cron Expression' },
   { value: 'once', label: 'One-time' }
 ]
-
+// CIL[END chunk_id="timerdetailpage_timertypes_1783664706"]
+// CIL[BEGIN chunk_id="timerdetailpage_timerdetailpage_1783664706" type="function" identity="TimerDetailPage" parent="none"]
+// CIL[DOC-MACRO purpose="Create/view/edit/delete page for single timer records"]
+// CIL[DOC-RESPONSIBILITY responsibility="Manage timer CRUD operations with form handling and validation"]
+// CIL[DOC-CONTEXT module="TimerDetailPage" layer="frontend-page" related_files="[\".framework/src/pages/admin/TypeDetailPage.tsx\",\"custom/apps/portal/pages/ContentPage.tsx\",\"custom/apps/cortex/pages/operations/OperationsDashboard.tsx\",\".framework/src/pages/admin/RolesPage.tsx\",\"\\\"]"]
+// CIL[DOC-CONTRACT inputs="none" outputs="React component with timer form" errors="API failures, validation errors" side_effects="API calls, navigation"]
+// CIL[DOC-MICRO logic_summary="Form handling with timer configuration and execution tracking" notable_decisions="[]"]
+// CIL[DOC-CONFIDENCE pass="second" score="0.95" flags="none"]
+// CIL[DOC-STABILITY stability="stable"]
+// CIL[DOC-VECTOR type="context" content="Layer: frontend-page. Direct callers: 0. Direct calls: 0. Related files: .framework/src/pages/admin/TypeDetailPage.tsx, custom/apps/portal/pages/ContentPage.tsx, custom/apps/cortex/pages/operations/OperationsDashboard.tsx, .framework/src/pages/admin/RolesPage.tsx, \."]
+// CIL[DOC-VECTOR type="blast_radius" content="Direct callers: 0. Total affected: 0."]
+// CIL[DOC-VECTOR type="configuration" content="No configuration dependencies."]
+// CIL[DOC-VECTOR type="constraint" content="No test paths identified."]
+// CIL[DOC-VECTOR type="implementation_pattern" content="" status="pending_human_input"]
+// CIL[DOC-VECTOR type="user_journey" content="" status="pending_human_input"]
 export function TimerDetailPage() {
   const { id } = useParams<{ id: string }>()
   const navigate = useNavigate()
@@ -49,7 +104,16 @@ export function TimerDetailPage() {
   const [loading, setLoading] = useState(true)
   const [error, setError] = useState<string | null>(null)
   const [isEditing, setIsEditing] = useState(isCreateMode)
-  const [formData, setFormData] = useState({ name: '', description: '', schedule: '', timer_type: 'interval' as const, interval_seconds: 3600, is_active: true, target_type: '', target_action: '', target_config: '{}' })
+  const [formData, setFormData] = useState({
+    name: '',
+    description: '',
+    app_id: '',
+    timer_type: 'interval' as const,
+    config: JSON.stringify({ schedule: '', interval_seconds: 3600 }, null, 2),
+    pipeline_id: '',
+    metadata: '{}',
+    is_active: true
+  })
 
   useEffect(() => {
     if (isCreateMode) {
@@ -65,9 +129,14 @@ export function TimerDetailPage() {
         const data = result.data
         setTimer(data)
         setFormData({
-          name: data.name, description: data.description || '', schedule: data.schedule, timer_type: data.timer_type,
-          interval_seconds: data.interval_seconds || 3600, is_active: data.is_active, target_type: data.target_type,
-          target_action: data.target_action, target_config: JSON.stringify(data.target_config || {}, null, 2)
+          name: data.name,
+          description: data.description || '',
+          app_id: data.app_id || '',
+          timer_type: data.timer_type,
+          config: JSON.stringify(data.config || {}, null, 2),
+          pipeline_id: data.pipeline_id || '',
+          metadata: JSON.stringify(data.metadata || {}, null, 2),
+          is_active: data.is_active ?? true
         })
       } catch (err) {
         setError(err instanceof Error ? err.message : 'Failed to load timer')
@@ -81,10 +150,22 @@ export function TimerDetailPage() {
   const handleSave = async () => {
     try {
       let parsedConfig = {}
-      try { parsedConfig = JSON.parse(formData.target_config) } catch { throw new Error('Invalid target config JSON') }
+      let parsedMetadata = {}
+      try { parsedConfig = JSON.parse(formData.config) } catch { throw new Error('Invalid config JSON') }
+      try { parsedMetadata = JSON.parse(formData.metadata) } catch { throw new Error('Invalid metadata JSON') }
       const url = isCreateMode ? '/api/timers?action=create' : `/api/timers?action=update&id=${id}`
       const method = isCreateMode ? 'POST' : 'PATCH'
-      const response = await apiFetch(url, { method, headers: { 'Content-Type': 'application/json' }, body: JSON.stringify({ ...formData, target_config: parsedConfig }) })
+      const saveData = {
+        name: formData.name,
+        description: formData.description,
+        app_id: formData.app_id || null,
+        timer_type: formData.timer_type,
+        config: parsedConfig,
+        pipeline_id: formData.pipeline_id || null,
+        metadata: parsedMetadata,
+        is_active: formData.is_active
+      }
+      const response = await apiFetch(url, { method, headers: { 'Content-Type': 'application/json' }, body: JSON.stringify(saveData) })
       if (!response.ok) throw new Error('Failed to save timer')
       if (isCreateMode) {
         const result = await response.json()
@@ -120,32 +201,61 @@ export function TimerDetailPage() {
         </div>
       </div>
 
-      <Card><CardContent className="p-6">
+      <PageInstructions
+        description="Schedule a timer to run actions at intervals, via cron, or once."
+        sections={[
+          { title: 'What this timer controls', content: 'A timer is a scheduled job that calls a target function or pipeline on an interval, a cron schedule, or one time. It is the Spine equivalent of a recurring or one-off background task.' },
+          { title: 'Fields explained', content: <ul className="list-disc pl-4 space-y-1">
+            <li><strong>Name</strong> — string. The display name. Missing name prevents saving.</li>
+            <li><strong>Type</strong> — select. interval, cron, or once. Controls which schedule field in Config is used and how the next run is calculated.</li>
+            <li><strong>App ID</strong> — string. Optional owning app UUID; blank means account-scoped.</li>
+            <li><strong>Pipeline ID</strong> — string. The pipeline to invoke when the timer fires.</li>
+            <li><strong>Active</strong> — checkbox. Inactive timers are skipped by the scheduler.</li>
+            <li><strong>Description</strong> — string. Optional notes.</li>
+            <li><strong>Config (JSON)</strong> — JSON. The timer schedule, e.g. { `{ "schedule": "0 */6 * * *" }` } for cron, { `{ "interval_seconds": 3600 }` } for interval, or { `{ "run_at": "2026-01-01T00:00:00Z" }` } for once.</li>
+            <li><strong>Metadata (JSON)</strong> — JSON. Optional metadata about the timer.</li>
+          </ul> },
+          { title: 'Options and values', content: <ul className="list-disc pl-4 space-y-1">
+            <li><strong>interval</strong>: config should contain interval_seconds.</li>
+            <li><strong>cron</strong>: config should contain a schedule cron expression like 0 */6 * * *.</li>
+            <li><strong>once</strong>: config should contain a run_at ISO timestamp.</li>
+          </ul> },
+          { title: 'Downstream impact', content: <ul className="list-disc pl-4 space-y-1">
+            <li>The scheduler uses the active flag and the timer_type/config fields to determine the next run and to enqueue the pipeline.</li>
+            <li>Pipeline ID must refer to an existing pipeline; otherwise the timer will fail with a missing handler.</li>
+          </ul> },
+          { title: 'How to create, save, and validate', content: <ol className="list-decimal pl-4 space-y-1">
+            <li>Pick the timer type and fill the Config JSON with the matching schedule. Enter the Pipeline ID and optional Metadata JSON.</li>
+            <li>Click Create to save or Edit then Save for existing timers.</li>
+            <li>Validation checks the name, timer type, and that Config and Metadata are valid JSON.</li>
+          </ol> },
+          { title: 'Common mistakes', content: <ul className="list-disc pl-4 space-y-1">
+            <li>Selecting cron but filling interval_seconds instead of a cron schedule.</li>
+            <li>Using an invalid cron expression, which the scheduler will not run.</li>
+            <li>Leaving Pipeline ID blank when the scheduler expects a pipeline to invoke.</li>
+          </ul> },
+        ]}
+      />
+
+      <Card><CardContent className="p-6 space-y-6">
         <div className="grid grid-cols-1 md:grid-cols-2 gap-6">
           <div className="space-y-4">
             <h3 className="text-sm font-medium text-muted-foreground">Configuration</h3>
             <div className="space-y-2"><Label>Name</Label>{isEditing ? <Input value={formData.name} onChange={e => setFormData({...formData, name: e.target.value})} /> : <div className="text-sm">{timer?.name}</div>}</div>
+            <div className="space-y-2"><Label>App ID</Label>{isEditing ? <Input value={formData.app_id} onChange={e => setFormData({...formData, app_id: e.target.value})} placeholder="Optional app UUID" /> : <div className="text-sm font-mono">{timer?.app_id || '—'}</div>}</div>
             <div className="space-y-2"><Label>Type</Label>{isEditing ? <Select value={formData.timer_type} onValueChange={v => setFormData({...formData, timer_type: v as any})}><SelectTrigger><SelectValue /></SelectTrigger><SelectContent>{TIMER_TYPES.map(t => <SelectItem key={t.value} value={t.value}>{t.label}</SelectItem>)}</SelectContent></Select> : <Badge>{timer?.timer_type}</Badge>}</div>
-            {formData.timer_type === 'interval' && <div className="space-y-2"><Label>Interval (seconds)</Label>{isEditing ? <Input type="number" value={formData.interval_seconds} onChange={e => setFormData({...formData, interval_seconds: parseInt(e.target.value)})} /> : <div className="text-sm">{timer?.interval_seconds}s</div>}</div>}
-            <div className="space-y-2"><Label>Schedule/Cron</Label>{isEditing ? <Input value={formData.schedule} onChange={e => setFormData({...formData, schedule: e.target.value})} placeholder={formData.timer_type === 'interval' ? '3600' : '0 */6 * * *'} /> : <div className="text-sm font-mono">{timer?.schedule}</div>}</div>
             <div className="space-y-2"><Label>Active</Label>{isEditing ? <div className="flex items-center gap-2"><Checkbox id="active" checked={formData.is_active} onCheckedChange={c => setFormData({...formData, is_active: c === true})} /><Label htmlFor="active">Enabled</Label></div> : <div className="text-sm">{timer?.is_active ? 'Yes' : 'No'}</div>}</div>
           </div>
           <div className="space-y-4">
             <h3 className="text-sm font-medium text-muted-foreground">Execution</h3>
-            {!isCreateMode && (
-              <>
-                <div className="flex justify-between"><span className="text-sm text-muted-foreground">Next Run</span><span className="text-sm">{timer?.next_run ? formatDateTime(timer.next_run) : '—'}</span></div>
-                <div className="flex justify-between"><span className="text-sm text-muted-foreground">Last Run</span><span className="text-sm">{timer?.last_run ? formatDateTime(timer.last_run) : '—'}</span></div>
-                <div className="flex justify-between"><span className="text-sm text-muted-foreground">Last Status</span><Badge variant={timer?.last_run_status === 'success' ? 'default' : 'destructive'}>{timer?.last_run_status || '—'}</Badge></div>
-              </>
-            )}
-            <div className="space-y-2"><Label>Target Type</Label>{isEditing ? <Input value={formData.target_type} onChange={e => setFormData({...formData, target_type: e.target.value})} placeholder="e.g., function, pipeline" /> : <div className="text-sm">{timer?.target_type}</div>}</div>
-            <div className="space-y-2"><Label>Target Action</Label>{isEditing ? <Input value={formData.target_action} onChange={e => setFormData({...formData, target_action: e.target.value})} placeholder="e.g., execute" /> : <div className="text-sm">{timer?.target_action}</div>}</div>
+            <div className="space-y-2"><Label>Pipeline ID</Label>{isEditing ? <Input value={formData.pipeline_id} onChange={e => setFormData({...formData, pipeline_id: e.target.value})} placeholder="Pipeline to invoke" /> : <div className="text-sm font-mono">{timer?.pipeline_id || '—'}</div>}</div>
           </div>
         </div>
         <div className="mt-6 space-y-2"><Label>Description</Label>{isEditing ? <Textarea value={formData.description} onChange={e => setFormData({...formData, description: e.target.value})} rows={3} /> : <div className="text-sm">{timer?.description || '—'}</div>}</div>
-        <div className="mt-6 space-y-2"><Label>Target Config (JSON)</Label>{isEditing ? <Textarea value={formData.target_config} onChange={e => setFormData({...formData, target_config: e.target.value})} rows={6} className="font-mono text-sm" /> : <pre className="text-sm bg-muted p-3 rounded">{JSON.stringify(timer?.target_config || {}, null, 2)}</pre>}</div>
+        <div className="mt-6 space-y-2"><Label>Config (JSON)</Label>{isEditing ? <Textarea value={formData.config} onChange={e => setFormData({...formData, config: e.target.value})} rows={6} className="font-mono text-sm" /> : <pre className="text-sm bg-muted p-3 rounded">{JSON.stringify(timer?.config || {}, null, 2)}</pre>}</div>
+        <div className="mt-6 space-y-2"><Label>Metadata (JSON)</Label>{isEditing ? <Textarea value={formData.metadata} onChange={e => setFormData({...formData, metadata: e.target.value})} rows={4} className="font-mono text-sm" /> : <pre className="text-sm bg-muted p-3 rounded">{JSON.stringify(timer?.metadata || {}, null, 2)}</pre>}</div>
       </CardContent></Card>
     </div>
   )
 }
+// CIL[END chunk_id="timerdetailpage_timerdetailpage_1783664706"]

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

@@ -1,18 +1,21 @@
-/**
- * @module src/pages/admin/TimersPage
- * @audience installer
- * @layer frontend-page
- * @stability stable
- *
- * Admin list page for scheduled timers. Fetches all timers via
- * `/api/timers?action=list`, applies client-side search, type filter
- * (`schedule` | `delay` | `recurring` | `cron`), and sort. Renders
- * inside `AdminListPage` with stat cards and a sortable table. Row
- * clicks navigate to `/spine-framework/admin/configs/timers/:id`.
- *
- * @seeAlso src/pages/admin/TimerDetailPage.tsx
- */
 
+
+
+// CIL[BEGIN chunk_id="timerspage_moduleheader_1783664706" type="module_header" identity="module_header" parent="none"]
+// CIL[DOC-MACRO purpose="Import dependencies for TimersPage component"]
+// CIL[DOC-RESPONSIBILITY responsibility="Provide all external dependencies and UI components"]
+// CIL[DOC-CONTEXT module="TimersPage" layer="frontend-page" related_files="[\".framework/src/components/layout/Sidebar.tsx\",\".framework/src/components/ui/dialog.tsx\",\"custom/apps/cortex/pages/operations/OperationsDashboard.tsx\",\"custom/apps/portal/pages/ContentPage.tsx\",\".framework/src/pages/admin/TypeDetailPage.tsx\",\"\\\"]"]
+// CIL[DOC-CONTRACT inputs="none" outputs="React components and utilities" errors="none" side_effects="none"]
+// CIL[DOC-MICRO logic_summary="Imports React hooks, navigation, API utilities, icons, and UI components" notable_decisions="[]"]
+// CIL[DOC-CONFIDENCE pass="second" score="0.95" flags="none"]
+// CIL[DOC-STABILITY stability="stable"]
+// CIL[DOC-AUDIENCE audience="developer"]
+// CIL[DOC-VECTOR type="context" content="Layer: frontend-page. Direct callers: 0. Direct calls: 0. Related files: .framework/src/components/layout/Sidebar.tsx, .framework/src/components/ui/dialog.tsx, custom/apps/cortex/pages/operations/OperationsDashboard.tsx, custom/apps/portal/pages/ContentPage.tsx, .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 React, { useState } from 'react'
 import { useNavigate } from 'react-router-dom'
 import { useApi } from '../../hooks/useApi'
@@ -24,7 +27,21 @@ import { Badge } from '../../components/ui/badge'
 import { formatDateTime } from '../../lib/utils'
 import { AdminListPage } from '../../components/admin/AdminListPage'
 import { SortableTableHeader } from '../../components/admin/SortableTableHeader'
-
+// CIL[END chunk_id="timerspage_moduleheader_1783664706"]
+// CIL[BEGIN chunk_id="timerspage_timer_1783664706" type="interface" identity="Timer" parent="none"]
+// CIL[DOC-MACRO purpose="Define the Timer data structure for timer management"]
+// CIL[DOC-RESPONSIBILITY responsibility="Provide type definition for scheduled/recurring timers"]
+// CIL[DOC-CONTEXT module="TimersPage" layer="frontend-page" related_files="[\".framework/src/pages/admin/IntegrationsPage.tsx\",\".framework/functions/_shared/principal.ts\",\"custom/apps/cortex/pages/operations/OperationsDashboard.tsx\",\".framework/functions/_shared/schema-utils.ts\",\".framework/src/pages/admin/TypeDetailPage.tsx\",\"\\\"]"]
+// CIL[DOC-CONTRACT inputs="none" outputs="Timer interface" errors="none" side_effects="none"]
+// CIL[DOC-MICRO logic_summary="Defines comprehensive timer structure with execution statistics" notable_decisions="[]"]
+// CIL[DOC-CONFIDENCE pass="second" score="0.95" flags="none"]
+// CIL[DOC-STABILITY stability="stable"]
+// CIL[DOC-VECTOR type="context" content="Layer: frontend-page. Direct callers: 0. Direct calls: 0. Related files: .framework/src/pages/admin/IntegrationsPage.tsx, .framework/functions/_shared/principal.ts, custom/apps/cortex/pages/operations/OperationsDashboard.tsx, .framework/functions/_shared/schema-utils.ts, .framework/src/pages/admin/TypeDetailPage.tsx, \."]
+// CIL[DOC-VECTOR type="blast_radius" content="Direct callers: 0. Total affected: 0."]
+// CIL[DOC-VECTOR type="configuration" content="No configuration dependencies."]
+// CIL[DOC-VECTOR type="constraint" content="No test paths identified."]
+// CIL[DOC-VECTOR type="implementation_pattern" content="" status="pending_human_input"]
+// CIL[DOC-VECTOR type="user_journey" content="" status="pending_human_input"]
 interface Timer {
   id: string
   name: string
@@ -50,7 +67,21 @@ interface Timer {
   success_count: number
   failure_count: number
 }
-
+// CIL[END chunk_id="timerspage_timer_1783664706"]
+// CIL[BEGIN chunk_id="timerspage_timerspage_1783664706" type="function" identity="TimersPage" parent="none"]
+// CIL[DOC-MACRO purpose="Admin list page for managing scheduled and recurring timers"]
+// CIL[DOC-RESPONSIBILITY responsibility="Fetch, filter, sort, and display timers with navigation"]
+// CIL[DOC-CONTEXT module="TimersPage" layer="frontend-page" related_files="[\"custom/apps/portal/pages/ContentPage.tsx\",\".framework/src/pages/admin/TypeDetailPage.tsx\",\"custom/apps/cortex/pages/operations/OperationsDashboard.tsx\",\".framework/src/pages/admin/RolesPage.tsx\",\"\\\"]"]
+// CIL[DOC-CONTRACT inputs="none" outputs="React component with timer list" errors="API failures" side_effects="API calls, navigation"]
+// CIL[DOC-MICRO logic_summary="Client-side filtering, sorting, and stats calculation for timers" notable_decisions="[]"]
+// CIL[DOC-CONFIDENCE pass="second" score="0.95" flags="none"]
+// CIL[DOC-STABILITY stability="stable"]
+// CIL[DOC-VECTOR type="context" content="Layer: frontend-page. Direct callers: 0. Direct calls: 0. Related files: custom/apps/portal/pages/ContentPage.tsx, .framework/src/pages/admin/TypeDetailPage.tsx, custom/apps/cortex/pages/operations/OperationsDashboard.tsx, .framework/src/pages/admin/RolesPage.tsx, \."]
+// CIL[DOC-VECTOR type="blast_radius" content="Direct callers: 0. Total affected: 0."]
+// CIL[DOC-VECTOR type="configuration" content="No configuration dependencies."]
+// CIL[DOC-VECTOR type="constraint" content="No test paths identified."]
+// CIL[DOC-VECTOR type="implementation_pattern" content="" status="pending_human_input"]
+// CIL[DOC-VECTOR type="user_journey" content="" status="pending_human_input"]
 export function TimersPage() {
   const navigate = useNavigate()
   const [searchTerm, setSearchTerm] = useState('')
@@ -59,7 +90,6 @@ export function TimersPage() {
   const [sortKey, setSortKey] = useState('name')
   const [sortDirection, setSortDirection] = useState<'asc' | 'desc'>('asc')
 
-  // Fetch timers from API
   const { data: timers, loading, error, refetch } = useApi<Timer[]>(
     async ({ signal }: { signal?: AbortSignal }) => {
       try {
@@ -75,7 +105,6 @@ export function TimersPage() {
         const result = await response.json()
         console.log('Raw API result:', result)
         
-        // Handle both nested and direct responses
         const timers = result.data || result
         console.log('Timers after processing:', timers)
         
@@ -151,7 +180,6 @@ export function TimersPage() {
     return Math.round((timer.success_count / timer.execution_count) * 100)
   }
 
-  // Sorting logic
   const sortedTimers = [...filteredTimers].sort((a, b) => {
     const aValue = a[sortKey as keyof Timer]
     const bValue = b[sortKey as keyof Timer]
@@ -191,7 +219,6 @@ export function TimersPage() {
     navigate(`/spine-framework/admin/configs/timers/${timer.id}`)
   }
 
-  // Stats cards
   const statsCards = [
     {
       title: 'Total Timers',
@@ -374,3 +401,4 @@ export function TimersPage() {
     </AdminListPage>
   )
 }
+// CIL[END chunk_id="timerspage_timerspage_1783664706"]