spine-framework 0.3.124 → 0.3.126

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

@@ -1,3 +1,21 @@
+
+
+
+// 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'
@@ -14,8 +32,8 @@ export interface AppRecord {
   source: string
   config: Record<string, any>
   nav_items: any[]
-  min_role?: string  // Deprecated: use required_roles instead
-  required_roles?: string[]  // New: array of roles that can access this app
+  min_role?: string
+  required_roles?: string[]
   is_active: boolean
   is_system: boolean
   route_prefix: string | null
@@ -30,12 +48,21 @@ interface UseAppsResult {
   error: string | null
   refetch: () => void
 }
-
-/**
- * Fetches active apps for the current account and filters by user roles.
- * Apps with renderer='none' or route_prefix=null are excluded from routing
- * but still returned for API-only consumers.
- */
+// 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="implementation_pattern" content="" status="pending_human_input"]
+// CIL[DOC-VECTOR type="user_journey" content="" status="pending_human_input"]
 export function useApps(): UseAppsResult {
   const { user } = useAuth()
   const [apps, setApps] = useState<AppRecord[]>([])
@@ -73,30 +100,22 @@ export function useApps(): UseAppsResult {
       const appMatchesDomain = (app: AppRecord): boolean => {
         const domain = environment === 'preview' ? app.preview_domain : app.prod_domain
         if (!domain) return true
-        // Accept both "hostname.com" and "https://hostname.com" formats
         const hostname = domain.includes('://') ? new URL(domain).hostname : domain.split(':')[0]
         return currentHost === hostname
       }
 
-      // Filter by user's roles: include app if user has any of the required_roles,
-      // or if app has no role restrictions
       const accessible = allApps.filter(app => {
         if (!app.is_active) return false
         if (!appMatchesDomain(app)) return false
         
-        // Support both new required_roles array and legacy min_role
         const requiredRoles = app.required_roles || (app.min_role ? [app.min_role] : [])
         
-        // No role restriction = accessible to all
         if (requiredRoles.length === 0) return true
         
-        // User has no roles = no access (unless no restriction)
         if (!user.roles || user.roles.length === 0) return false
         
-        // system_admin can access everything
         if (user.roles.includes('system_admin')) return true
         
-        // Check if user has any of the required roles
         return requiredRoles.some(role => user.roles!.includes(role))
       })
 
@@ -115,10 +134,21 @@ export function useApps(): UseAppsResult {
 
   return { apps, loading, error, refetch: fetchApps }
 }
-
-/**
- * Returns only routable apps (those with a route_prefix and renderer != 'none').
- */
+// 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="implementation_pattern" content="" status="pending_human_input"]
+// CIL[DOC-VECTOR type="user_journey" content="" status="pending_human_input"]
 export function useRoutableApps() {
   const result = useApps()
   return {
@@ -126,3 +156,4 @@ export function useRoutableApps() {
     apps: result.apps.filter(app => app.route_prefix != null && app.renderer !== 'none')
   }
 }
+// CIL[END chunk_id="useapps_useroutableapps_1783719596"]

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

@@ -1,43 +1,24 @@
-/**
- * @module src/hooks/useEntityList
- * @audience installer
- * @layer frontend-hook
- * @stability stable
- *
- * Schema-driven list data hook. Given an entity name and a minimal
- * `MinimalEntityListConfig`, fetches a paginated, filtered, and sorted list
- * from the API and exposes controls for filters, sort, and pagination.
- *
- * **How it works:**
- * 1. Builds query params from `entity`, `config.api`, filters, sort, and pagination
- * 2. Calls `apiFetch('/api/<endpoint>?action=list&...')` via `useApi`
- * 3. Re-fetches when `config` arrives (async schema load), or when filters change
- *    (which also resets page to 1)
- *
- * **Auth retry:** `useApi` re-executes on route navigation, which naturally
- * retries after the auth session hydrates on the next tick.
- *
- * @seeAlso src/hooks/useApi.ts (useApi — underlying fetch + abort primitive)
- * @seeAlso src/lib/api.ts (apiFetch)
- * @seeAlso src/components/runtime/DataListPage.tsx (primary consumer)
- * @seeAlso functions/admin-data.ts (API endpoint for list action)
- */
 
+
+// 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'
 
-// ─── TYPES ───────────────────────────────────────────────────────────────────
-
-/**
- * Minimal configuration shape consumed by `useEntityList`.
- *
- * @prop entity - Entity name (used as fallback endpoint, filter param)
- * @prop typeSlug - Optional type slug; appended as `type_slug` param if present
- * @prop api.endpoint - Netlify function base path (e.g. `'admin-data'`)
- * @prop api.listAction - Action string; defaults to `'list'`
- * @prop list.defaultSort - Initial sort field and direction
- */
 interface MinimalEntityListConfig {
   entity: string
   typeSlug?: string
@@ -50,19 +31,6 @@ interface MinimalEntityListConfig {
   }
 }
 
-/**
- * Return value of `useEntityList`.
- *
- * @prop data - Fetched records array (empty while loading or on error)
- * @prop loading - True while fetching
- * @prop error - Error message or null
- * @prop refetch - Re-execute the current query
- * @prop filters - Active filter values keyed by param name
- * @prop setFilters - Replace the active filters (resets page to 1)
- * @prop sort - Current sort field and direction
- * @prop setSort - Update sort (does not auto-reset page)
- * @prop pagination - page/setPage/pageSize/setPageSize/total controls
- */
 interface UseEntityListReturn {
   data: any[]
   loading: boolean
@@ -80,28 +48,21 @@ interface UseEntityListReturn {
     total: number
   }
 }
-
-// ─── HOOK ────────────────────────────────────────────────────────────────────
-
-/**
- * Fetches and manages a filtered, sorted, paginated entity list.
- *
- * @param entity - Entity name (e.g. `'accounts'`, `'items'`)
- * @param config - Schema-derived config; pass `null` while schema is loading
- *   (hook is a no-op until config is non-null)
- * @returns `UseEntityListReturn` — see type for full details
- *
- * @inputSpec config.api.endpoint: string — function name, e.g. `'admin-data'`
- * @inputSpec filters: values of `''`, `undefined`, or `'all'` are omitted from params
- * @outputSpec data: any[] — raw API response; shape depends on entity type
- * @sideEffects Network request via apiFetch; React state mutations
- * @calledBy DataListPage.tsx
- *
- * @example
- * ```tsx
- * const { data, loading, setFilters } = useEntityList('accounts', config)
- * ```
- */
+// 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="implementation_pattern" content="" status="pending_human_input"]
+// CIL[DOC-VECTOR type="user_journey" content="" status="pending_human_input"]
 export function useEntityList(
   entity: string,
   config: MinimalEntityListConfig | null
@@ -116,33 +77,27 @@ export function useEntityList(
     
     const params = new URLSearchParams()
     
-    // Support new endpoint-based API pattern
     const endpoint = config.api.endpoint || entity
     const action = config.api.listAction || 'list'
     params.append('action', action)
     
-    // Add entity parameter for unified admin-data endpoint
     if (config.api.endpoint) {
       params.append('entity', entity)
     }
     
-    // Add type_slug for schema-driven filtering if available
     if (config.typeSlug) {
       params.append('type_slug', config.typeSlug)
     }
     
-    // Add filters
     Object.entries(filters).forEach(([key, value]) => {
       if (value !== undefined && value !== '' && value !== 'all') {
         params.append(key, value.toString())
       }
     })
     
-    // Add sort
     params.append('sort_field', sort.field)
     params.append('sort_direction', sort.direction)
     
-    // Add pagination
     params.append('limit', pageSize.toString())
     params.append('offset', ((page - 1) * pageSize).toString())
     
@@ -160,12 +115,10 @@ export function useEntityList(
     immediate: true
   })
 
-  // Re-fetch when config arrives (schema was not ready on initial mount)
   useEffect(() => {
     if (config) execute()
   }, [config?.api.endpoint, config?.api.listAction, config?.typeSlug])
 
-  // Reset page when filters change
   useEffect(() => {
     setPage(1)
   }, [filters])
@@ -188,3 +141,4 @@ export function useEntityList(
     }
   }
 }
+// CIL[END chunk_id="useentitylist_useentitylist_1783719596"]

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

@@ -1,58 +1,29 @@
-/**
- * @module src/hooks/useEntityRecord
- * @audience installer
- * @layer frontend-hook
- * @stability stable
- *
- * Schema-driven single-record hook. Fetches a record by ID, exposes its
- * design schema, computes field-level read/write permissions for the
- * current principal, and provides save and delete mutations.
- *
- * **Field permission model:**
- * - `system_admin` role always gets `{ read: true, write: true }` on all fields
- * - Other principals: permissions are read from `design_schema.fields[n].permissions`
- *   as role arrays; defaults to `true` if absent
- *
- * **Save routing:**
- * - Fields marked `fieldDef.system = true` go to top-level record columns
- * - All other fields are nested under the `data` JSONB column
- *
- * **Delete:** sends a `DELETE` request with the configured `deleteAction`;
- *   hard vs. soft delete is determined by the API handler (`config.softDelete`
- *   signals intent to the handler).
- *
- * @seeAlso src/hooks/useApi.ts (useApi + useMutation primitives)
- * @seeAlso src/hooks/useSchemaRecord.ts (companion for schema-driven form data)
- * @seeAlso src/components/runtime/DataDetailPage.tsx (primary consumer)
- * @seeAlso functions/admin-data.ts (API endpoint handling get/update/delete)
- */
 
+
+// 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[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"]
 import { useCallback } from 'react'
 import { useApi, useMutation } from './useApi'
 import { apiFetch } from '../lib/api'
 import { useAuth } from '../contexts/AuthContext'
 
-// ─── TYPES ───────────────────────────────────────────────────────────────────
-
-/**
- * Per-field read/write permission map keyed by field name.
- * Computed from `design_schema.fields[n].permissions` and the current user's roles.
- */
 interface FieldPermissions {
   [key: string]: { read: boolean; write: boolean }
 }
 
-/**
- * Minimal entity configuration consumed by `useEntityRecord`.
- *
- * @prop entity - Entity table name
- * @prop typeSlug - Optional type slug for schema resolution
- * @prop icon - Icon identifier (used by detail page header)
- * @prop displayField - Field name used as the record title
- * @prop api.endpoint - Netlify function base path
- * @prop api.*Action - Action strings for get/create/update/delete
- * @prop softDelete - Hint for the API handler (true = set is_active=false)
- */
 interface MinimalEntityConfig {
   entity: string
   typeSlug?: string
@@ -68,19 +39,6 @@ interface MinimalEntityConfig {
   softDelete?: boolean
 }
 
-/**
- * Return value of `useEntityRecord`.
- *
- * @prop record - Fetched record or null
- * @prop schema - `design_schema` extracted from the record (or nested type)
- * @prop fieldPermissions - Per-field `{ read, write }` map for the current user
- * @prop loading - True while fetching
- * @prop error - Error message or null
- * @prop refetch - Re-fetch the record
- * @prop save - Trigger the save mutation (create or update based on `id`)
- * @prop delete - Trigger the delete mutation
- * @prop saving / deleting - Mutation loading flags
- */
 interface UseEntityRecordReturn {
   record: any
   schema: any
@@ -93,30 +51,23 @@ interface UseEntityRecordReturn {
   saving: boolean
   deleting: boolean
 }
-
-// ─── HOOK ────────────────────────────────────────────────────────────────────
-
-/**
- * Fetches, saves, and deletes a single entity record with schema and
- * field-permission awareness.
- *
- * @param entity - Entity table name (e.g. `'accounts'`)
- * @param id - Record UUID; pass `undefined` to enter create mode
- * @param config - Schema-derived config; pass `null` while loading
- * @returns `UseEntityRecordReturn` — see type for full details
- *
- * @inputSpec id: string | undefined — undefined triggers create mode (no GET)
- * @outputSpec schema: DesignSchema | {} — empty object if no design_schema found
- * @outputSpec fieldPermissions: FieldPermissions — computed per-render
- * @sideEffects Network requests via apiFetch; React state mutations
- * @calledBy DataDetailPage.tsx
- *
- * @example
- * ```tsx
- * const { record, save, saving, fieldPermissions } =
- *   useEntityRecord('accounts', id, config)
- * ```
- */
+// 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="implementation_pattern" content="" status="pending_human_input"]
+// CIL[DOC-VECTOR type="user_journey" content="" status="pending_human_input"]
 export function useEntityRecord(
   entity: string,
   id: string | undefined,
@@ -124,14 +75,12 @@ export function useEntityRecord(
 ): UseEntityRecordReturn {
   const { user } = useAuth()
   
-  // Get API configuration with safe defaults
   const endpoint = config?.api?.endpoint || entity
   const getAction = config?.api?.getAction || 'get'
   const createAction = config?.api?.createAction || 'create'
   const updateAction = config?.api?.updateAction || 'update'
   const deleteAction = config?.api?.deleteAction || 'delete'
   
-  // Fetch record - always call useCallback to maintain hook order
   const fetchRecord = useCallback(async () => {
     if (!id) return null
     
@@ -154,17 +103,13 @@ export function useEntityRecord(
     immediate: !!id
   })
   
-  // Extract schema from record (accounts have it at root level, items/types have it nested)
   const schema = record?.design_schema || record?.type?.design_schema || {}
   
-  // Calculate field permissions from record's schema
   const calculatePermissions = (): FieldPermissions => {
     const permissions: FieldPermissions = {}
     
-    // System admin gets full access
     const isSystemAdmin = user?.roles?.includes('system_admin')
     
-    // Get all fields from record's schema
     const recordSchema = record?.design_schema?.fields
     if (!recordSchema) return permissions
     
@@ -172,7 +117,6 @@ export function useEntityRecord(
       if (isSystemAdmin) {
         permissions[fieldName] = { read: true, write: true }
       } else {
-        // Check field-level permissions from schema
         const fieldPerms = fieldSchema?.permissions || {}
         
         const canRead = fieldPerms.read?.some((role: string) => 
@@ -192,10 +136,8 @@ export function useEntityRecord(
   
   const fieldPermissions = calculatePermissions()
   
-  // Save mutation
   const saveMutation = useMutation(
     async (data: any) => {
-      // Separate system fields from custom fields
       const systemData: Record<string, any> = {}
       const customData: Record<string, any> = {}
       
@@ -208,14 +150,12 @@ export function useEntityRecord(
         }
       })
       
-      // Combine system fields with custom data in data field
       const saveData = {
         ...systemData,
         data: Object.keys(customData).length > 0 ? customData : undefined
       }
       
       if (id) {
-        // Update
         const params = new URLSearchParams()
         params.append('action', updateAction)
         params.append('entity', entity)
@@ -236,8 +176,7 @@ export function useEntityRecord(
         
         return response.json()
       } else {
-        // Create
-        const createData = { entity, ...saveData }
+        const createData = { entity, type_slug: config?.typeSlug, ...saveData }
         
         const params = new URLSearchParams()
         params.append('action', createAction)
@@ -268,7 +207,6 @@ export function useEntityRecord(
     }
   )
   
-  // Delete mutation
   const deleteMutation = useMutation(
     async () => {
       if (!id) throw new Error('Cannot delete: no ID provided')
@@ -306,3 +244,4 @@ export function useEntityRecord(
     deleting: deleteMutation.loading
   }
 }
+// CIL[END chunk_id="useentityrecord_useentityrecord_1783719596"]