spine-framework 0.3.145 → 0.4.0

package/.framework/src/components/kb/KBArticleList.tsx

@@ -1,3 +1,13 @@
+// CIL[BEGIN stable_id="~/.framework/src/components/kb/KBArticleList.tsx:module_header:module_header"]
+// CIL[DOC-MACRO purpose="Defines imports and dependencies for the KB article list UI."]
+// CIL[DOC-RESPONSIBILITY responsibility="Provide React, utility, and UI component imports for KBArticleList."]
+// CIL[DOC-CONTEXT module="kb" layer="components" related_files=".framework/src/components/ui/badge.tsx,.framework/src/components/ui/button.tsx,.framework/src/components/ui/input.tsx,.framework/src/components/ui/skeleton.tsx,.framework/src/lib/api.ts,.framework/src/lib/utils.ts"]
+// CIL[DOC-CONTRACT inputs="none" outputs="none" errors="none" side_effects="none"]
+// CIL[DOC-MICRO logic_summary="Import block for hooks, API, utilities, and UI primitives." notable_decisions="[]"]
+// CIL[DOC-CONFIDENCE pass="second" score="0.90" flags="none"]
+// CIL[DOC-STABILITY stability="stable"]
+// CIL[DOC-AUDIENCE audience="developers"]
+
 import { Fragment, useCallback, useEffect, useMemo, useRef, useState } from 'react'
 import { apiFetch } from '../../lib/api'
 import { formatDateTime } from '../../lib/utils'
@@ -8,6 +18,24 @@ import { Badge } from '../ui/badge'
 import { Skeleton } from '../ui/skeleton'
 import { Plus, Search, Edit, BookOpen, GripVertical, X } from 'lucide-react'
 
+
+// CIL[DOC-VECTOR type="context" content="purpose='Defines imports and dependencies for the KB article list UI.'; No verified external callers; imports: .framework/src/lib/api.ts,.framework/src/lib/utils.ts,.framework/src/components/ui/button.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/components/kb/KBArticleList.tsx:module_header:module_header"]
+
+
+// CIL[BEGIN stable_id="~/.framework/src/components/kb/KBArticleList.tsx:KBArticleListProps:interface"]
+// CIL[DOC-MACRO purpose="Defines the props accepted by the KBArticleList component."]
+// CIL[DOC-RESPONSIBILITY responsibility="Contract between parent and KBArticleList."]
+// CIL[DOC-CONTEXT module="kb" layer="components" related_files=".framework/src/components/kb/KBArticleList.tsx,.framework/src/components/ui/badge.tsx,.framework/src/components/ui/button.tsx,.framework/src/components/ui/input.tsx,.framework/src/components/ui/skeleton.tsx,.framework/src/lib/api.ts,.framework/src/lib/utils.ts"]
+// CIL[DOC-CONTRACT inputs="none" outputs="KBArticleListProps interface" errors="none" side_effects="none"]
+// CIL[DOC-MICRO logic_summary="Lists optional and required props for the component." notable_decisions="[]"]
+// CIL[DOC-CONFIDENCE pass="second" score="0.90" flags="none"]
+// CIL[DOC-STABILITY stability="stable"]
 export interface KBArticleListProps {
   typeSlugs: string[]
   typeName?: string
@@ -15,7 +43,23 @@ export interface KBArticleListProps {
   onNew?: () => void
   onEdit?: (record: KBRecord) => void
 }
-
+// CIL[DOC-VECTOR type="context" content="purpose='Defines the props accepted by the KBArticleList component.'; No verified external callers; imports: .framework/src/lib/api.ts,.framework/src/lib/utils.ts,.framework/src/components/ui/button.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/components/kb/KBArticleList.tsx:KBArticleListProps:interface"]
+
+
+// CIL[BEGIN stable_id="~/.framework/src/components/kb/KBArticleList.tsx:KBRecord:interface"]
+// CIL[DOC-MACRO purpose="Defines the shape of a knowledge base record."]
+// CIL[DOC-RESPONSIBILITY responsibility="Data model for KB articles."]
+// CIL[DOC-CONTEXT module="kb" layer="components" related_files=".framework/src/components/kb/KBArticleList.tsx,.framework/src/components/ui/badge.tsx,.framework/src/components/ui/button.tsx,.framework/src/components/ui/input.tsx,.framework/src/components/ui/skeleton.tsx,.framework/src/lib/api.ts,.framework/src/lib/utils.ts"]
+// CIL[DOC-CONTRACT inputs="none" outputs="KBRecord interface" errors="none" side_effects="none"]
+// CIL[DOC-MICRO logic_summary="Defines KBRecord fields including id, title, status, and data." notable_decisions="[]"]
+// CIL[DOC-CONFIDENCE pass="second" score="0.90" flags="none"]
+// CIL[DOC-STABILITY stability="stable"]
 interface KBRecord {
   id: string
   title: string
@@ -27,27 +71,127 @@ interface KBRecord {
   data: Record<string, any>
   [key: string]: any
 }
-
+// CIL[DOC-VECTOR type="context" content="purpose='Defines the shape of a knowledge base record.'; No verified external callers; imports: .framework/src/lib/api.ts,.framework/src/lib/utils.ts,.framework/src/components/ui/button.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/components/kb/KBArticleList.tsx:KBRecord:interface"]
+
+
+// CIL[BEGIN stable_id="~/.framework/src/components/kb/KBArticleList.tsx:TreeNode:interface"]
+// CIL[DOC-MACRO purpose="Defines a tree node that extends KBRecord with children."]
+// CIL[DOC-RESPONSIBILITY responsibility="Recursive tree structure contract."]
+// CIL[DOC-CONTEXT module="kb" layer="components" related_files=".framework/src/components/kb/KBArticleList.tsx,.framework/src/components/ui/badge.tsx,.framework/src/components/ui/button.tsx,.framework/src/components/ui/input.tsx,.framework/src/components/ui/skeleton.tsx,.framework/src/lib/api.ts,.framework/src/lib/utils.ts"]
+// CIL[DOC-CONTRACT inputs="none" outputs="TreeNode interface" errors="none" side_effects="none"]
+// CIL[DOC-MICRO logic_summary="Extends KBRecord with a children array." notable_decisions="[]"]
+// CIL[DOC-CONFIDENCE pass="second" score="0.90" flags="none"]
+// CIL[DOC-STABILITY stability="stable"]
 interface TreeNode extends KBRecord {
   children: TreeNode[]
 }
-
+// CIL[DOC-VECTOR type="context" content="purpose='Defines a tree node that extends KBRecord with children.'; No verified external callers; imports: .framework/src/lib/api.ts,.framework/src/lib/utils.ts,.framework/src/components/ui/button.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/components/kb/KBArticleList.tsx:TreeNode:interface"]
+
+
+// CIL[BEGIN stable_id="~/.framework/src/components/kb/KBArticleList.tsx:isNullId:function"]
+// CIL[DOC-MACRO purpose="Tests whether a value is a null, undefined, or empty id."]
+// CIL[DOC-RESPONSIBILITY responsibility="Predicate for missing id values."]
+// CIL[DOC-CONTEXT module="kb" layer="components" related_files=".framework/src/components/kb/KBArticleList.tsx,.framework/src/components/ui/badge.tsx,.framework/src/components/ui/button.tsx,.framework/src/components/ui/input.tsx,.framework/src/components/ui/skeleton.tsx,.framework/src/lib/api.ts,.framework/src/lib/utils.ts"]
+// CIL[DOC-CONTRACT inputs="a: string | null | undefined" outputs="boolean (type predicate a is null | undefined)" errors="none" side_effects="none"]
+// CIL[DOC-MICRO logic_summary="Returns true for null, undefined, or empty string." notable_decisions="[]"]
+// CIL[DOC-CONFIDENCE pass="second" score="0.90" flags="none"]
+// CIL[DOC-STABILITY stability="stable"]
 function isNullId(a: string | null | undefined): a is null | undefined {
   return a === null || a === undefined || a === ''
 }
-
+// CIL[DOC-VECTOR type="context" content="purpose='Tests whether a value is a null, undefined, or empty id.'; No verified external callers; imports: .framework/src/lib/api.ts,.framework/src/lib/utils.ts,.framework/src/components/ui/button.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/components/kb/KBArticleList.tsx:isNullId:function"]
+
+
+// CIL[BEGIN stable_id="~/.framework/src/components/kb/KBArticleList.tsx:sameId:function"]
+// CIL[DOC-MACRO purpose="Compares two id values for equality, treating nullish as equal."]
+// CIL[DOC-RESPONSIBILITY responsibility="Determine id equality for parent and record comparisons."]
+// CIL[DOC-CONTEXT module="kb" layer="components" related_files=".framework/src/components/kb/KBArticleList.tsx,.framework/src/components/ui/badge.tsx,.framework/src/components/ui/button.tsx,.framework/src/components/ui/input.tsx,.framework/src/components/ui/skeleton.tsx,.framework/src/lib/api.ts,.framework/src/lib/utils.ts"]
+// CIL[DOC-CONTRACT inputs="a, b: string | null | undefined" outputs="boolean" errors="none" side_effects="none"]
+// CIL[DOC-MICRO logic_summary="Returns true if values are equal or both nullish." notable_decisions="[]"]
+// CIL[DOC-CONFIDENCE pass="second" score="0.90" flags="none"]
+// CIL[DOC-STABILITY stability="stable"]
 function sameId(a: string | null | undefined, b: string | null | undefined): boolean {
   return a === b || (isNullId(a) && isNullId(b))
 }
-
+// CIL[DOC-VECTOR type="context" content="purpose='Compares two id values for equality, treating nullish as equal.'; No verified external callers; imports: .framework/src/lib/api.ts,.framework/src/lib/utils.ts,.framework/src/components/ui/button.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/components/kb/KBArticleList.tsx:sameId:function"]
+
+
+// CIL[BEGIN stable_id="~/.framework/src/components/kb/KBArticleList.tsx:sameParent:function"]
+// CIL[DOC-MACRO purpose="Checks whether a record's parent_id matches the given parent."]
+// CIL[DOC-RESPONSIBILITY responsibility="Parent equality predicate for tree grouping."]
+// CIL[DOC-CONTEXT module="kb" layer="components" related_files=".framework/src/components/kb/KBArticleList.tsx,.framework/src/components/ui/badge.tsx,.framework/src/components/ui/button.tsx,.framework/src/components/ui/input.tsx,.framework/src/components/ui/skeleton.tsx,.framework/src/lib/api.ts,.framework/src/lib/utils.ts"]
+// CIL[DOC-CONTRACT inputs="record: KBRecord, parentId: string | undefined" outputs="boolean" errors="none" side_effects="none"]
+// CIL[DOC-MICRO logic_summary="Compares record.data.parent_id to parentId using sameId." notable_decisions="[]"]
+// CIL[DOC-CONFIDENCE pass="second" score="0.90" flags="none"]
+// CIL[DOC-STABILITY stability="stable"]
 function sameParent(record: KBRecord, parentId: string | undefined): boolean {
   return sameId(record.data?.parent_id as string | undefined, parentId)
 }
-
+// CIL[DOC-VECTOR type="context" content="purpose='Checks whether a record's parent_id matches the given parent.'; No verified external callers; imports: .framework/src/lib/api.ts,.framework/src/lib/utils.ts,.framework/src/components/ui/button.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/components/kb/KBArticleList.tsx:sameParent:function"]
+
+
+// CIL[BEGIN stable_id="~/.framework/src/components/kb/KBArticleList.tsx:sortByOrder:function"]
+// CIL[DOC-MACRO purpose="Sorts two KB records by their data.order value."]
+// CIL[DOC-RESPONSIBILITY responsibility="Order comparison for tree siblings."]
+// CIL[DOC-CONTEXT module="kb" layer="components" related_files=".framework/src/components/kb/KBArticleList.tsx,.framework/src/components/ui/badge.tsx,.framework/src/components/ui/button.tsx,.framework/src/components/ui/input.tsx,.framework/src/components/ui/skeleton.tsx,.framework/src/lib/api.ts,.framework/src/lib/utils.ts"]
+// CIL[DOC-CONTRACT inputs="a: KBRecord, b: KBRecord" outputs="number" errors="none" side_effects="none"]
+// CIL[DOC-MICRO logic_summary="Subtracts b order from a order, defaulting to MAX_SAFE_INTEGER." notable_decisions="[]"]
+// CIL[DOC-CONFIDENCE pass="second" score="0.90" flags="none"]
+// CIL[DOC-STABILITY stability="stable"]
 function sortByOrder(a: KBRecord, b: KBRecord): number {
   return (a.data?.order ?? Number.MAX_SAFE_INTEGER) - (b.data?.order ?? Number.MAX_SAFE_INTEGER)
 }
-
+// CIL[DOC-VECTOR type="context" content="purpose='Sorts two KB records by their data.order value.'; No verified external callers; imports: .framework/src/lib/api.ts,.framework/src/lib/utils.ts,.framework/src/components/ui/button.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/components/kb/KBArticleList.tsx:sortByOrder:function"]
+
+// CIL[BEGIN stable_id="~/.framework/src/components/kb/KBArticleList.tsx:KBArticleList:component"]
+// CIL[DOC-MACRO purpose="Renders a searchable, filterable, drag-and-drop knowledge base article list."]
+// CIL[DOC-RESPONSIBILITY responsibility="Display KB articles as a tree or flat list, support search, status/type filters, and reordering via drag-and-drop."]
+// CIL[DOC-CONTEXT module="kb" layer="components" related_files=".framework/src/components/kb/KBArticleList.tsx,.framework/src/components/ui/badge.tsx,.framework/src/components/ui/button.tsx,.framework/src/components/ui/input.tsx,.framework/src/components/ui/skeleton.tsx,.framework/src/lib/api.ts,.framework/src/lib/utils.ts"]
+// CIL[DOC-CONTRACT inputs="typeSlugs: string[], typeName?: string, onSelect?: (record: KBRecord) => void, onNew?: () => void, onEdit?: (record: KBRecord) => void" outputs="JSX" errors="Network or permission errors" side_effects="Fetches data from API, updates state, PATCHes records on drop."]
+// CIL[DOC-MICRO logic_summary="Loads record types, fetches article trees, handles search, builds filtered tree, renders list, and applies drag-and-drop reordering." notable_decisions="[]"]
+// CIL[DOC-CONFIDENCE pass="second" score="0.90" flags="none"]
+// CIL[DOC-STABILITY stability="stable"]
+// CIL[DOC-NOTE type="param" content="typeSlugs: string[] - allowed knowledge base type slugs"]
+// CIL[DOC-NOTE type="param" content="typeName?: string - display name for the knowledge base"]
+// CIL[DOC-NOTE type="param" content="onSelect?: (record: KBRecord) => void - callback when an article is selected"]
+// CIL[DOC-NOTE type="param" content="onNew?: () => void - callback to create a new article"]
+// CIL[DOC-NOTE type="param" content="onEdit?: (record: KBRecord) => void - callback to edit an article"
 export function KBArticleList({ typeSlugs, typeName, onSelect, onNew, onEdit }: KBArticleListProps) {
   const [typeRecords, setTypeRecords] = useState<any[]>([])
   const [articles, setArticles] = useState<KBRecord[]>([])
@@ -60,14 +204,25 @@ export function KBArticleList({ typeSlugs, typeName, onSelect, onNew, onEdit }:
   const [typeFilter, setTypeFilter] = useState<string>('all')
   const [dragging, setDragging] = useState<string | null>(null)
 
+
+
+
   const typeById = useMemo(() => {
     const map: Record<string, any> = {}
     typeRecords.forEach((t) => { map[t.id] = t })
     return map
   }, [typeRecords])
 
+
+
+
+
   const typeSlugsSet = useMemo(() => new Set(typeSlugs), [typeSlugs])
 
+
+
+
+
   const statusOptions = useMemo(() => {
     const opts = new Set<string>()
     typeRecords.forEach((t) => {
@@ -77,22 +232,36 @@ export function KBArticleList({ typeSlugs, typeName, onSelect, onNew, onEdit }:
     return ['all', ...Array.from(opts)]
   }, [typeRecords])
 
+
+
+
   const statusLabel = (s: string) => s === 'all' ? 'All' : (s?.charAt(0).toUpperCase() + s?.slice(1))
 
   useEffect(() => {
+
+
+
     let cancelled = false
+
     setLoading(true)
     apiFetch('/api/types?action=list')
       .then((r) => r.json())
       .then((j) => {
         if (cancelled) return
+
+
+
         const found = (j.data || []).filter((t: any) => typeSlugsSet.has(t.slug))
+
         setTypeRecords(found)
       })
       .catch(() => setTypeRecords([]))
     return () => { cancelled = true }
   }, [typeSlugsSet])
 
+
+
+
   const loadTree = useCallback(async () => {
     if (typeRecords.length === 0) return
     setLoading(true)
@@ -107,6 +276,17 @@ export function KBArticleList({ typeSlugs, typeName, onSelect, onNew, onEdit }:
         const record = records[0]
         return record?.data?.trees || {}
       }
+
+
+
+
+
+
+
+
+
+
+
       const [globalTrees, accountTrees] = await Promise.all([
         loadCache('KB Article List - Global'),
         loadCache('KB Article List - Account'),
@@ -125,11 +305,17 @@ export function KBArticleList({ typeSlugs, typeName, onSelect, onNew, onEdit }:
     }
   }, [typeRecords, typeSlugs, typeById])
 
+
+
+
+
   const handleSearch = useCallback(async (query: string) => {
     if (typeRecords.length === 0 || query.trim().length < 2) {
       setSearchResultIds(null)
       return
     }
+
+
     setSearching(true)
     setError(null)
     try {
@@ -158,12 +344,17 @@ export function KBArticleList({ typeSlugs, typeName, onSelect, onNew, onEdit }:
     }
   }, [typeRecords, typeSlugs])
 
+
   useEffect(() => {
     loadTree()
   }, [loadTree])
 
+
+
+
   const hasActiveSearch = searchResultIds !== null
 
+
   const { visibleArticles, roots, byId } = useMemo(() => {
     let out = articles
     if (statusFilter !== 'all') out = out.filter((a) => a.status === statusFilter)
@@ -182,6 +373,10 @@ export function KBArticleList({ typeSlugs, typeName, onSelect, onNew, onEdit }:
           ancestorSet.add(parentId)
           current = fullById.get(parentId)
         }
+
+
+
+
       }
       out = out.filter((a) => ancestorSet.has(a.id))
     }
@@ -209,11 +404,17 @@ export function KBArticleList({ typeSlugs, typeName, onSelect, onNew, onEdit }:
     return { visibleArticles: out, roots: roots.sort(sortByOrder), byId }
   }, [articles, statusFilter, typeFilter, searchResultIds])
 
+
+
+
   const isTreeMode = useMemo(
     () => statusFilter === 'all' && typeFilter === 'all',
     [statusFilter, typeFilter]
   )
 
+
+
+
   const handleDrop = async (itemId: string, targetParentId: string | undefined, insertIndex: number) => {
     const item = articles.find((a) => a.id === itemId)
     if (!item) return
@@ -231,6 +432,8 @@ export function KBArticleList({ typeSlugs, typeName, onSelect, onNew, onEdit }:
       if (originalIndex !== -1 && insertIndex > originalIndex) {
         effectiveIndex = insertIndex - 1
       }
+
+
     }
 
     const targetChildren = articles
@@ -239,7 +442,7 @@ export function KBArticleList({ typeSlugs, typeName, onSelect, onNew, onEdit }:
     const newGroup = [...targetChildren]
     newGroup.splice(effectiveIndex, 0, item)
 
-    const updates: { id: string; type_slug: string; data: any }[] = []
+    const updates: { id: string; type_slug?: string; data: any }[] = []
 
     newGroup.forEach((a, order) => {
       const nextData = { ...a.data, order }
@@ -250,7 +453,7 @@ export function KBArticleList({ typeSlugs, typeName, onSelect, onNew, onEdit }:
       if (a.data?.order !== order || parentChanged) {
         updates.push({
           id: a.id,
-          type_slug: a.type_slug || typeById[a.type_id]?.slug || 'kb-spine-public',
+          type_slug: a.type_slug || typeById[a.type_id]?.slug || undefined,
           data: nextData,
         })
       }
@@ -264,7 +467,7 @@ export function KBArticleList({ typeSlugs, typeName, onSelect, onNew, onEdit }:
         if (a.data?.order !== order) {
           updates.push({
             id: a.id,
-            type_slug: a.type_slug || typeById[a.type_id]?.slug || 'kb-spine-public',
+            type_slug: a.type_slug || typeById[a.type_id]?.slug || undefined,
             data: { ...a.data, order },
           })
         }
@@ -289,10 +492,15 @@ export function KBArticleList({ typeSlugs, typeName, onSelect, onNew, onEdit }:
     }
   }
 
+
+
+
   const DropIndicator = () => (
     <div className="h-0.5 bg-primary rounded-full my-1" />
   )
 
+
+
   function getDropIndex(e: React.DragEvent, container: HTMLElement | null): number {
     if (!container) return 0
     const itemEls = Array.from(container.children).filter((c) => c.getAttribute('data-item') === 'true')
@@ -304,9 +512,13 @@ export function KBArticleList({ typeSlugs, typeName, onSelect, onNew, onEdit }:
       const centerY = rect.top + rect.height / 2 - containerRect.top
       if (mouseY < centerY) return i
     }
+
     return itemEls.length
   }
 
+
+
+
   function SortableDropZone({
     parentId,
     nodes,
@@ -340,6 +552,7 @@ export function KBArticleList({ typeSlugs, typeName, onSelect, onNew, onEdit }:
           if (!e.relatedTarget || !listRef.current?.contains(e.relatedTarget as Node)) {
             setOver(true)
           }
+
         }}
         onDragLeave={(e) => {
           e.preventDefault()
@@ -359,8 +572,16 @@ export function KBArticleList({ typeSlugs, typeName, onSelect, onNew, onEdit }:
           e.preventDefault()
           e.stopPropagation()
           setOver(false)
+
+
+
           const id = e.dataTransfer.getData('text/plain')
+
+
+
+
           const index = computeIndex(e)
+
           setInsertIndex(null)
           if (id) handleDrop(id, parentId, index)
         }}
@@ -389,7 +610,11 @@ export function KBArticleList({ typeSlugs, typeName, onSelect, onNew, onEdit }:
               onDrop={(e) => {
                 e.preventDefault()
                 e.stopPropagation()
+
+
+
                 const id = e.dataTransfer.getData('text/plain')
+
                 if (id) handleDrop(id, node.id, node.children.length)
               }}
               className={cn(
@@ -427,6 +652,14 @@ export function KBArticleList({ typeSlugs, typeName, onSelect, onNew, onEdit }:
     )
   }
 
+
+
+
+
+
+
+
+
   const renderFlatRow = (record: KBRecord) => (
     <div
       key={record.id}
@@ -555,3 +788,11 @@ export function KBArticleList({ typeSlugs, typeName, onSelect, onNew, onEdit }:
     </div>
   )
 }
+// CIL[DOC-VECTOR type="context" content="purpose='Renders a searchable, filterable, drag-and-drop knowledge base article list.'; No verified external callers; imports: .framework/src/lib/api.ts,.framework/src/lib/utils.ts,.framework/src/components/ui/button.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/components/kb/KBArticleList.tsx:KBArticleList:component"]
+

package/.framework/src/components/layout/AppShell.tsx

@@ -1,23 +1,16 @@
-
-
-
-// CIL[BEGIN chunk_id="appshell_moduleheader_1783929861" type="module_header" identity="imports" parent="none"]
-// CIL[DOC-MACRO purpose="Import React, router, and UI components for app shell layout"]
-// CIL[DOC-RESPONSIBILITY responsibility="Provide dependencies for AppShell component"]
-// CIL[DOC-CONTEXT module="src/components/layout/AppShell" layer="frontend-component" related_files="[\"custom/apps/cortex/pages/operations/OperationsDashboard.tsx\",\"custom/apps/portal/pages/ContentPage.tsx\",\".framework/src/components/ui/dialog.tsx\",\".framework/src/pages/admin/TypeDetailPage.tsx\",\"custom/apps/cortex/functions/custom_cil-embeddings.ts\",\"\\\"]"]
-// CIL[DOC-CONTRACT inputs="none" outputs="React, Link, Sidebar components, Separator, Breadcrumb components" errors="none" side_effects="none"]
-// CIL[DOC-MICRO logic_summary="Imports React, router Link, shadcn sidebar, separator and breadcrumb components" notable_decisions="[]"]
-// CIL[DOC-CONFIDENCE pass="second" score="0.95" flags="none"]
+// CIL[BEGIN stable_id="~/.framework/src/components/layout/AppShell.tsx:module_header:module_header" type="module_header" identity="module_header" parent="~/.framework/src/components/layout/AppShell.tsx"]
+// CIL[DOC-MACRO purpose="AppShell layout component module entry point"]
+// CIL[DOC-RESPONSIBILITY responsibility="Provide shared application shell imports and component"]
+// CIL[DOC-CONTEXT module="AppShell" layer="component" related_files=".framework/src/components/ui/breadcrumb.tsx,.framework/src/components/ui/separator.tsx,.framework/src/components/ui/sidebar.tsx"]
+// CIL[DOC-CONTRACT inputs="none" outputs="none" errors="none" side_effects="none"]
+// CIL[DOC-MICRO logic_summary="Module header with React and UI imports for the AppShell layout component" notable_decisions="[]"]
+// CIL[DOC-CONFIDENCE pass="second" score="0.90" flags="none"]
 // CIL[DOC-STABILITY stability="stable"]
-// CIL[DOC-AUDIENCE audience="developer"]
-// CIL[DOC-VECTOR type="context" content="Layer: frontend-component. Direct callers: 0. Direct calls: 0. Related files: custom/apps/cortex/pages/operations/OperationsDashboard.tsx, custom/apps/portal/pages/ContentPage.tsx, .framework/src/components/ui/dialog.tsx, .framework/src/pages/admin/TypeDetailPage.tsx, custom/apps/cortex/functions/custom_cil-embeddings.ts, \."]
-// CIL[DOC-VECTOR type="blast_radius" content="Direct callers: 0. Total affected: 0."]
-// CIL[DOC-VECTOR type="configuration" content="No configuration dependencies."]
-// CIL[DOC-VECTOR type="constraint" content="No test paths identified."]
-// CIL[DOC-VECTOR type="implementation_pattern" content="" status="pending_human_input"]
-// CIL[DOC-VECTOR type="user_journey" content="" status="pending_human_input"]
+// CIL[DOC-AUDIENCE audience="system-ui"]
+
 import * as React from "react"
 import { Link } from 'react-router-dom'
+import { cn } from "../../lib/utils"
 import { SidebarProvider, SidebarInset, SidebarTrigger } from "../ui/sidebar"
 import { Separator } from "../ui/separator"
 import {
@@ -28,49 +21,56 @@ import {
   BreadcrumbPage,
   BreadcrumbSeparator,
 } from "../ui/breadcrumb"
-// CIL[END chunk_id="appshell_moduleheader_1783929861"]
-// CIL[BEGIN chunk_id="appshell_appshellprops_1783929861" type="interface" identity="AppShellProps" parent="none"]
-// CIL[DOC-MACRO purpose="Define props interface for AppShell component with sidebar and navigation"]
-// CIL[DOC-RESPONSIBILITY responsibility="Specify AppShell component contract for professional layout"]
-// CIL[DOC-CONTEXT module="src/components/layout/AppShell" layer="frontend-component" related_files="[\"custom/apps/portal/pages/ContentPage.tsx\",\".framework/functions/_shared/schema-utils.ts\",\".framework/src/components/ui/dialog.tsx\",\".framework/functions/_shared/principal.ts\",\"custom/apps/cortex/pages/operations/OperationsDashboard.tsx\",\"\\\"]"]
-// CIL[DOC-CONTRACT inputs="none" outputs="AppShellProps interface" errors="none" side_effects="none"]
-// CIL[DOC-MICRO logic_summary="Interface with sidebar, children, breadcrumbs, and optional header actions" 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-component. Direct callers: 0. Direct calls: 0. Related files: custom/apps/portal/pages/ContentPage.tsx, .framework/functions/_shared/schema-utils.ts, .framework/src/components/ui/dialog.tsx, .framework/functions/_shared/principal.ts, 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='AppShell layout component module entry point'; No verified external callers; imports: .framework/src/components/ui/sidebar.tsx,.framework/src/components/ui/separator.tsx,.framework/src/components/ui/breadcrumb.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/components/layout/AppShell.tsx:module_header:module_header"]
+
+// CIL[BEGIN stable_id="~/.framework/src/components/layout/AppShell.tsx:appshellprops:interface" type="interface" identity="AppShellProps" parent="~/.framework/src/components/layout/AppShell.tsx:module_header:module_header"]
+// CIL[DOC-MACRO purpose="Props interface for the AppShell layout component"]
+// CIL[DOC-RESPONSIBILITY responsibility="Declare the inputs accepted by AppShell"]
+// CIL[DOC-CONTEXT module="AppShell" layer="component" related_files=".framework/src/components/layout/AppShell.tsx,.framework/src/components/ui/breadcrumb.tsx,.framework/src/components/ui/separator.tsx,.framework/src/components/ui/sidebar.tsx"]
+// CIL[DOC-CONTRACT inputs="none" outputs="AppShellProps interface type" errors="none" side_effects="none"]
+// CIL[DOC-MICRO logic_summary="Defines AppShell props including sidebar, children, breadcrumbs, headerActions, banner and mainClassName" notable_decisions="mainClassName overrides the default main padding (p-4 md:p-6 lg:p-8) — apps whose pages self-pad pass a zero/tighter value to close the gap above the page header"]
+// CIL[DOC-CONFIDENCE pass="second" score="0.90" flags="none"]
+// CIL[DOC-STABILITY stability="stable"]
+
 interface AppShellProps {
   sidebar: React.ReactNode
   children: React.ReactNode
   breadcrumbs?: { title: string; url?: string }[]
   headerActions?: React.ReactNode
   banner?: React.ReactNode
+  mainClassName?: string
 }
-// CIL[END chunk_id="appshell_appshellprops_1783929861"]
-// CIL[BEGIN chunk_id="appshell_appshell_1783929861" type="function" identity="AppShell" parent="none"]
-// CIL[DOC-MACRO purpose="Render professional app shell with sidebar, header breadcrumbs and main content"]
-// CIL[DOC-RESPONSIBILITY responsibility="Provide complete app layout with navigation and content areas"]
-// CIL[DOC-CONTEXT module="src/components/layout/AppShell" layer="frontend-component" related_files="[\"custom/apps/portal/pages/ContentPage.tsx\",\"custom/apps/cortex/pages/operations/OperationsDashboard.tsx\",\"custom/apps/cortex/functions/custom_cil-embeddings.ts\",\".framework/src/pages/admin/RolesPage.tsx\",\"\\\"]"]
-// CIL[DOC-CONTRACT inputs="none" outputs="JSX app shell layout" errors="none" side_effects="Manages sidebar state and provides navigation structure"]
-// CIL[DOC-MICRO logic_summary="SidebarProvider with collapsible sidebar, header with breadcrumbs, and main content area" 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-component. Direct callers: 0. Direct calls: 0. Related files: custom/apps/portal/pages/ContentPage.tsx, custom/apps/cortex/pages/operations/OperationsDashboard.tsx, custom/apps/cortex/functions/custom_cil-embeddings.ts, .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='Props interface for the AppShell layout component'; No verified external callers; imports: .framework/src/components/ui/sidebar.tsx,.framework/src/components/ui/separator.tsx,.framework/src/components/ui/breadcrumb.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/components/layout/AppShell.tsx:appshellprops:interface"]
+
+// CIL[BEGIN stable_id="~/.framework/src/components/layout/AppShell.tsx:appshell:function" type="function" identity="AppShell" parent="~/.framework/src/components/layout/AppShell.tsx:module_header:module_header"]
+// CIL[DOC-MACRO purpose="Render the main application shell with sidebar, header and content area"]
+// CIL[DOC-RESPONSIBILITY responsibility="Compose sidebar, breadcrumbs, header actions, banner and children into the app layout"]
+// CIL[DOC-CONTEXT module="AppShell" layer="component" related_files=".framework/src/components/layout/AppShell.tsx,.framework/src/components/ui/breadcrumb.tsx,.framework/src/components/ui/separator.tsx,.framework/src/components/ui/sidebar.tsx"]
+// CIL[DOC-CONTRACT inputs="sidebar: React.ReactNode, children: React.ReactNode, breadcrumbs: { title: string; url?: string }[] | undefined, headerActions: React.ReactNode | undefined, banner: React.ReactNode | undefined, mainClassName: string | undefined" outputs="React tree" errors="none" side_effects="none"]
+// CIL[DOC-MICRO logic_summary="Wraps children in a sidebar-aware layout with optional breadcrumbs and header actions" notable_decisions="mainClassName replaces the default main padding (p-4 md:p-6 lg:p-8) entirely via cn() — pass an empty/tight value when pages self-pad to close the gap above the page header"]
+// CIL[DOC-CONFIDENCE pass="second" score="0.90" flags="none"]
+// CIL[DOC-STABILITY stability="stable"]
+
 export function AppShell({
   sidebar,
   children,
   breadcrumbs,
   headerActions,
   banner,
+  mainClassName,
 }: AppShellProps) {
   return (
     <SidebarProvider>
@@ -119,11 +119,17 @@ export function AppShell({
           )}
         </header>
 
-        <main className="flex-1 flex flex-col min-h-0 overflow-auto p-4 md:p-6 lg:p-8">
+        <main className={cn("flex-1 flex flex-col min-h-0 overflow-auto", mainClassName ?? "p-4 md:p-6 lg:p-8")}>
           {children}
         </main>
       </SidebarInset>
     </SidebarProvider>
   )
 }
-// CIL[END chunk_id="appshell_appshell_1783929861"]
+// CIL[DOC-VECTOR type="context" content="purpose='Render the main application shell with sidebar, header and content area'; No verified external callers; imports: .framework/src/components/ui/sidebar.tsx,.framework/src/components/ui/separator.tsx,.framework/src/components/ui/breadcrumb.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/components/layout/AppShell.tsx:appshell:function"]