spine-framework 0.3.145 → 0.4.1

package/.framework/src/hooks/useApps.ts

@@ -1,25 +1,36 @@
+// CIL[BEGIN stable_id="~/.framework/src/hooks/useApps.ts:module_header:module_header" type="module_header" identity="module_header" parent="~/.framework/src/hooks/useApps.ts"]
+// CIL[DOC-MACRO purpose="Module setup and imports for useApps.ts"]
+// CIL[DOC-RESPONSIBILITY responsibility="Establish the public surface and dependencies of useApps.ts"]
+// CIL[DOC-CONTEXT module=".framework/src/hooks/useApps.ts" layer="hooks" related_files=".framework/src/contexts/AuthContext.tsx,.framework/src/lib/api.ts"]
+// CIL[DOC-CONTRACT inputs="none" outputs="none" errors="none" side_effects="none"]
+// CIL[DOC-MICRO logic_summary="Imports required modules for useApps.ts" notable_decisions="[]"]
+// CIL[DOC-CONFIDENCE pass="second" score="0.90" flags="none"]
+// CIL[DOC-AUDIENCE audience="frontend"]
+// CIL[DOC-STABILITY stability="stable"]
+
 
 
 
-// CIL[BEGIN chunk_id="useapps_module_header_1783719596" type="module_header" identity="module_header" parent="none"]
-// CIL[DOC-MACRO purpose="Define types and interfaces for app management"]
-// CIL[DOC-RESPONSIBILITY responsibility="Type definitions for AppRecord and UseAppsResult"]
-// CIL[DOC-CONTEXT module="useApps" layer="frontend-hook" related_files="[\"custom/apps/portal/pages/ContentPage.tsx\",\"custom/apps/cortex/pages/operations/OperationsDashboard.tsx\",\".framework/migrations/015_simplify_apps_table.sql\",\".framework/functions/_shared/principal.ts\",\"\\\"]"]
-// CIL[DOC-CONTRACT inputs="none" outputs="Type definitions" errors="none" side_effects="Type declarations"]
-// CIL[DOC-MICRO logic_summary="Exports AppRecord interface with app metadata and UseAppsResult interface" 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-hook. 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/functions/_shared/principal.ts, \."]
-// CIL[DOC-VECTOR type="blast_radius" content="Direct callers: 0. Total affected: 0."]
-// CIL[DOC-VECTOR type="configuration" content="No configuration dependencies."]
-// CIL[DOC-VECTOR type="constraint" content="No test paths identified."]
-// CIL[DOC-VECTOR type="implementation_pattern" content="" status="pending_human_input"]
-// CIL[DOC-VECTOR type="user_journey" content="" status="pending_human_input"]
 import { useState, useEffect } from 'react'
 import { apiFetch } from '../lib/api'
 import { useAuth } from '../contexts/AuthContext'
+// CIL[DOC-VECTOR type="context" content="purpose='Module setup and imports for useApps.ts'; No verified external callers; imports: .framework/src/lib/api.ts,.framework/src/contexts/AuthContext.tsx"]
+// CIL[DOC-VECTOR type="blast_radius" content="No direct caller data from CIL graph; local impact only"]
+// CIL[DOC-VECTOR type="configuration" content="No environment or build configuration dependencies identified"]
+// CIL[DOC-VECTOR type="constraint" content="Standard runtime; no special invariants documented"]
+// CIL[DOC-VECTOR type="implementation_pattern" content="" status="pending_human_input"]
+// CIL[DOC-VECTOR type="user_journey" content="" status="pending_human_input"]
+// CIL[END stable_id="~/.framework/src/hooks/useApps.ts:module_header:module_header"]
+
 
+// CIL[BEGIN stable_id="~/.framework/src/hooks/useApps.ts:AppRecord:interface" type="interface" identity="AppRecord" parent="~/.framework/src/hooks/useApps.ts"]
+// CIL[DOC-MACRO purpose="Define the AppRecord shape"]
+// CIL[DOC-RESPONSIBILITY responsibility="Provide the AppRecord type contract"]
+// CIL[DOC-CONTEXT module=".framework/src/hooks/useApps.ts" layer="hooks" related_files=".framework/src/contexts/AuthContext.tsx,.framework/src/hooks/useApps.ts,.framework/src/lib/api.ts"]
+// CIL[DOC-CONTRACT inputs="none" outputs="AppRecord interface definition" errors="none" side_effects="none"]
+// CIL[DOC-MICRO logic_summary="Declares the fields of the AppRecord interface" notable_decisions="[]"]
+// CIL[DOC-CONFIDENCE pass="second" score="0.90" flags="none"]
+// CIL[DOC-STABILITY stability="stable"]
 export interface AppRecord {
   id: string
   slug: string
@@ -41,28 +52,45 @@ export interface AppRecord {
   preview_domain?: string | null
   prod_domain?: string | null
 }
+// CIL[DOC-VECTOR type="context" content="purpose='Define the AppRecord shape'; No verified external callers; imports: .framework/src/lib/api.ts,.framework/src/contexts/AuthContext.tsx"]
+// CIL[DOC-VECTOR type="blast_radius" content="No direct caller data from CIL graph; local impact only"]
+// CIL[DOC-VECTOR type="configuration" content="No environment or build configuration dependencies identified"]
+// CIL[DOC-VECTOR type="constraint" content="Standard runtime; no special invariants documented"]
+// CIL[DOC-VECTOR type="implementation_pattern" content="" status="pending_human_input"]
+// CIL[DOC-VECTOR type="user_journey" content="" status="pending_human_input"]
+// CIL[END stable_id="~/.framework/src/hooks/useApps.ts:AppRecord:interface"]
+
 
+// CIL[BEGIN stable_id="~/.framework/src/hooks/useApps.ts:UseAppsResult:interface" type="interface" identity="UseAppsResult" parent="~/.framework/src/hooks/useApps.ts"]
+// CIL[DOC-MACRO purpose="Define the UseAppsResult shape"]
+// CIL[DOC-RESPONSIBILITY responsibility="Provide the UseAppsResult type contract"]
+// CIL[DOC-CONTEXT module=".framework/src/hooks/useApps.ts" layer="hooks" related_files=".framework/src/contexts/AuthContext.tsx,.framework/src/hooks/useApps.ts,.framework/src/lib/api.ts"]
+// CIL[DOC-CONTRACT inputs="none" outputs="UseAppsResult interface definition" errors="none" side_effects="none"]
+// CIL[DOC-MICRO logic_summary="Declares the fields of the UseAppsResult interface" notable_decisions="[]"]
+// CIL[DOC-CONFIDENCE pass="second" score="0.90" flags="none"]
+// CIL[DOC-STABILITY stability="stable"]
 interface UseAppsResult {
   apps: AppRecord[]
   loading: boolean
   error: string | null
   refetch: () => void
 }
-// CIL[END chunk_id="useapps_module_header_1783719596"]
-// CIL[BEGIN chunk_id="useapps_useapps_1783719596" type="function" identity="useApps" parent="none"]
-// CIL[DOC-MACRO purpose="Fetch and filter apps based on user roles and domain"]
-// CIL[DOC-RESPONSIBILITY responsibility="App fetching, role-based filtering, domain matching"]
-// CIL[DOC-CONTEXT module="useApps" layer="frontend-hook" related_files="[\"custom/apps/portal/pages/ContentPage.tsx\",\".framework/src/pages/admin/RolesPage.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="UseAppsResult with apps, loading, error, refetch" errors="Network errors, auth errors" side_effects="React state updates, API calls"]
-// CIL[DOC-MICRO logic_summary="Fetches apps, filters by active status, domain, and user roles with system_admin override" 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-hook. Direct callers: 1. Direct calls: 0. Related files: custom/apps/portal/pages/ContentPage.tsx, .framework/src/pages/admin/RolesPage.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: 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="context" content="purpose='Define the UseAppsResult shape'; No verified external callers; imports: .framework/src/lib/api.ts,.framework/src/contexts/AuthContext.tsx"]
+// CIL[DOC-VECTOR type="blast_radius" content="No direct caller data from CIL graph; local impact only"]
+// CIL[DOC-VECTOR type="configuration" content="No environment or build configuration dependencies identified"]
+// CIL[DOC-VECTOR type="constraint" content="Standard runtime; no special invariants documented"]
 // CIL[DOC-VECTOR type="implementation_pattern" content="" status="pending_human_input"]
 // CIL[DOC-VECTOR type="user_journey" content="" status="pending_human_input"]
+// CIL[END stable_id="~/.framework/src/hooks/useApps.ts:UseAppsResult:interface"]
+
+// CIL[BEGIN stable_id="~/.framework/src/hooks/useApps.ts:useApps:hook" type="hook" identity="useApps" parent="~/.framework/src/hooks/useApps.ts"]
+// CIL[DOC-MACRO purpose="Implement useApps"]
+// CIL[DOC-RESPONSIBILITY responsibility="Execute the core logic for useApps"]
+// CIL[DOC-CONTEXT module=".framework/src/hooks/useApps.ts" layer="hooks" related_files=".framework/src/contexts/AuthContext.tsx,.framework/src/hooks/useApps.ts,.framework/src/lib/api.ts"]
+// CIL[DOC-CONTRACT inputs="none" outputs="UseAppsResult" errors="propagates dependency errors" side_effects="updates React state"]
+// CIL[DOC-MICRO logic_summary="Processes inputs, performs work, and returns output for useApps" notable_decisions="[]"]
+// CIL[DOC-CONFIDENCE pass="second" score="0.90" flags="none"]
+// CIL[DOC-STABILITY stability="stable"]
 export function useApps(): UseAppsResult {
   const { user } = useAuth()
   const [apps, setApps] = useState<AppRecord[]>([])
@@ -134,21 +162,22 @@ export function useApps(): UseAppsResult {
 
   return { apps, loading, error, refetch: fetchApps }
 }
-// CIL[END chunk_id="useapps_useapps_1783719596"]
-// CIL[BEGIN chunk_id="useapps_useroutableapps_1783719596" type="function" identity="useRoutableApps" parent="none"]
-// CIL[DOC-MACRO purpose="Filter apps to only those with routing capabilities"]
-// CIL[DOC-RESPONSIBILITY responsibility="Route filtering for navigation-ready apps"]
-// CIL[DOC-CONTEXT module="useApps" layer="frontend-hook" related_files="[\"custom/apps/cortex/functions/custom_cil-embeddings.ts\",\"custom/apps/portal/pages/ContentPage.tsx\",\"custom/apps/cortex/pages/operations/OperationsDashboard.tsx\",\".framework/migrations/015_simplify_apps_table.sql\",\"\\\"]"]
-// CIL[DOC-CONTRACT inputs="none" outputs="UseAppsResult filtered to routable apps" errors="none" side_effects="React state updates via useApps hook"]
-// CIL[DOC-MICRO logic_summary="Wraps useApps and filters results to apps with route_prefix and not 'none' renderer" 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-hook. Direct callers: 0. Direct calls: 0. Related files: custom/apps/cortex/functions/custom_cil-embeddings.ts, custom/apps/portal/pages/ContentPage.tsx, custom/apps/cortex/pages/operations/OperationsDashboard.tsx, .framework/migrations/015_simplify_apps_table.sql, \."]
-// 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="context" content="purpose='Implement useApps'; No verified external callers; imports: .framework/src/lib/api.ts,.framework/src/contexts/AuthContext.tsx"]
+// CIL[DOC-VECTOR type="blast_radius" content="No direct caller data from CIL graph; local impact only"]
+// CIL[DOC-VECTOR type="configuration" content="No environment or build configuration dependencies identified"]
+// CIL[DOC-VECTOR type="constraint" content="Standard runtime; no special invariants documented"]
 // CIL[DOC-VECTOR type="implementation_pattern" content="" status="pending_human_input"]
 // CIL[DOC-VECTOR type="user_journey" content="" status="pending_human_input"]
+// CIL[END stable_id="~/.framework/src/hooks/useApps.ts:useApps:hook"]
+
+// CIL[BEGIN stable_id="~/.framework/src/hooks/useApps.ts:useRoutableApps:hook" type="hook" identity="useRoutableApps" parent="~/.framework/src/hooks/useApps.ts"]
+// CIL[DOC-MACRO purpose="Implement useRoutableApps"]
+// CIL[DOC-RESPONSIBILITY responsibility="Execute the core logic for useRoutableApps"]
+// CIL[DOC-CONTEXT module=".framework/src/hooks/useApps.ts" layer="hooks" related_files=".framework/src/contexts/AuthContext.tsx,.framework/src/hooks/useApps.ts,.framework/src/lib/api.ts"]
+// CIL[DOC-CONTRACT inputs="none" outputs="filtered UseAppsResult" errors="propagates dependency errors" side_effects="none"]
+// CIL[DOC-MICRO logic_summary="Processes inputs, performs work, and returns output for useRoutableApps" notable_decisions="[]"]
+// CIL[DOC-CONFIDENCE pass="second" score="0.90" flags="none"]
+// CIL[DOC-STABILITY stability="stable"]
 export function useRoutableApps() {
   const result = useApps()
   return {
@@ -156,4 +185,10 @@ export function useRoutableApps() {
     apps: result.apps.filter(app => app.route_prefix != null && app.renderer !== 'none')
   }
 }
-// CIL[END chunk_id="useapps_useroutableapps_1783719596"]
+// CIL[DOC-VECTOR type="context" content="purpose='Implement useRoutableApps'; No verified external callers; imports: .framework/src/lib/api.ts,.framework/src/contexts/AuthContext.tsx"]
+// CIL[DOC-VECTOR type="blast_radius" content="No direct caller data from CIL graph; local impact only"]
+// CIL[DOC-VECTOR type="configuration" content="No environment or build configuration dependencies identified"]
+// CIL[DOC-VECTOR type="constraint" content="Standard runtime; no special invariants documented"]
+// CIL[DOC-VECTOR type="implementation_pattern" content="" status="pending_human_input"]
+// CIL[DOC-VECTOR type="user_journey" content="" status="pending_human_input"]
+// CIL[END stable_id="~/.framework/src/hooks/useApps.ts:useRoutableApps:hook"]

package/.framework/src/hooks/useEntityList.ts

@@ -1,24 +1,36 @@
+// CIL[BEGIN stable_id="~/.framework/src/hooks/useEntityList.ts:module_header:module_header" type="module_header" identity="module_header" parent="~/.framework/src/hooks/useEntityList.ts"]
+// CIL[DOC-AUDIENCE audience="internal"]
+// CIL[DOC-MACRO purpose="Provide React and API imports for the useEntityList hook"]
+// CIL[DOC-RESPONSIBILITY responsibility="Import dependencies required by useEntityList"]
+// CIL[DOC-CONTEXT module=".framework/src/hooks/useEntityList" layer="ui" related_files=".framework/src/hooks/useApi.ts,.framework/src/lib/api.ts"]
+// CIL[DOC-CONTRACT inputs="none" outputs="module-level imports" errors="none" side_effects="none"]
+// CIL[DOC-MICRO logic_summary="Imports useState/useEffect/useCallback from React, useApi helper, and apiFetch utility" notable_decisions=""]
+// CIL[DOC-CONFIDENCE pass="second" score="0.90" flags="none"]
+// CIL[DOC-STABILITY stable]
+
 
 
-// CIL[BEGIN chunk_id="useentitylist_module_header_1783719596" type="module_header" identity="module_header" parent="none"]
-// CIL[DOC-MACRO purpose="Define entity list hook types and interfaces"]
-// CIL[DOC-RESPONSIBILITY responsibility="Type definitions for entity list management"]
-// CIL[DOC-CONTEXT module="useEntityList" layer="frontend-hook" related_files="[\"custom/apps/portal/pages/ContentPage.tsx\",\"custom/apps/cortex/pages/operations/OperationsDashboard.tsx\",\".framework/src/pages/admin/IntegrationsPage.tsx\",\".framework/functions/_shared/principal.ts\",\".framework/functions/_shared/schema-utils.ts\",\"\\\"]"]
-// CIL[DOC-CONTRACT inputs="none" outputs="MinimalEntityListConfig and UseEntityListReturn interfaces" errors="none" side_effects="Type declarations"]
-// CIL[DOC-MICRO logic_summary="Exports interfaces for list configuration, return values, and pagination controls" 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-hook. Direct callers: 0. Direct calls: 0. Related files: custom/apps/portal/pages/ContentPage.tsx, custom/apps/cortex/pages/operations/OperationsDashboard.tsx, .framework/src/pages/admin/IntegrationsPage.tsx, .framework/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 { useState, useEffect, useCallback } from 'react'
 import { useApi } from './useApi'
 import { apiFetch } from '../lib/api'
+// CIL[DOC-VECTOR type="context" content="purpose='Provide React and API imports for the useEntityList hook'; No verified external callers; imports: .framework/src/hooks/useApi.ts,.framework/src/lib/api.ts"]
+// CIL[DOC-VECTOR type="blast_radius" content="No direct caller data from CIL graph; local impact only"]
+// CIL[DOC-VECTOR type="configuration" content="No environment or build configuration dependencies identified"]
+// CIL[DOC-VECTOR type="constraint" content="Standard runtime; no special invariants documented"]
+// CIL[DOC-VECTOR type="implementation_pattern" content="" status="pending_human_input"]
+// CIL[DOC-VECTOR type="user_journey" content="" status="pending_human_input"]
+// CIL[END stable_id="~/.framework/src/hooks/useEntityList.ts:module_header:module_header"]
+
 
+// CIL[BEGIN stable_id="~/.framework/src/hooks/useEntityList.ts:MinimalEntityListConfig:interface" type="interface" identity="MinimalEntityListConfig" parent="~/.framework/src/hooks/useEntityList.ts"]
+// CIL[DOC-AUDIENCE audience="internal"]
+// CIL[DOC-MACRO purpose="Define the minimal configuration shape for useEntityList"]
+// CIL[DOC-RESPONSIBILITY responsibility="Describe required and optional list configuration fields"]
+// CIL[DOC-CONTEXT module=".framework/src/hooks/useEntityList" layer="ui" related_files=".framework/src/hooks/useApi.ts,.framework/src/hooks/useEntityList.ts,.framework/src/lib/api.ts"]
+// CIL[DOC-CONTRACT inputs="none" outputs="MinimalEntityListConfig interface" errors="none" side_effects="none"]
+// CIL[DOC-MICRO logic_summary="Declares entity, optional typeSlug, API endpoint/listAction, and default sort settings" notable_decisions="list.defaultSort is required"]
+// CIL[DOC-CONFIDENCE pass="second" score="0.90" flags="none"]
+// CIL[DOC-STABILITY stable]
 interface MinimalEntityListConfig {
   entity: string
   typeSlug?: string
@@ -30,7 +42,24 @@ interface MinimalEntityListConfig {
     defaultSort: { field: string; direction: 'asc' | 'desc' }
   }
 }
+// CIL[DOC-VECTOR type="context" content="purpose='Define the minimal configuration shape for useEntityList'; No verified external callers; imports: .framework/src/hooks/useApi.ts,.framework/src/lib/api.ts"]
+// CIL[DOC-VECTOR type="blast_radius" content="No direct caller data from CIL graph; local impact only"]
+// CIL[DOC-VECTOR type="configuration" content="No environment or build configuration dependencies identified"]
+// CIL[DOC-VECTOR type="constraint" content="Standard runtime; no special invariants documented"]
+// CIL[DOC-VECTOR type="implementation_pattern" content="" status="pending_human_input"]
+// CIL[DOC-VECTOR type="user_journey" content="" status="pending_human_input"]
+// CIL[END stable_id="~/.framework/src/hooks/useEntityList.ts:MinimalEntityListConfig:interface"]
+
 
+// CIL[BEGIN stable_id="~/.framework/src/hooks/useEntityList.ts:UseEntityListReturn:interface" type="interface" identity="UseEntityListReturn" parent="~/.framework/src/hooks/useEntityList.ts"]
+// CIL[DOC-AUDIENCE audience="internal"]
+// CIL[DOC-MACRO purpose="Define the return shape for useEntityList"]
+// CIL[DOC-RESPONSIBILITY responsibility="Expose state and controls returned by the useEntityList hook"]
+// CIL[DOC-CONTEXT module=".framework/src/hooks/useEntityList" layer="ui" related_files=".framework/src/hooks/useApi.ts,.framework/src/hooks/useEntityList.ts,.framework/src/lib/api.ts"]
+// CIL[DOC-CONTRACT inputs="none" outputs="UseEntityListReturn interface" errors="none" side_effects="none"]
+// CIL[DOC-MICRO logic_summary="Declares data, loading, error, refetch, filters, sort, and pagination state accessors" notable_decisions=""]
+// CIL[DOC-CONFIDENCE pass="second" score="0.90" flags="none"]
+// CIL[DOC-STABILITY stable]
 interface UseEntityListReturn {
   data: any[]
   loading: boolean
@@ -48,21 +77,23 @@ interface UseEntityListReturn {
     total: number
   }
 }
-// CIL[END chunk_id="useentitylist_module_header_1783719596"]
-// CIL[BEGIN chunk_id="useentitylist_useentitylist_1783719596" type="function" identity="useEntityList" parent="none"]
-// CIL[DOC-MACRO purpose="Fetch and manage paginated, filtered, sorted entity lists"]
-// CIL[DOC-RESPONSIBILITY responsibility="List fetching, pagination, filtering, sorting, state management"]
-// CIL[DOC-CONTEXT module="useEntityList" layer="frontend-hook" related_files="[\"custom/apps/portal/pages/ContentPage.tsx\",\"custom/apps/cortex/pages/operations/OperationsDashboard.tsx\",\".framework/src/pages/admin/TypeDetailPage.tsx\",\".framework/src/components/ui/dialog.tsx\",\".framework/src/pages/admin/RolesPage.tsx\",\"\\\"]"]
-// CIL[DOC-CONTRACT inputs="none" outputs="UseEntityListReturn with data, controls, pagination" errors="Network errors, API errors" side_effects="React state updates, API calls via apiFetch"]
-// CIL[DOC-MICRO logic_summary="Builds query params from config, filters, sort, pagination; fetches via useApi; manages 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: frontend-hook. Direct callers: 3. Direct calls: 0. Related files: custom/apps/portal/pages/ContentPage.tsx, custom/apps/cortex/pages/operations/OperationsDashboard.tsx, .framework/src/pages/admin/TypeDetailPage.tsx, .framework/src/components/ui/dialog.tsx, .framework/src/pages/admin/RolesPage.tsx, \."]
-// CIL[DOC-VECTOR type="blast_radius" content="Direct callers: 3. Total affected: 3."]
-// CIL[DOC-VECTOR type="configuration" content="No configuration dependencies."]
-// CIL[DOC-VECTOR type="constraint" content="No test paths identified."]
+// CIL[DOC-VECTOR type="context" content="purpose='Define the return shape for useEntityList'; No verified external callers; imports: .framework/src/hooks/useApi.ts,.framework/src/lib/api.ts"]
+// CIL[DOC-VECTOR type="blast_radius" content="No direct caller data from CIL graph; local impact only"]
+// CIL[DOC-VECTOR type="configuration" content="No environment or build configuration dependencies identified"]
+// CIL[DOC-VECTOR type="constraint" content="Standard runtime; no special invariants documented"]
 // CIL[DOC-VECTOR type="implementation_pattern" content="" status="pending_human_input"]
 // CIL[DOC-VECTOR type="user_journey" content="" status="pending_human_input"]
+// CIL[END stable_id="~/.framework/src/hooks/useEntityList.ts:UseEntityListReturn:interface"]
+
+// CIL[BEGIN stable_id="~/.framework/src/hooks/useEntityList.ts:useEntityList:hook" type="hook" identity="useEntityList" parent="~/.framework/src/hooks/useEntityList.ts"]
+// CIL[DOC-AUDIENCE audience="internal"]
+// CIL[DOC-MACRO purpose="Fetch and manage a paginated, sortable, filterable list of entities"]
+// CIL[DOC-RESPONSIBILITY responsibility="Manage list state, build API query parameters, and expose list controls"]
+// CIL[DOC-CONTEXT module=".framework/src/hooks/useEntityList" layer="ui" related_files=".framework/src/hooks/useApi.ts,.framework/src/hooks/useEntityList.ts,.framework/src/lib/api.ts"]
+// CIL[DOC-CONTRACT inputs="entity: string, config: MinimalEntityListConfig | null" outputs="UseEntityListReturn" errors="Throws on non-ok API response" side_effects="HTTP GET request, React state updates"]
+// CIL[DOC-MICRO logic_summary="Computes URL parameters from filters, sort, and pagination; fetches via apiFetch; resets page on filter changes" notable_decisions="Defaults sort to created_at descending; resets page to 1 when filters change"]
+// CIL[DOC-CONFIDENCE pass="second" score="0.90" flags="none"]
+// CIL[DOC-STABILITY stable]
 export function useEntityList(
   entity: string,
   config: MinimalEntityListConfig | null
@@ -141,4 +172,10 @@ export function useEntityList(
     }
   }
 }
-// CIL[END chunk_id="useentitylist_useentitylist_1783719596"]
+// CIL[DOC-VECTOR type="context" content="purpose='Fetch and manage a paginated, sortable, filterable list of entities'; No verified external callers; imports: .framework/src/hooks/useApi.ts,.framework/src/lib/api.ts"]
+// CIL[DOC-VECTOR type="blast_radius" content="No direct caller data from CIL graph; local impact only"]
+// CIL[DOC-VECTOR type="configuration" content="No environment or build configuration dependencies identified"]
+// CIL[DOC-VECTOR type="constraint" content="Standard runtime; no special invariants documented"]
+// CIL[DOC-VECTOR type="implementation_pattern" content="" status="pending_human_input"]
+// CIL[DOC-VECTOR type="user_journey" content="" status="pending_human_input"]
+// CIL[END stable_id="~/.framework/src/hooks/useEntityList.ts:useEntityList:hook"]

package/.framework/src/hooks/useEntityRecord.ts

@@ -1,29 +1,52 @@
-
-
-// CIL[BEGIN chunk_id="useentityrecord_module_header_1783719596" type="module_header" identity="module_header" parent="none"]
-// CIL[DOC-MACRO purpose="Define entity record hook types and interfaces"]
-// CIL[DOC-RESPONSIBILITY responsibility="Type definitions for entity record management"]
-// CIL[DOC-CONTEXT module="useEntityRecord" layer="frontend-hook" related_files="[\"custom/apps/portal/pages/ContentPage.tsx\",\"custom/apps/cortex/pages/operations/OperationsDashboard.tsx\",\".framework/src/pages/admin/IntegrationsPage.tsx\",\".framework/functions/_shared/principal.ts\",\".framework/src/pages/admin/TypeDetailPage.tsx\",\"\\\"]"]
-// CIL[DOC-CONTRACT inputs="none" outputs="FieldPermissions, MinimalEntityConfig, UseEntityRecordReturn interfaces" errors="none" side_effects="Type declarations"]
-// CIL[DOC-MICRO logic_summary="Exports interfaces for field permissions, entity config, and record management" notable_decisions="[]"]
-// CIL[DOC-CONFIDENCE pass="second" score="0.95" flags="none"]
+// CIL[BEGIN stable_id="~/.framework/src/hooks/useEntityRecord.ts:module_header:module_header" type="module_header" identity="module_header" parent="~/.framework/src/hooks/useEntityRecord.ts"]
+// CIL[DOC-MACRO purpose="React hook for fetching and managing a single entity record"]
+// CIL[DOC-RESPONSIBILITY responsibility="Declares module imports and exposes the useEntityRecord hook for record CRUD and permission handling"]
+// CIL[DOC-CONTEXT module="useEntityRecord" layer="hooks" related_files=".framework/src/contexts/AuthContext.tsx,.framework/src/hooks/useApi.ts,.framework/src/lib/api.ts"]
+// CIL[DOC-CONTRACT inputs="none" outputs="none" errors="none" side_effects="none"]
+// CIL[DOC-MICRO logic_summary="Sets up React and API imports used by the useEntityRecord hook." notable_decisions="[]"]
+// CIL[DOC-CONFIDENCE pass="second" score="0.85" flags="none"]
 // CIL[DOC-STABILITY stability="stable"]
-// CIL[DOC-AUDIENCE audience="developer"]
-// CIL[DOC-VECTOR type="context" content="Layer: frontend-hook. Direct callers: 0. Direct calls: 0. Related files: custom/apps/portal/pages/ContentPage.tsx, custom/apps/cortex/pages/operations/OperationsDashboard.tsx, .framework/src/pages/admin/IntegrationsPage.tsx, .framework/functions/_shared/principal.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"]
+// CIL[DOC-AUDIENCE audience="internal"]
 import { useCallback } from 'react'
 import { useApi, useMutation } from './useApi'
 import { apiFetch } from '../lib/api'
 import { useAuth } from '../contexts/AuthContext'
+// CIL[DOC-VECTOR type="context" content="purpose='React hook for fetching and managing a single entity record'; No verified external callers; imports: .framework/src/hooks/useApi.ts,.framework/src/lib/api.ts,.framework/src/contexts/AuthContext.tsx"]
+// CIL[DOC-VECTOR type="blast_radius" content="No direct caller data from CIL graph; local impact only"]
+// CIL[DOC-VECTOR type="configuration" content="No environment or build configuration dependencies identified"]
+// CIL[DOC-VECTOR type="constraint" content="Standard runtime; no special invariants documented"]
+// CIL[DOC-VECTOR type="implementation_pattern" content="" status="pending_human_input"]
+// CIL[DOC-VECTOR type="user_journey" content="" status="pending_human_input"]
+// CIL[END stable_id="~/.framework/src/hooks/useEntityRecord.ts:module_header:module_header"]
 
+// CIL[BEGIN stable_id="~/.framework/src/hooks/useEntityRecord.ts:fieldpermissions:interface" type="interface" identity="fieldpermissions" parent="~/.framework/src/hooks/useEntityRecord.ts"]
+// CIL[DOC-MACRO purpose="Field-level read and write permission map"]
+// CIL[DOC-RESPONSIBILITY responsibility="Defines the shape of per-field permissions with read and write booleans"]
+// CIL[DOC-CONTEXT module="useEntityRecord" layer="hooks" related_files=".framework/src/contexts/AuthContext.tsx,.framework/src/hooks/useApi.ts,.framework/src/hooks/useEntityRecord.ts,.framework/src/lib/api.ts"]
+// CIL[DOC-CONTRACT inputs="none" outputs="FieldPermissions object" errors="none" side_effects="none"]
+// CIL[DOC-MICRO logic_summary="Maps a field name to an object containing read and write flags." notable_decisions="[]"]
+// CIL[DOC-CONFIDENCE pass="second" score="0.85" flags="none"]
+// CIL[DOC-STABILITY stability="stable"]
 interface FieldPermissions {
   [key: string]: { read: boolean; write: boolean }
 }
+// CIL[DOC-VECTOR type="context" content="purpose='Field-level read and write permission map'; No verified external callers; imports: .framework/src/hooks/useApi.ts,.framework/src/lib/api.ts,.framework/src/contexts/AuthContext.tsx"]
+// CIL[DOC-VECTOR type="blast_radius" content="No direct caller data from CIL graph; local impact only"]
+// CIL[DOC-VECTOR type="configuration" content="No environment or build configuration dependencies identified"]
+// CIL[DOC-VECTOR type="constraint" content="Standard runtime; no special invariants documented"]
+// CIL[DOC-VECTOR type="implementation_pattern" content="" status="pending_human_input"]
+// CIL[DOC-VECTOR type="user_journey" content="" status="pending_human_input"]
+// CIL[END stable_id="~/.framework/src/hooks/useEntityRecord.ts:fieldpermissions:interface"]
+
 
+// CIL[BEGIN stable_id="~/.framework/src/hooks/useEntityRecord.ts:MinimalEntityConfig:interface" type="interface" identity="MinimalEntityConfig" parent="~/.framework/src/hooks/useEntityRecord.ts"]
+// CIL[DOC-MACRO purpose="Minimal configuration shape for an entity"]
+// CIL[DOC-RESPONSIBILITY responsibility="Declares the configuration required to drive entity CRUD and API action overrides"]
+// CIL[DOC-CONTEXT module="useEntityRecord" layer="hooks" related_files=".framework/src/contexts/AuthContext.tsx,.framework/src/hooks/useApi.ts,.framework/src/hooks/useEntityRecord.ts,.framework/src/lib/api.ts"]
+// CIL[DOC-CONTRACT inputs="none" outputs="MinimalEntityConfig object" errors="none" side_effects="none"]
+// CIL[DOC-MICRO logic_summary="Defines entity metadata, icon, display field, and optional API action overrides." notable_decisions="[]"]
+// CIL[DOC-CONFIDENCE pass="second" score="0.85" flags="none"]
+// CIL[DOC-STABILITY stability="stable"]
 interface MinimalEntityConfig {
   entity: string
   typeSlug?: string
@@ -38,7 +61,23 @@ interface MinimalEntityConfig {
   }
   softDelete?: boolean
 }
+// CIL[DOC-VECTOR type="context" content="purpose='Minimal configuration shape for an entity'; No verified external callers; imports: .framework/src/hooks/useApi.ts,.framework/src/lib/api.ts,.framework/src/contexts/AuthContext.tsx"]
+// CIL[DOC-VECTOR type="blast_radius" content="No direct caller data from CIL graph; local impact only"]
+// CIL[DOC-VECTOR type="configuration" content="No environment or build configuration dependencies identified"]
+// CIL[DOC-VECTOR type="constraint" content="Standard runtime; no special invariants documented"]
+// CIL[DOC-VECTOR type="implementation_pattern" content="" status="pending_human_input"]
+// CIL[DOC-VECTOR type="user_journey" content="" status="pending_human_input"]
+// CIL[END stable_id="~/.framework/src/hooks/useEntityRecord.ts:MinimalEntityConfig:interface"]
 
+
+// CIL[BEGIN stable_id="~/.framework/src/hooks/useEntityRecord.ts:UseEntityRecordReturn:interface" type="interface" identity="UseEntityRecordReturn" parent="~/.framework/src/hooks/useEntityRecord.ts"]
+// CIL[DOC-MACRO purpose="Return shape for useEntityRecord"]
+// CIL[DOC-RESPONSIBILITY responsibility="Declares the object returned by the useEntityRecord hook including state, schema, permissions, and callbacks"]
+// CIL[DOC-CONTEXT module="useEntityRecord" layer="hooks" related_files=".framework/src/contexts/AuthContext.tsx,.framework/src/hooks/useApi.ts,.framework/src/hooks/useEntityRecord.ts,.framework/src/lib/api.ts"]
+// CIL[DOC-CONTRACT inputs="none" outputs="UseEntityRecordReturn object" errors="none" side_effects="none"]
+// CIL[DOC-MICRO logic_summary="Exposes record state, schema, field permissions, loading and error flags, and save/delete mutators." notable_decisions="[]"]
+// CIL[DOC-CONFIDENCE pass="second" score="0.85" flags="none"]
+// CIL[DOC-STABILITY stability="stable"]
 interface UseEntityRecordReturn {
   record: any
   schema: any
@@ -51,23 +90,22 @@ interface UseEntityRecordReturn {
   saving: boolean
   deleting: boolean
 }
-// CIL[END chunk_id="useentityrecord_module_header_1783719596"]
-// CIL[BEGIN chunk_id="useentityrecord_useentityrecord_1783719596" type="function" identity="useEntityRecord" parent="none"]
-// CIL[DOC-LEARNING topic="runtime-type:generic/entity_record" content="useEntityRecord splits a record into system fields (field.system=true, stored on the row) and data fields (stored in record.data) using record.design_schema.fields. It applies field-level permissions before saving and uses the design_schema to build the update payload."]
-// CIL[DOC-NOTE type="design_schema_caveat" content="If record.design_schema is not stamped or fields is empty, all values may be treated as data and silently dropped by row-level validation or security policies."]
-// CIL[DOC-MACRO purpose="Fetch, save, and delete single entity records with permissions"]
-// CIL[DOC-RESPONSIBILITY responsibility="Record CRUD operations, field permissions, schema extraction"]
-// CIL[DOC-CONTEXT module="useEntityRecord" layer="frontend-hook" related_files="[\".framework/src/pages/admin/TypeDetailPage.tsx\",\"custom/apps/portal/pages/ContentPage.tsx\",\".framework/src/pages/admin/RolesPage.tsx\",\".framework/functions/_shared/principal.ts\",\"custom/apps/cortex/pages/operations/OperationsDashboard.tsx\",\"\\\"]"]
-// CIL[DOC-CONTRACT inputs="none" outputs="UseEntityRecordReturn with record, permissions, mutations" errors="Network errors, permission errors" side_effects="React state updates, API calls via apiFetch"]
-// CIL[DOC-MICRO logic_summary="Fetches record, calculates field permissions from schema, handles create/update/delete with system/custom field separation" 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-hook. Direct callers: 3. Direct calls: 0. Related files: .framework/src/pages/admin/TypeDetailPage.tsx, custom/apps/portal/pages/ContentPage.tsx, .framework/src/pages/admin/RolesPage.tsx, .framework/functions/_shared/principal.ts, custom/apps/cortex/pages/operations/OperationsDashboard.tsx, \."]
-// CIL[DOC-VECTOR type="blast_radius" content="Direct callers: 3. Total affected: 3."]
-// CIL[DOC-VECTOR type="configuration" content="No configuration dependencies."]
-// CIL[DOC-VECTOR type="constraint" content="No test paths identified."]
+// CIL[DOC-VECTOR type="context" content="purpose='Return shape for useEntityRecord'; No verified external callers; imports: .framework/src/hooks/useApi.ts,.framework/src/lib/api.ts,.framework/src/contexts/AuthContext.tsx"]
+// CIL[DOC-VECTOR type="blast_radius" content="No direct caller data from CIL graph; local impact only"]
+// CIL[DOC-VECTOR type="configuration" content="No environment or build configuration dependencies identified"]
+// CIL[DOC-VECTOR type="constraint" content="Standard runtime; no special invariants documented"]
 // CIL[DOC-VECTOR type="implementation_pattern" content="" status="pending_human_input"]
 // CIL[DOC-VECTOR type="user_journey" content="" status="pending_human_input"]
+// CIL[END stable_id="~/.framework/src/hooks/useEntityRecord.ts:UseEntityRecordReturn:interface"]
+
+// CIL[BEGIN stable_id="~/.framework/src/hooks/useEntityRecord.ts:useEntityRecord:hook" type="function" identity="useEntityRecord" parent="~/.framework/src/hooks/useEntityRecord.ts"]
+// CIL[DOC-MACRO purpose="Fetch, save, and delete a single runtime entity record"]
+// CIL[DOC-RESPONSIBILITY responsibility="Provides a React hook that loads a record, derives schema and field permissions, and exposes save and delete mutations"]
+// CIL[DOC-CONTEXT module="useEntityRecord" layer="hooks" related_files=".framework/src/contexts/AuthContext.tsx,.framework/src/hooks/useApi.ts,.framework/src/hooks/useEntityRecord.ts,.framework/src/lib/api.ts"]
+// CIL[DOC-CONTRACT inputs="entity: string, id: string | undefined, config: MinimalEntityConfig | null" outputs="UseEntityRecordReturn" errors="Throws on failed API requests; returns error string from useApi" side_effects="Calls apiFetch for GET, PATCH, POST, and DELETE requests via useMutation"]
+// CIL[DOC-MICRO logic_summary="Fetches record by ID when present, derives permissions from user roles and design schema, and performs create/update/delete via useMutation." notable_decisions="[]"]
+// CIL[DOC-CONFIDENCE pass="second" score="0.85" flags="none"]
+// CIL[DOC-STABILITY stability="stable"]
 export function useEntityRecord(
   entity: string,
   id: string | undefined,
@@ -244,4 +282,10 @@ export function useEntityRecord(
     deleting: deleteMutation.loading
   }
 }
-// CIL[END chunk_id="useentityrecord_useentityrecord_1783719596"]
+// CIL[DOC-VECTOR type="context" content="purpose='Fetch, save, and delete a single runtime entity record'; No verified external callers; imports: .framework/src/hooks/useApi.ts,.framework/src/lib/api.ts,.framework/src/contexts/AuthContext.tsx"]
+// CIL[DOC-VECTOR type="blast_radius" content="No direct caller data from CIL graph; local impact only"]
+// CIL[DOC-VECTOR type="configuration" content="No environment or build configuration dependencies identified"]
+// CIL[DOC-VECTOR type="constraint" content="Standard runtime; no special invariants documented"]
+// CIL[DOC-VECTOR type="implementation_pattern" content="" status="pending_human_input"]
+// CIL[DOC-VECTOR type="user_journey" content="" status="pending_human_input"]
+// CIL[END stable_id="~/.framework/src/hooks/useEntityRecord.ts:useEntityRecord:hook"]

package/.framework/src/hooks/useForm.ts

@@ -1,23 +1,32 @@
+// CIL[BEGIN stable_id="~/.framework/src/hooks/useForm.ts:module_header:module_header" type="module_header" identity="module_header" parent="~/.framework/src/hooks/useForm.ts"]
+// CIL[DOC-MACRO purpose="Import React hooks and shared form types for useForm"]
+// CIL[DOC-RESPONSIBILITY responsibility="Set up module dependencies and type imports for the useForm hook"]
+// CIL[DOC-CONTEXT module=".framework/src/hooks" layer="hooks" related_files=".framework/src/types/types.ts"]
+// CIL[DOC-CONTRACT inputs="" outputs="" errors="" side_effects=""]
+// CIL[DOC-MICRO logic_summary="Imports useState, useCallback, useEffect from react and FieldDefinition, FormState, ValidationError from ../types/types" notable_decisions=""]
+// CIL[DOC-CONFIDENCE pass="second" score="0.90" flags="none"]
+// CIL[DOC-STABILITY stable]
+// CIL[DOC-AUDIENCE audience="Developers using the useForm form-state hook"]
 
-
-// CIL[BEGIN chunk_id="useform_module_header_1783719596" type="module_header" identity="module_header" parent="none"]
-// CIL[DOC-MACRO purpose="Define form hook types and interfaces"]
-// CIL[DOC-RESPONSIBILITY responsibility="Type definitions for form management"]
-// CIL[DOC-CONTEXT module="useForm" layer="frontend-hook" related_files="[\"custom/apps/portal/pages/ContentPage.tsx\",\"custom/apps/cortex/pages/operations/OperationsDashboard.tsx\",\".framework/src/pages/admin/IntegrationsPage.tsx\",\".framework/functions/_shared/principal.ts\",\".framework/functions/_shared/schema-utils.ts\",\"\\\"]"]
-// CIL[DOC-CONTRACT inputs="none" outputs="UseFormOptions and UseFormReturn interfaces" errors="none" side_effects="Type declarations"]
-// CIL[DOC-MICRO logic_summary="Exports interfaces for form options, return values, and field definitions" 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-hook. Direct callers: 0. Direct calls: 0. Related files: custom/apps/portal/pages/ContentPage.tsx, custom/apps/cortex/pages/operations/OperationsDashboard.tsx, .framework/src/pages/admin/IntegrationsPage.tsx, .framework/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 { useState, useCallback, useEffect } from 'react'
 import { FieldDefinition, FormState, ValidationError } from '../types/types'
+// CIL[DOC-VECTOR type="context" content="purpose='Import React hooks and shared form types for useForm'; No verified external callers; imports: .framework/src/types/types.ts"]
+// CIL[DOC-VECTOR type="blast_radius" content="No direct caller data from CIL graph; local impact only"]
+// CIL[DOC-VECTOR type="configuration" content="No environment or build configuration dependencies identified"]
+// CIL[DOC-VECTOR type="constraint" content="Standard runtime; no special invariants documented"]
+// CIL[DOC-VECTOR type="implementation_pattern" content="" status="pending_human_input"]
+// CIL[DOC-VECTOR type="user_journey" content="" status="pending_human_input"]
+// CIL[END stable_id="~/.framework/src/hooks/useForm.ts:module_header:module_header"]
+
 
+// CIL[BEGIN stable_id="~/.framework/src/hooks/useForm.ts:UseFormOptions:interface" type="interface" identity="UseFormOptions" parent="~/.framework/src/hooks/useForm.ts"]
+// CIL[DOC-MACRO purpose="Define configuration options for the useForm hook"]
+// CIL[DOC-RESPONSIBILITY responsibility="Declare the shape of options accepted by useForm"]
+// CIL[DOC-CONTEXT module=".framework/src/hooks" layer="hooks" related_files=".framework/src/hooks/useForm.ts,.framework/src/types/types.ts"]
+// CIL[DOC-CONTRACT inputs="none" outputs="UseFormOptions interface" errors="" side_effects="none"]
+// CIL[DOC-MICRO logic_summary="Describes initial values, an array of FieldDefinition objects, and optional onSubmit, validate, and onChange callbacks" notable_decisions="Validation and change callbacks are optional"]
+// CIL[DOC-CONFIDENCE pass="second" score="0.90" flags="none"]
+// CIL[DOC-STABILITY stable]
 interface UseFormOptions {
   initialValues: Record<string, any>
   fields: FieldDefinition[]
@@ -25,7 +34,23 @@ interface UseFormOptions {
   validate?: (values: Record<string, any>) => Record<string, string>
   onChange?: (values: Record<string, any>) => void
 }
+// CIL[DOC-VECTOR type="context" content="purpose='Define configuration options for the useForm hook'; No verified external callers; imports: .framework/src/types/types.ts"]
+// CIL[DOC-VECTOR type="blast_radius" content="No direct caller data from CIL graph; local impact only"]
+// CIL[DOC-VECTOR type="configuration" content="No environment or build configuration dependencies identified"]
+// CIL[DOC-VECTOR type="constraint" content="Standard runtime; no special invariants documented"]
+// CIL[DOC-VECTOR type="implementation_pattern" content="" status="pending_human_input"]
+// CIL[DOC-VECTOR type="user_journey" content="" status="pending_human_input"]
+// CIL[END stable_id="~/.framework/src/hooks/useForm.ts:UseFormOptions:interface"]
+
 
+// CIL[BEGIN stable_id="~/.framework/src/hooks/useForm.ts:UseFormReturn:interface" type="interface" identity="UseFormReturn" parent="~/.framework/src/hooks/useForm.ts"]
+// CIL[DOC-MACRO purpose="Define the return shape of the useForm hook"]
+// CIL[DOC-RESPONSIBILITY responsibility="Declare the exposed form state and imperative callbacks available to consumers"]
+// CIL[DOC-CONTEXT module=".framework/src/hooks" layer="hooks" related_files=".framework/src/hooks/useForm.ts,.framework/src/types/types.ts"]
+// CIL[DOC-CONTRACT inputs="none" outputs="UseFormReturn interface" errors="" side_effects="none"]
+// CIL[DOC-MICRO logic_summary="Exposes data, errors, touched, isSubmitting, isValid, isDirty, and change/blur/submit/reset helper callbacks" notable_decisions=""]
+// CIL[DOC-CONFIDENCE pass="second" score="0.90" flags="none"]
+// CIL[DOC-STABILITY stable]
 interface UseFormReturn {
   data: Record<string, any>
   errors: Record<string, string>
@@ -41,21 +66,22 @@ interface UseFormReturn {
   setFieldError: (field: string, error: string) => void
   clearErrors: () => void
 }
-// CIL[END chunk_id="useform_module_header_1783719596"]
-// CIL[BEGIN chunk_id="useform_useform_1783719596" type="function" identity="useForm" parent="none"]
-// CIL[DOC-MACRO purpose="Schema-driven form state and validation management"]
-// CIL[DOC-RESPONSIBILITY responsibility="Form validation, state management, submission handling"]
-// CIL[DOC-CONTEXT module="useForm" layer="frontend-hook" related_files="[\"custom/apps/portal/pages/ContentPage.tsx\",\".framework/functions/_shared/schema-utils.ts\",\".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="UseFormReturn with form state and handlers" errors="Validation errors, submission errors" side_effects="React state updates, API calls via onSubmit"]
-// CIL[DOC-MICRO logic_summary="Implements field-level validation, form submission, error handling, and state management for schema-driven forms" 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-hook. Direct callers: 0. Direct calls: 0. Related files: custom/apps/portal/pages/ContentPage.tsx, .framework/functions/_shared/schema-utils.ts, .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="context" content="purpose='Define the return shape of the useForm hook'; No verified external callers; imports: .framework/src/types/types.ts"]
+// CIL[DOC-VECTOR type="blast_radius" content="No direct caller data from CIL graph; local impact only"]
+// CIL[DOC-VECTOR type="configuration" content="No environment or build configuration dependencies identified"]
+// CIL[DOC-VECTOR type="constraint" content="Standard runtime; no special invariants documented"]
 // CIL[DOC-VECTOR type="implementation_pattern" content="" status="pending_human_input"]
 // CIL[DOC-VECTOR type="user_journey" content="" status="pending_human_input"]
+// CIL[END stable_id="~/.framework/src/hooks/useForm.ts:UseFormReturn:interface"]
+
+// CIL[BEGIN stable_id="~/.framework/src/hooks/useForm.ts:useForm:hook" type="hook" identity="useForm" parent="~/.framework/src/hooks/useForm.ts"]
+// CIL[DOC-MACRO purpose="Manage React form state, validation, and submission for typed field definitions"]
+// CIL[DOC-RESPONSIBILITY responsibility="Track form data, validate fields and full form, expose change/blur/submit handlers and reset helpers"]
+// CIL[DOC-CONTEXT module=".framework/src/hooks" layer="hooks" related_files=".framework/src/hooks/useForm.ts,.framework/src/types/types.ts"]
+// CIL[DOC-CONTRACT inputs="{initialValues,fields,onSubmit,validate,onChange}:UseFormOptions" outputs="UseFormReturn (data, errors, touched, isSubmitting, isValid, isDirty, handlers)" errors="Field validation messages and uncaught submission errors logged to console" side_effects="Updates React state, invokes onSubmit and onChange callbacks, logs submission errors to console"]
+// CIL[DOC-MICRO logic_summary="Validates individual fields by data_type and custom validator, aggregates form errors, manages dirty and touched state, and handles async submission with an isSubmitting flag" notable_decisions="Validation clears the error for a changed field before blur; setFieldError and clearErrors allow manual error control"]
+// CIL[DOC-CONFIDENCE pass="second" score="0.90" flags="none"]
+// CIL[DOC-STABILITY stable]
 export function useForm({
   initialValues,
   fields,
@@ -244,4 +270,10 @@ export function useForm({
     clearErrors
   }
 }
-// CIL[END chunk_id="useform_useform_1783719596"]
+// CIL[DOC-VECTOR type="context" content="purpose='Manage React form state, validation, and submission for typed field definitions'; No verified external callers; imports: .framework/src/types/types.ts"]
+// CIL[DOC-VECTOR type="blast_radius" content="No direct caller data from CIL graph; local impact only"]
+// CIL[DOC-VECTOR type="configuration" content="No environment or build configuration dependencies identified"]
+// CIL[DOC-VECTOR type="constraint" content="Standard runtime; no special invariants documented"]
+// CIL[DOC-VECTOR type="implementation_pattern" content="" status="pending_human_input"]
+// CIL[DOC-VECTOR type="user_journey" content="" status="pending_human_input"]
+// CIL[END stable_id="~/.framework/src/hooks/useForm.ts:useForm:hook"]