spine-framework 0.3.145 → 0.4.0

package/.framework/src/hooks/useApi.ts

@@ -1,3 +1,13 @@
+// CIL[BEGIN stable_id="~/.framework/src/hooks/useApi.ts:module_header:module_header" type="module_header" identity="module_header" parent="~/.framework/src/hooks/useApi.ts"]
+// CIL[DOC-MACRO purpose="React hooks for asynchronous API operations including fetching, pagination, and mutations"]
+// CIL[DOC-RESPONSIBILITY responsibility="Provide reusable React hooks that encapsulate data fetching, pagination, and mutation state"]
+// CIL[DOC-CONTEXT module="hooks" layer="frontend" related_files=".framework/src/hooks/useApi.ts"]
+// CIL[DOC-CONTRACT inputs="" outputs="useApi, usePaginatedApi, useMutation" errors="" side_effects="none"]
+// CIL[DOC-MICRO logic_summary="Exports three hooks for asynchronous API state management" notable_decisions="Keeps related data fetching patterns in a single module"]
+// CIL[DOC-CONFIDENCE pass="second" score="0.90" flags="none"]
+// CIL[DOC-STABILITY stability="stable"]
+// CIL[DOC-AUDIENCE audience="frontend-developers"]
+
 
 
 
@@ -10,59 +20,46 @@
 
 
 
-// CIL[BEGIN chunk_id="useapi_module_header_1783740744" type="module_header" identity="imports" parent="none"]
-// CIL[DOC-MACRO purpose="Import React hooks and router for API functionality"]
-// CIL[DOC-RESPONSIBILITY responsibility="Provide core React dependencies for API state management"]
-// CIL[DOC-CONTEXT module="useApi" 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/functions/_shared/principal.ts\",\".framework/functions/_shared/schema-utils.ts\",\"\\\"]"]
-// CIL[DOC-CONTRACT inputs="none" outputs="React hooks" errors="none" side_effects="Module imports"]
-// CIL[DOC-MICRO logic_summary="Imports useState, useEffect, useCallback, useRef from React and useLocation from react-router-dom" 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/TypeDetailPage.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, useRef } from 'react'
 import { useLocation } from 'react-router-dom'
-// CIL[END chunk_id="useapi_module_header_1783740744"]
-// CIL[BEGIN chunk_id="useapi_apistate_1783740744" type="interface" identity="ApiState" parent="none"]
-// CIL[DOC-MACRO purpose="Define API state structure for loading, data, and error tracking"]
-// CIL[DOC-RESPONSIBILITY responsibility="Own the core state shape for API operations"]
-// CIL[DOC-CONTEXT module="useApi" layer="frontend-hook" related_files="[\"custom/apps/portal/pages/ContentPage.tsx\",\".framework/src/pages/admin/IntegrationsPage.tsx\",\".framework/functions/_shared/principal.ts\",\"custom/apps/cortex/pages/operations/OperationsDashboard.tsx\",\".framework/functions/_shared/schema-utils.ts\",\"\\\"]"]
-// CIL[DOC-CONTRACT inputs="none" outputs="state interface" errors="none" side_effects="Type definition"]
-// CIL[DOC-MICRO logic_summary="Generic interface with data, loading, error, and lastFetched fields" notable_decisions="[]"]
-// CIL[DOC-CONFIDENCE pass="second" score="0.95" flags="none"]
-// CIL[DOC-STABILITY stability="stable"]
-// CIL[DOC-VECTOR type="context" content="Layer: frontend-hook. Direct callers: 0. Direct calls: 0. Related files: custom/apps/portal/pages/ContentPage.tsx, .framework/src/pages/admin/IntegrationsPage.tsx, .framework/functions/_shared/principal.ts, custom/apps/cortex/pages/operations/OperationsDashboard.tsx, .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="context" content="purpose='React hooks for asynchronous API operations including fetching, pagination, and mutations'; No verified external callers; imports: none"]
+// 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/useApi.ts:module_header:module_header"]
+
+// CIL[BEGIN stable_id="~/.framework/src/hooks/useApi.ts:ApiState:interface" type="interface" identity="ApiState" parent="~/.framework/src/hooks/useApi.ts"]
+// CIL[DOC-MACRO purpose="Type definition for ApiState"]
+// CIL[DOC-RESPONSIBILITY responsibility="Define the fields and shape of the ApiState interface"]
+// CIL[DOC-CONTEXT module="hooks" layer="frontend" related_files=".framework/src/hooks/useApi.ts"]
+// CIL[DOC-CONTRACT inputs="generic type parameters" outputs="data, loading, error, lastFetched" errors="" side_effects="none"]
+// CIL[DOC-MICRO logic_summary="Describes the structure of the ApiState data object" notable_decisions="Tracks lastFetched to record the most recent successful fetch"]
+// CIL[DOC-CONFIDENCE pass="second" score="0.90" flags="none"]
+// CIL[DOC-STABILITY stability="stable"]
 interface ApiState<T> {
   data: T | null
   loading: boolean
   error: string | null
   lastFetched: Date | null
 }
-// CIL[END chunk_id="useapi_apistate_1783740744"]
-// CIL[BEGIN chunk_id="useapi_useapioptions_1783740744" type="interface" identity="UseApiOptions" parent="none"]
-// CIL[DOC-MACRO purpose="Configure API hook behavior with callbacks and initial data"]
-// CIL[DOC-RESPONSIBILITY responsibility="Define configuration options for API hook usage"]
-// CIL[DOC-CONTEXT module="useApi" layer="frontend-hook" related_files="[\"custom/apps/portal/pages/ContentPage.tsx\",\".framework/src/pages/admin/IntegrationsPage.tsx\",\".framework/functions/_shared/schema-utils.ts\",\".framework/src/pages/admin/RolesPage.tsx\",\"custom/apps/cortex/pages/operations/OperationsDashboard.tsx\",\"\\\"]"]
-// CIL[DOC-CONTRACT inputs="none" outputs="options interface" errors="none" side_effects="Type definition"]
-// CIL[DOC-MICRO logic_summary="Options for immediate execution, success/error callbacks, initial data, and dependencies" 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/src/pages/admin/IntegrationsPage.tsx, .framework/functions/_shared/schema-utils.ts, .framework/src/pages/admin/RolesPage.tsx, custom/apps/cortex/pages/operations/OperationsDashboard.tsx, \."]
-// CIL[DOC-VECTOR type="blast_radius" content="Direct callers: 0. Total affected: 0."]
-// CIL[DOC-VECTOR type="configuration" content="No configuration dependencies."]
-// CIL[DOC-VECTOR type="constraint" content="No test paths identified."]
+// CIL[DOC-VECTOR type="context" content="purpose='Type definition for ApiState'; No verified external callers; imports: none"]
+// 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/useApi.ts:ApiState:interface"]
+
+// CIL[BEGIN stable_id="~/.framework/src/hooks/useApi.ts:UseApiOptions:interface" type="interface" identity="UseApiOptions" parent="~/.framework/src/hooks/useApi.ts"]
+// CIL[DOC-MACRO purpose="Type definition for UseApiOptions"]
+// CIL[DOC-RESPONSIBILITY responsibility="Define the fields and shape of the UseApiOptions interface"]
+// CIL[DOC-CONTEXT module="hooks" layer="frontend" related_files=".framework/src/hooks/useApi.ts"]
+// CIL[DOC-CONTRACT inputs="generic type parameters" outputs="immediate, onSuccess, onError, initialData, deps" errors="" side_effects="none"]
+// CIL[DOC-MICRO logic_summary="Describes the structure of the UseApiOptions data object" notable_decisions="Uses generics to remain flexible across concrete API payloads"]
+// CIL[DOC-CONFIDENCE pass="second" score="0.90" flags="none"]
+// CIL[DOC-STABILITY stability="stable"]
 interface UseApiOptions<T> {
   immediate?: boolean
   onSuccess?: (data: T) => void
@@ -70,21 +67,22 @@ interface UseApiOptions<T> {
   initialData?: T
   deps?: any[]
 }
-// CIL[END chunk_id="useapi_useapioptions_1783740744"]
-// CIL[BEGIN chunk_id="useapi_useapireturn_1783740744" type="interface" identity="UseApiReturn" parent="none"]
-// CIL[DOC-MACRO purpose="Define the return value structure for useApi hook"]
-// CIL[DOC-RESPONSIBILITY responsibility="Shape the public API surface for consumers"]
-// CIL[DOC-CONTEXT module="useApi" layer="frontend-hook" related_files="[\".framework/functions/_shared/principal.ts\",\".framework/src/pages/admin/IntegrationsPage.tsx\",\"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="return interface" errors="none" side_effects="Type definition"]
-// CIL[DOC-MICRO logic_summary="Returns state data, loading status, error, and control functions" 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: .framework/functions/_shared/principal.ts, .framework/src/pages/admin/IntegrationsPage.tsx, 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="context" content="purpose='Type definition for UseApiOptions'; No verified external callers; imports: none"]
+// 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/useApi.ts:UseApiOptions:interface"]
+
+// CIL[BEGIN stable_id="~/.framework/src/hooks/useApi.ts:UseApiReturn:interface" type="interface" identity="UseApiReturn" parent="~/.framework/src/hooks/useApi.ts"]
+// CIL[DOC-MACRO purpose="Type definition for UseApiReturn"]
+// CIL[DOC-RESPONSIBILITY responsibility="Define the fields and shape of the UseApiReturn interface"]
+// CIL[DOC-CONTEXT module="hooks" layer="frontend" related_files=".framework/src/hooks/useApi.ts"]
+// CIL[DOC-CONTRACT inputs="generic type parameters" outputs="data, loading, error, execute, reset, refetch" errors="" side_effects="none"]
+// CIL[DOC-MICRO logic_summary="Describes the structure of the UseApiReturn data object" notable_decisions="Returns both state and controller functions"]
+// CIL[DOC-CONFIDENCE pass="second" score="0.90" flags="none"]
+// CIL[DOC-STABILITY stability="stable"]
 interface UseApiReturn<T> {
   data: T | null
   loading: boolean
@@ -93,21 +91,22 @@ interface UseApiReturn<T> {
   reset: () => void
   refetch: () => Promise<T>
 }
-// CIL[END chunk_id="useapi_useapireturn_1783740744"]
-// CIL[BEGIN chunk_id="useapi_useapi_1783740744" type="function" identity="useApi" parent="none"]
-// CIL[DOC-MACRO purpose="Core async API hook with loading state and request cancellation"]
-// CIL[DOC-RESPONSIBILITY responsibility="Manage API calls, state, and automatic cleanup on navigation"]
-// CIL[DOC-CONTEXT module="useApi" layer="frontend-hook" related_files="[]"]
-// CIL[DOC-CONTRACT inputs="none" outputs="UseApiReturn" errors="throws API errors" side_effects="React state, AbortController"]
-// CIL[DOC-MICRO logic_summary="Wraps async functions with loading state, error handling, and AbortController for cancellation" 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: none."]
-// CIL[DOC-VECTOR type="blast_radius" content="Direct callers: 0. Total affected: 0."]
-// CIL[DOC-VECTOR type="configuration" content="No configuration dependencies."]
-// CIL[DOC-VECTOR type="constraint" content="No test paths identified."]
+// CIL[DOC-VECTOR type="context" content="purpose='Type definition for UseApiReturn'; No verified external callers; imports: none"]
+// 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/useApi.ts:UseApiReturn:interface"]
+
+// CIL[BEGIN stable_id="~/.framework/src/hooks/useApi.ts:useApi:hook" type="hook" identity="useApi" parent="~/.framework/src/hooks/useApi.ts"]
+// CIL[DOC-MACRO purpose="React hook for fetching data from an API with cancellation support"]
+// CIL[DOC-RESPONSIBILITY responsibility="Manage async state and lifecycle for useApi"]
+// CIL[DOC-CONTEXT module="hooks" layer="frontend" related_files=".framework/src/hooks/useApi.ts"]
+// CIL[DOC-CONTRACT inputs="apiFunction returning a Promise<T> and UseApiOptions<T>" outputs="UseApiReturn<T> with data, loading, error, execute, reset, refetch" errors="Throws non-AbortError after updating state.error" side_effects="Calls apiFunction, updates React state, invokes onSuccess/onError, logs metrics"]
+// CIL[DOC-MICRO logic_summary="Encapsulates a single async request lifecycle with request cancellation" notable_decisions="Uses refs to keep the latest callback versions and aborts previous in-flight requests"]
+// CIL[DOC-CONFIDENCE pass="second" score="0.90" flags="none"]
+// CIL[DOC-STABILITY stability="stable"]
 export function useApi<T>(
   apiFunction: (params?: any) => Promise<T>,
   options: UseApiOptions<T> = {}
@@ -225,21 +224,22 @@ export function useApi<T>(
     refetch
   }
 }
-// CIL[END chunk_id="useapi_useapi_1783740744"]
-// CIL[BEGIN chunk_id="useapi_paginatedapistate_1783740744" type="interface" identity="PaginatedApiState" parent="none"]
-// CIL[DOC-MACRO purpose="Extend ApiState with pagination metadata for paginated responses"]
-// CIL[DOC-RESPONSIBILITY responsibility="Define state structure for paginated API data"]
-// CIL[DOC-CONTEXT module="useApi" layer="frontend-hook" related_files="[]"]
-// CIL[DOC-CONTRACT inputs="none" outputs="paginated state interface" errors="none" side_effects="Type definition"]
-// CIL[DOC-MICRO logic_summary="Extends ApiState with pagination fields for page, totalPages, totalItems, itemsPerPage" 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: none."]
-// CIL[DOC-VECTOR type="blast_radius" content="Direct callers: 0. Total affected: 0."]
-// CIL[DOC-VECTOR type="configuration" content="No configuration dependencies."]
-// CIL[DOC-VECTOR type="constraint" content="No test paths identified."]
+// CIL[DOC-VECTOR type="context" content="purpose='React hook for fetching data from an API with cancellation support'; No verified external callers; imports: none"]
+// 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/useApi.ts:useApi:hook"]
+
+// CIL[BEGIN stable_id="~/.framework/src/hooks/useApi.ts:PaginatedApiState:interface" type="interface" identity="PaginatedApiState" parent="~/.framework/src/hooks/useApi.ts"]
+// CIL[DOC-MACRO purpose="Type definition for PaginatedApiState"]
+// CIL[DOC-RESPONSIBILITY responsibility="Define the fields and shape of the PaginatedApiState interface"]
+// CIL[DOC-CONTEXT module="hooks" layer="frontend" related_files=".framework/src/hooks/useApi.ts"]
+// CIL[DOC-CONTRACT inputs="generic type parameters" outputs="data, loading, error, lastFetched, pagination" errors="" side_effects="none"]
+// CIL[DOC-MICRO logic_summary="Describes the structure of the PaginatedApiState data object" notable_decisions="Extends ApiState with a pagination block"]
+// CIL[DOC-CONFIDENCE pass="second" score="0.90" flags="none"]
+// CIL[DOC-STABILITY stability="stable"]
 interface PaginatedApiState<T> extends ApiState<T[]> {
   pagination: {
     page: number
@@ -248,39 +248,41 @@ interface PaginatedApiState<T> extends ApiState<T[]> {
     itemsPerPage: number
   }
 }
-// CIL[END chunk_id="useapi_paginatedapistate_1783740744"]
-// CIL[BEGIN chunk_id="useapi_usepaginatedapioptions_1783740744" type="interface" identity="UsePaginatedApiOptions" parent="none"]
-// CIL[DOC-MACRO purpose="Extend UseApiOptions with pagination-specific configuration"]
-// CIL[DOC-RESPONSIBILITY responsibility="Define configuration options for paginated API hook"]
-// CIL[DOC-CONTEXT module="useApi" layer="frontend-hook" related_files="[]"]
-// CIL[DOC-CONTRACT inputs="none" outputs="paginated options interface" errors="none" side_effects="Type definition"]
-// CIL[DOC-MICRO logic_summary="Extends UseApiOptions with itemsPerPage 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-hook. Direct callers: 0. Direct calls: 0. Related files: none."]
-// CIL[DOC-VECTOR type="blast_radius" content="Direct callers: 0. Total affected: 0."]
-// CIL[DOC-VECTOR type="configuration" content="No configuration dependencies."]
-// CIL[DOC-VECTOR type="constraint" content="No test paths identified."]
+// CIL[DOC-VECTOR type="context" content="purpose='Type definition for PaginatedApiState'; No verified external callers; imports: none"]
+// 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/useApi.ts:PaginatedApiState:interface"]
+
+// CIL[BEGIN stable_id="~/.framework/src/hooks/useApi.ts:UsePaginatedApiOptions:interface" type="interface" identity="UsePaginatedApiOptions" parent="~/.framework/src/hooks/useApi.ts"]
+// CIL[DOC-MACRO purpose="Type definition for UsePaginatedApiOptions"]
+// CIL[DOC-RESPONSIBILITY responsibility="Define the fields and shape of the UsePaginatedApiOptions interface"]
+// CIL[DOC-CONTEXT module="hooks" layer="frontend" related_files=".framework/src/hooks/useApi.ts"]
+// CIL[DOC-CONTRACT inputs="generic type parameters" outputs="immediate, onSuccess, onError, initialData, deps, itemsPerPage" errors="" side_effects="none"]
+// CIL[DOC-MICRO logic_summary="Describes the structure of the UsePaginatedApiOptions data object" notable_decisions="Extends UseApiOptions with pagination settings"]
+// CIL[DOC-CONFIDENCE pass="second" score="0.90" flags="none"]
+// CIL[DOC-STABILITY stability="stable"]
 interface UsePaginatedApiOptions<T> extends UseApiOptions<T[]> {
   itemsPerPage?: number
 }
-// CIL[END chunk_id="useapi_usepaginatedapioptions_1783740744"]
-// CIL[BEGIN chunk_id="useapi_usepaginatedapireturn_1783740744" type="interface" identity="UsePaginatedApiReturn" parent="none"]
-// CIL[DOC-MACRO purpose="Extend UseApiReturn with pagination navigation controls"]
-// CIL[DOC-RESPONSIBILITY responsibility="Define return structure for paginated API hook with navigation"]
-// CIL[DOC-CONTEXT module="useApi" layer="frontend-hook" related_files="[]"]
-// CIL[DOC-CONTRACT inputs="none" outputs="paginated return interface" errors="none" side_effects="Type definition"]
-// CIL[DOC-MICRO logic_summary="Extends UseApiReturn with pagination state and navigation functions" 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: none."]
-// CIL[DOC-VECTOR type="blast_radius" content="Direct callers: 0. Total affected: 0."]
-// CIL[DOC-VECTOR type="configuration" content="No configuration dependencies."]
-// CIL[DOC-VECTOR type="constraint" content="No test paths identified."]
+// CIL[DOC-VECTOR type="context" content="purpose='Type definition for UsePaginatedApiOptions'; No verified external callers; imports: none"]
+// 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/useApi.ts:UsePaginatedApiOptions:interface"]
+
+// CIL[BEGIN stable_id="~/.framework/src/hooks/useApi.ts:UsePaginatedApiReturn:interface" type="interface" identity="UsePaginatedApiReturn" parent="~/.framework/src/hooks/useApi.ts"]
+// CIL[DOC-MACRO purpose="Type definition for UsePaginatedApiReturn"]
+// CIL[DOC-RESPONSIBILITY responsibility="Define the fields and shape of the UsePaginatedApiReturn interface"]
+// CIL[DOC-CONTEXT module="hooks" layer="frontend" related_files=".framework/src/hooks/useApi.ts"]
+// CIL[DOC-CONTRACT inputs="generic type parameters" outputs="data, loading, error, execute, reset, refetch, pagination, setPage, setItemsPerPage, nextPage, prevPage, hasNextPage, hasPrevPage" errors="" side_effects="none"]
+// CIL[DOC-MICRO logic_summary="Describes the structure of the UsePaginatedApiReturn data object" notable_decisions="Exposes pagination control methods in addition to base useApi return values"]
+// CIL[DOC-CONFIDENCE pass="second" score="0.90" flags="none"]
+// CIL[DOC-STABILITY stability="stable"]
 interface UsePaginatedApiReturn<T> extends UseApiReturn<T[]> {
   pagination: PaginatedApiState<T>['pagination']
   setPage: (page: number) => void
@@ -290,21 +292,22 @@ interface UsePaginatedApiReturn<T> extends UseApiReturn<T[]> {
   hasNextPage: boolean
   hasPrevPage: boolean
 }
-// CIL[END chunk_id="useapi_usepaginatedapireturn_1783740744"]
-// CIL[BEGIN chunk_id="useapi_usepaginatedapi_1783740744" type="function" identity="usePaginatedApi" parent="none"]
-// CIL[DOC-MACRO purpose="Paginated API hook with page navigation and items-per-page controls"]
-// CIL[DOC-RESPONSIBILITY responsibility="Manage paginated API state and navigation controls"]
-// CIL[DOC-CONTEXT module="useApi" layer="frontend-hook" related_files="[]"]
-// CIL[DOC-CONTRACT inputs="none" outputs="UsePaginatedApiReturn" errors="throws API errors" side_effects="React state, pagination"]
-// CIL[DOC-MICRO logic_summary="Wraps paginated API calls with state management and navigation functions" 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: none."]
-// CIL[DOC-VECTOR type="blast_radius" content="Direct callers: 0. Total affected: 0."]
-// CIL[DOC-VECTOR type="configuration" content="No configuration dependencies."]
-// CIL[DOC-VECTOR type="constraint" content="No test paths identified."]
+// CIL[DOC-VECTOR type="context" content="purpose='Type definition for UsePaginatedApiReturn'; No verified external callers; imports: none"]
+// 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/useApi.ts:UsePaginatedApiReturn:interface"]
+
+// CIL[BEGIN stable_id="~/.framework/src/hooks/useApi.ts:usePaginatedApi:hook" type="hook" identity="usePaginatedApi" parent="~/.framework/src/hooks/useApi.ts"]
+// CIL[DOC-MACRO purpose="React hook for paginated API fetching"]
+// CIL[DOC-RESPONSIBILITY responsibility="Manage async state and lifecycle for usePaginatedApi"]
+// CIL[DOC-CONTEXT module="hooks" layer="frontend" related_files=".framework/src/hooks/useApi.ts"]
+// CIL[DOC-CONTRACT inputs="apiFunction returning {data: T[], pagination} and UsePaginatedApiOptions<T>" outputs="UsePaginatedApiReturn<T> with pagination controls" errors="Throws on API error after setting state.error" side_effects="Fetches new page when page or itemsPerPage changes"]
+// CIL[DOC-MICRO logic_summary="Manages paginated state and refetches when pagination parameters change" notable_decisions="Resets to page 1 when itemsPerPage changes and exposes nextPage/prevPage helpers"]
+// CIL[DOC-CONFIDENCE pass="second" score="0.90" flags="none"]
+// CIL[DOC-STABILITY stability="stable"]
 export function usePaginatedApi<T>(
   apiFunction: (params: { page: number; itemsPerPage: number; [key: string]: any }) => Promise<{
     data: T[]
@@ -441,61 +444,64 @@ export function usePaginatedApi<T>(
     hasPrevPage
   }
 }
-// CIL[END chunk_id="useapi_usepaginatedapi_1783740744"]
-// CIL[BEGIN chunk_id="useapi_mutationstate_1783740744" type="interface" identity="MutationState" parent="none"]
-// CIL[DOC-MACRO purpose="Define state structure for mutation operations"]
-// CIL[DOC-RESPONSIBILITY responsibility="Own the state shape for write operations"]
-// CIL[DOC-CONTEXT module="useApi" layer="frontend-hook" related_files="[]"]
-// CIL[DOC-CONTRACT inputs="none" outputs="mutation state interface" errors="none" side_effects="Type definition"]
-// CIL[DOC-MICRO logic_summary="Simple state interface with data, loading, and error fields for mutations" 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: none."]
-// CIL[DOC-VECTOR type="blast_radius" content="Direct callers: 0. Total affected: 0."]
-// CIL[DOC-VECTOR type="configuration" content="No configuration dependencies."]
-// CIL[DOC-VECTOR type="constraint" content="No test paths identified."]
+// CIL[DOC-VECTOR type="context" content="purpose='React hook for paginated API fetching'; No verified external callers; imports: none"]
+// 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/useApi.ts:usePaginatedApi:hook"]
+
+// CIL[BEGIN stable_id="~/.framework/src/hooks/useApi.ts:MutationState:interface" type="interface" identity="MutationState" parent="~/.framework/src/hooks/useApi.ts"]
+// CIL[DOC-MACRO purpose="Type definition for MutationState"]
+// CIL[DOC-RESPONSIBILITY responsibility="Define the fields and shape of the MutationState interface"]
+// CIL[DOC-CONTEXT module="hooks" layer="frontend" related_files=".framework/src/hooks/useApi.ts"]
+// CIL[DOC-CONTRACT inputs="generic type parameters" outputs="data, loading, error" errors="" side_effects="none"]
+// CIL[DOC-MICRO logic_summary="Describes the structure of the MutationState data object" notable_decisions="Uses generics to remain flexible across concrete API payloads"]
+// CIL[DOC-CONFIDENCE pass="second" score="0.90" flags="none"]
+// CIL[DOC-STABILITY stability="stable"]
 interface MutationState<T> {
   data: T | null
   loading: boolean
   error: string | null
 }
-// CIL[END chunk_id="useapi_mutationstate_1783740744"]
-// CIL[BEGIN chunk_id="useapi_usemutationoptions_1783740744" type="interface" identity="UseMutationOptions" parent="none"]
-// CIL[DOC-MACRO purpose="Define callback options for mutation lifecycle events"]
-// CIL[DOC-RESPONSIBILITY responsibility="Configure mutation hook behavior with lifecycle callbacks"]
-// CIL[DOC-CONTEXT module="useApi" layer="frontend-hook" related_files="[]"]
-// CIL[DOC-CONTRACT inputs="none" outputs="mutation options interface" errors="none" side_effects="Type definition"]
-// CIL[DOC-MICRO logic_summary="Options for success, error, and settled callbacks with typed parameters" 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: none."]
-// CIL[DOC-VECTOR type="blast_radius" content="Direct callers: 0. Total affected: 0."]
-// CIL[DOC-VECTOR type="configuration" content="No configuration dependencies."]
-// CIL[DOC-VECTOR type="constraint" content="No test paths identified."]
+// CIL[DOC-VECTOR type="context" content="purpose='Type definition for MutationState'; No verified external callers; imports: none"]
+// 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/useApi.ts:MutationState:interface"]
+
+// CIL[BEGIN stable_id="~/.framework/src/hooks/useApi.ts:UseMutationOptions:interface" type="interface" identity="UseMutationOptions" parent="~/.framework/src/hooks/useApi.ts"]
+// CIL[DOC-MACRO purpose="Type definition for UseMutationOptions"]
+// CIL[DOC-RESPONSIBILITY responsibility="Define the fields and shape of the UseMutationOptions interface"]
+// CIL[DOC-CONTEXT module="hooks" layer="frontend" related_files=".framework/src/hooks/useApi.ts"]
+// CIL[DOC-CONTRACT inputs="generic type parameters" outputs="onSuccess, onError, onSettled" errors="" side_effects="none"]
+// CIL[DOC-MICRO logic_summary="Describes the structure of the UseMutationOptions data object" notable_decisions="Uses generics to remain flexible across concrete API payloads"]
+// CIL[DOC-CONFIDENCE pass="second" score="0.90" flags="none"]
+// CIL[DOC-STABILITY stability="stable"]
 interface UseMutationOptions<T, P> {
   onSuccess?: (data: T) => void
   onError?: (error: string) => void
   onSettled?: () => void
 }
-// CIL[END chunk_id="useapi_usemutationoptions_1783740744"]
-// CIL[BEGIN chunk_id="useapi_usemutationreturn_1783740744" type="interface" identity="UseMutationReturn" parent="none"]
-// CIL[DOC-MACRO purpose="Define return structure for mutation hook"]
-// CIL[DOC-RESPONSIBILITY responsibility="Shape the public API surface for mutation operations"]
-// CIL[DOC-CONTEXT module="useApi" layer="frontend-hook" related_files="[]"]
-// CIL[DOC-CONTRACT inputs="none" outputs="mutation return interface" errors="none" side_effects="Type definition"]
-// CIL[DOC-MICRO logic_summary="Returns mutation state, mutate function, and reset function" 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: none."]
-// CIL[DOC-VECTOR type="blast_radius" content="Direct callers: 0. Total affected: 0."]
-// CIL[DOC-VECTOR type="configuration" content="No configuration dependencies."]
-// CIL[DOC-VECTOR type="constraint" content="No test paths identified."]
+// CIL[DOC-VECTOR type="context" content="purpose='Type definition for UseMutationOptions'; No verified external callers; imports: none"]
+// 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/useApi.ts:UseMutationOptions:interface"]
+
+// CIL[BEGIN stable_id="~/.framework/src/hooks/useApi.ts:UseMutationReturn:interface" type="interface" identity="UseMutationReturn" parent="~/.framework/src/hooks/useApi.ts"]
+// CIL[DOC-MACRO purpose="Type definition for UseMutationReturn"]
+// CIL[DOC-RESPONSIBILITY responsibility="Define the fields and shape of the UseMutationReturn interface"]
+// CIL[DOC-CONTEXT module="hooks" layer="frontend" related_files=".framework/src/hooks/useApi.ts"]
+// CIL[DOC-CONTRACT inputs="generic type parameters" outputs="data, loading, error, mutate, reset" errors="" side_effects="none"]
+// CIL[DOC-MICRO logic_summary="Describes the structure of the UseMutationReturn data object" notable_decisions="Provides a mutate trigger and reset for optimistic UIs"]
+// CIL[DOC-CONFIDENCE pass="second" score="0.90" flags="none"]
+// CIL[DOC-STABILITY stability="stable"]
 interface UseMutationReturn<T, P> {
   data: T | null
   loading: boolean
@@ -503,21 +509,22 @@ interface UseMutationReturn<T, P> {
   mutate: (params: P) => Promise<T>
   reset: () => void
 }
-// CIL[END chunk_id="useapi_usemutationreturn_1783740744"]
-// CIL[BEGIN chunk_id="useapi_usemutation_1783740744" type="function" identity="useMutation" parent="none"]
-// CIL[DOC-MACRO purpose="Write-operation hook for create, update, and delete operations"]
-// CIL[DOC-RESPONSIBILITY responsibility="Manage mutation state and lifecycle callbacks"]
-// CIL[DOC-CONTEXT module="useApi" layer="frontend-hook" related_files="[]"]
-// CIL[DOC-CONTRACT inputs="none" outputs="UseMutationReturn" errors="throws mutation errors" side_effects="React state, callbacks"]
-// CIL[DOC-MICRO logic_summary="Wraps async write operations with loading state and lifecycle callbacks" 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: none."]
-// CIL[DOC-VECTOR type="blast_radius" content="Direct callers: 0. Total affected: 0."]
-// CIL[DOC-VECTOR type="configuration" content="No configuration dependencies."]
-// CIL[DOC-VECTOR type="constraint" content="No test paths identified."]
+// CIL[DOC-VECTOR type="context" content="purpose='Type definition for UseMutationReturn'; No verified external callers; imports: none"]
+// 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/useApi.ts:UseMutationReturn:interface"]
+
+// CIL[BEGIN stable_id="~/.framework/src/hooks/useApi.ts:useMutation:hook" type="hook" identity="useMutation" parent="~/.framework/src/hooks/useApi.ts"]
+// CIL[DOC-MACRO purpose="React hook for mutation operations"]
+// CIL[DOC-RESPONSIBILITY responsibility="Manage async state and lifecycle for useMutation"]
+// CIL[DOC-CONTEXT module="hooks" layer="frontend" related_files=".framework/src/hooks/useApi.ts"]
+// CIL[DOC-CONTRACT inputs="mutationFunction(params: P) => Promise<T> and UseMutationOptions<T, P>" outputs="UseMutationReturn<T, P> with data, loading, error, mutate, reset" errors="Throws mutation error after setting state.error" side_effects="Updates React state and calls onSuccess/onError/onSettled callbacks"]
+// CIL[DOC-MICRO logic_summary="Encapsulates a mutation request and reset lifecycle" notable_decisions="Calls onSettled in a finally block to allow cleanup after success or failure"]
+// CIL[DOC-CONFIDENCE pass="second" score="0.90" flags="none"]
+// CIL[DOC-STABILITY stability="stable"]
 export function useMutation<T, P = void>(
   mutationFunction: (params: P) => Promise<T>,
   options: UseMutationOptions<T, P> = {}
@@ -572,4 +579,10 @@ export function useMutation<T, P = void>(
     reset
   }
 }
-// CIL[END chunk_id="useapi_usemutation_1783740744"]
+// CIL[DOC-VECTOR type="context" content="purpose='React hook for mutation operations'; No verified external callers; imports: none"]
+// 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/useApi.ts:useMutation:hook"]

package/.framework/src/hooks/useAppPath.ts

@@ -1,35 +1,31 @@
+// CIL[BEGIN stable_id="~/.framework/src/hooks/useAppPath.ts:module_header:module_header" type="module_header" identity="module_header" parent="~/.framework/src/hooks/useAppPath.ts"]
+// CIL[DOC-AUDIENCE audience="internal"]
+// CIL[DOC-CONTEXT module="useAppPath" layer="hooks" related_files=".framework/src/contexts/AppContext.tsx"]
+// CIL[DOC-CONTRACT inputs="" outputs="" errors="" side_effects=""]
+// CIL[DOC-CONFIDENCE pass="second" score="0.90" flags="none"]
+// CIL[DOC-MACRO purpose="import the current-app context hook dependency"]
+// CIL[DOC-MICRO logic_summary="imports useCurrentApp from AppContext" notable_decisions=""]
+// CIL[DOC-RESPONSIBILITY responsibility="provide the app context dependency used by useAppPath"]
+// CIL[DOC-STABILITY stable]
+
 
-// CIL[BEGIN chunk_id="useapppath_module_header_1783740744" type="module_header" identity="imports" parent="none"]
-// CIL[DOC-MACRO purpose="Import app context hook for route prefix access"]
-// CIL[DOC-RESPONSIBILITY responsibility="Provide access to current app configuration"]
-// CIL[DOC-CONTEXT module="useAppPath" layer="frontend-hook" related_files="[\"custom/apps/cortex/pages/operations/OperationsDashboard.tsx\",\".framework/migrations/015_simplify_apps_table.sql\",\"custom/apps/portal/pages/ContentPage.tsx\",\".framework/functions/_shared/principal.ts\",\"\\\"]"]
-// CIL[DOC-CONTRACT inputs="none" outputs="useCurrentApp hook" errors="none" side_effects="Module imports"]
-// CIL[DOC-MICRO logic_summary="Imports useCurrentApp hook from AppContext for app-specific routing" 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/cortex/pages/operations/OperationsDashboard.tsx, .framework/migrations/015_simplify_apps_table.sql, custom/apps/portal/pages/ContentPage.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"]
 import { useCurrentApp } from '../contexts/AppContext'
-// CIL[END chunk_id="useapppath_module_header_1783740744"]
-// CIL[BEGIN chunk_id="useapppath_useapppath_1783740744" type="function" identity="useAppPath" parent="none"]
-// CIL[DOC-MACRO purpose="Generate app-specific path helper with route prefix handling"]
-// CIL[DOC-RESPONSIBILITY responsibility="Manage route prefix logic for app-relative paths"]
-// CIL[DOC-CONTEXT module="useAppPath" layer="frontend-hook" related_files="[\".framework/src/pages/admin/RolesPage.tsx\",\".framework/functions/_shared/schema-utils.ts\",\".framework/src/pages/admin/TypeDetailPage.tsx\",\"custom/apps/cortex/functions/custom_cil-embeddings.ts\",\".framework/src/components/ui/dialog.tsx\",\"\\\"]"]
-// CIL[DOC-CONTRACT inputs="none" outputs="path helper function" errors="none" side_effects="React hook dependency"]
-// CIL[DOC-MICRO logic_summary="Creates path function that prepends app route_prefix to root-relative paths" 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: 7. Direct calls: 0. Related files: .framework/src/pages/admin/RolesPage.tsx, .framework/functions/_shared/schema-utils.ts, .framework/src/pages/admin/TypeDetailPage.tsx, custom/apps/cortex/functions/custom_cil-embeddings.ts, .framework/src/components/ui/dialog.tsx, \."]
-// CIL[DOC-VECTOR type="blast_radius" content="Direct callers: 7. Total affected: 7."]
-// 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='import the current-app context hook dependency'; No verified external callers; imports: .framework/src/contexts/AppContext.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/useAppPath.ts:module_header:module_header"]
+
+// CIL[BEGIN stable_id="~/.framework/src/hooks/useAppPath.ts:useAppPath:hook" type="hook" identity="useAppPath" parent="~/.framework/src/hooks/useAppPath.ts"]
+// CIL[DOC-CONTEXT module="useAppPath" layer="hooks" related_files=".framework/src/contexts/AppContext.tsx,.framework/src/hooks/useAppPath.ts"]
+// CIL[DOC-CONTRACT inputs="path: string" outputs="string: prefixed and normalized path" errors="none" side_effects="none"]
+// CIL[DOC-CONFIDENCE pass="second" score="0.90" flags="none"]
+// CIL[DOC-MACRO purpose="return a path prefix function that applies the current app route prefix"]
+// CIL[DOC-MICRO logic_summary="strips trailing slash from app.route_prefix; special-cases root '/'; otherwise ensures leading slash and concatenates" notable_decisions="treats '/' as special root path; only prefixes when a non-root route_prefix exists"]
+// CIL[DOC-RESPONSIBILITY responsibility="produce an application-prefixed, slash-normalized path string"]
+// CIL[DOC-STABILITY stable]
 export function useAppPath(): (path: string) => string {
   const app = useCurrentApp()
 
@@ -44,4 +40,10 @@ export function useAppPath(): (path: string) => string {
     return `${prefix}${normalized}`
   }
 }
-// CIL[END chunk_id="useapppath_useapppath_1783740744"]
+// CIL[DOC-VECTOR type="context" content="purpose='return a path prefix function that applies the current app route prefix'; No verified external callers; imports: .framework/src/contexts/AppContext.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/useAppPath.ts:useAppPath:hook"]