@brainfish-ai/devdoc 0.1.22 → 0.1.23

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@brainfish-ai/devdoc",
-  "version": "0.1.22",
+  "version": "0.1.23",
   "description": "Documentation framework for developers. Write docs in MDX, preview locally, deploy to Brainfish.",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",

package/renderer/components/docs-viewer/index.tsx

@@ -7,7 +7,6 @@ import { DocsSidebar } from './sidebar'
 import { ApiPlayground } from './playground'
 import type { DebugContext } from './playground/response-viewer'
 import { RightSidebar } from './sidebar/right-sidebar'
-import { Introduction } from './content/introduction'
 import { RequestDetails } from './content/request-details'
 import { DocPage } from './content/doc-page'
 import { ChangelogPage } from './content/changelog-page'
@@ -241,6 +240,53 @@ function findRequestById(collection: BrainfishCollection, id: string): Brainfish
   return null
 }
 
+// Helper to get the first endpoint from collection
+function getFirstEndpoint(collection: BrainfishCollection): BrainfishRESTRequest | null {
+  // Check direct requests first
+  if (collection.requests.length > 0) {
+    return collection.requests[0]
+  }
+  
+  // Check folders recursively
+  for (const folder of collection.folders) {
+    const firstInFolder = getFirstEndpoint(folder)
+    if (firstInFolder) return firstInFolder
+  }
+  return null
+}
+
+// Helper to check if a doc group belongs to a specific tab
+// Group IDs are formatted as: group-{tab-id}-{group-name}
+function isGroupForTab(groupId: string, tabId: string): boolean {
+  // Check if the group ID starts with "group-{tabId}-"
+  const prefix = `group-${tabId}-`
+  return groupId.startsWith(prefix)
+}
+
+// Helper to check if a tab has doc groups (MDX pages)
+function hasDocGroupsForTab(
+  docGroups: BrainfishDocGroup[] | undefined, 
+  tabId: string
+): boolean {
+  if (!docGroups || docGroups.length === 0) return false
+  
+  // Check if any doc group belongs to this tab and has pages
+  return docGroups.some(g => isGroupForTab(g.id, tabId) && g.pages.length > 0)
+}
+
+// Helper to get the first page from doc groups for a tab
+function getFirstDocPageForTab(
+  docGroups: BrainfishDocGroup[] | undefined,
+  tabId: string
+): string | null {
+  if (!docGroups || docGroups.length === 0) return null
+  
+  const tabDocGroup = docGroups.find(g => isGroupForTab(g.id, tabId) && g.pages.length > 0)
+  
+  return tabDocGroup?.pages[0]?.slug || null
+}
+
+
 // API version
 interface ApiVersion {
   version: string
@@ -391,19 +437,21 @@ function DocsContent() {
   const navigateToHash = useCallback((collectionData: BrainfishCollection) => {
     const hash = window.location.hash.slice(1) // Remove #
 
-    console.log('[Docs] Navigating to hash:', hash)
-
     if (!hash) {
-      // No hash - show Introduction by default
-      setSelectedRequest(null)
+      // No hash - auto-select first endpoint
       setSelectedDocSection(null)
       setSelectedDocPage(null)
+      const firstEndpoint = getFirstEndpoint(collectionData)
+      if (firstEndpoint) {
+        setSelectedRequest(firstEndpoint)
+      } else {
+        setSelectedRequest(null)
+      }
       return
     }
 
     // Notes mode is handled by ModeContext, just clear API selection
     if (hash === 'notes' || hash.startsWith('notes/')) {
-      console.log('[Docs] Notes mode detected, clearing API selection')
       setSelectedRequest(null)
       setSelectedDocSection(null)
       setSelectedDocPage(null)
@@ -428,9 +476,7 @@ function DocsContent() {
     const actualId = id || (legacyType ? hash.replace(`${legacyType}/`, '') : null)
 
     if (actualType === 'endpoint' && actualId) {
-      console.log('[Docs] Looking for endpoint:', actualId)
       const request = findRequestById(collectionData, actualId)
-      console.log('[Docs] Found request:', request?.name || 'NOT FOUND')
       if (request) {
         setSelectedRequest(request)
         setSelectedDocSection(null)
@@ -598,18 +644,55 @@ function DocsContent() {
     // Reset mode to docs when switching tabs (exit sandbox/api-client mode)
     switchToDocs()
 
-    if (tabId === 'api-reference') {
-      // Switch to API Reference - clear doc page and show introduction (no endpoint selected)
-      setSelectedDocPage(null)
-      setSelectedRequest(null)
-      setSelectedDocSection(null)
-      updateUrlHash('', tabId)
-    } else if (tabId === 'changelog') {
+    // Find the tab config to check its type
+    const tabConfig = collection?.navigationTabs?.find(t => t.id === tabId)
+    const isApiTab = tabConfig?.type === 'openapi' || tabConfig?.type === 'graphql' || tabId === 'api-reference'
+
+    if (tabId === 'changelog') {
       // Switch to Changelog tab
       setSelectedDocPage(null)
       setSelectedRequest(null)
       setSelectedDocSection(null)
       updateUrlHash('', tabId)
+    } else if (isApiTab) {
+      // API Reference or GraphQL tab
+      setSelectedDocSection(null)
+      
+      // Check if there are doc groups for this tab (MDX pages)
+      const hasGroups = hasDocGroupsForTab(collection?.docGroups, tabId)
+      
+      if (hasGroups) {
+        // Has doc groups - select the first page from groups
+        const firstPage = getFirstDocPageForTab(collection?.docGroups, tabId)
+        if (firstPage) {
+          setSelectedDocPage(firstPage)
+          setSelectedRequest(null)
+          updateUrlHash(`page/${firstPage}`, tabId)
+          switchToDocs()
+        } else {
+          // No pages in groups - auto-select first endpoint
+          setSelectedDocPage(null)
+          const firstEndpoint = collection ? getFirstEndpoint(collection) : null
+          if (firstEndpoint) {
+            setSelectedRequest(firstEndpoint)
+            updateUrlHash(`endpoint/${firstEndpoint.id}`, tabId)
+          } else {
+            setSelectedRequest(null)
+            updateUrlHash('', tabId)
+          }
+        }
+      } else {
+        // No doc groups - auto-select first endpoint
+        setSelectedDocPage(null)
+        const firstEndpoint = collection ? getFirstEndpoint(collection) : null
+        if (firstEndpoint) {
+          setSelectedRequest(firstEndpoint)
+          updateUrlHash(`endpoint/${firstEndpoint.id}`, tabId)
+        } else {
+          setSelectedRequest(null)
+          updateUrlHash('', tabId)
+        }
+      }
     } else {
       // Switch to a doc group tab - find and select the first page in that tab
       setSelectedRequest(null)
@@ -617,10 +700,7 @@ function DocsContent() {
 
       // Find the first doc group for this tab and select its first page
       if (collection?.docGroups) {
-        const tabDocGroup = collection.docGroups.find(g => {
-          const groupTabPart = g.id.replace('group-', '').split('-')[0]
-          return groupTabPart === tabId
-        })
+        const tabDocGroup = collection.docGroups.find(g => isGroupForTab(g.id, tabId))
 
         if (tabDocGroup && tabDocGroup.pages.length > 0) {
           const firstPage = tabDocGroup.pages[0]
@@ -733,8 +813,6 @@ function DocsContent() {
     // Also update shortcut icon and apple-touch-icon
     updateFaviconLink('shortcut icon', faviconPath)
     updateFaviconLink('apple-touch-icon', faviconPath)
-    
-    console.log('[Docs] Set favicon to:', faviconPath)
   }, [collection?.docsFavicon])
 
   useEffect(() => {
@@ -761,16 +839,6 @@ function DocsContent() {
         }
 
         const data = await response.json()
-        
-        console.log('[Docs] Collection data:', JSON.stringify({
-          hasData: !!data,
-          name: data?.name,
-          requestsCount: data?.requests?.length || 0,
-          foldersCount: data?.folders?.length || 0,
-          apiVersions: data?.apiVersions?.length || 0,
-          selectedVersion: data?.selectedApiVersion,
-        }, null, 2))
-        
         setCollection(data)
         
         // Set initial API version if not already set
@@ -793,24 +861,60 @@ function DocsContent() {
             // Use setTimeout to ensure state is set before navigation
             setTimeout(() => {
               const hash = window.location.hash.slice(1)
-              console.log('[Docs] Initial hash:', hash)
 
               if (!hash) {
                 // No hash - set URL to initial tab
-                updateUrlHash('', initialTabId)
-                setSelectedRequest(null)
                 setSelectedDocSection(null)
 
-                if (initialTabId === 'api-reference') {
-                  // API Reference tab - show introduction
-                  setSelectedDocPage(null)
+                // Find the tab config to check its type
+                const tabConfig = data.navigationTabs?.find((t: NavigationTab) => t.id === initialTabId)
+                const isApiTab = tabConfig?.type === 'openapi' || tabConfig?.type === 'graphql' || initialTabId === 'api-reference'
+
+                if (isApiTab) {
+                  // API Reference or GraphQL tab
+                  setSelectedDocSection(null)
+                  
+                  // Check if there are doc groups for this tab (MDX pages)
+                  const hasGroups = hasDocGroupsForTab(data.docGroups, initialTabId)
+                  
+                  if (hasGroups) {
+                    // Has doc groups - select the first page from groups
+                    const firstPage = getFirstDocPageForTab(data.docGroups, initialTabId)
+                    if (firstPage) {
+                      setSelectedDocPage(firstPage)
+                      setSelectedRequest(null)
+                      updateUrlHash(`page/${firstPage}`, initialTabId)
+                    } else {
+                      // No pages in groups - auto-select first endpoint
+                      setSelectedDocPage(null)
+                      const firstEndpoint = getFirstEndpoint(data)
+                      if (firstEndpoint) {
+                        setSelectedRequest(firstEndpoint)
+                        updateUrlHash(`endpoint/${firstEndpoint.id}`, initialTabId)
+                      } else {
+                        setSelectedRequest(null)
+                        updateUrlHash('', initialTabId)
+                      }
+                    }
+                  } else {
+                    // No doc groups - auto-select first endpoint
+                    setSelectedDocPage(null)
+                    const firstEndpoint = getFirstEndpoint(data)
+                    if (firstEndpoint) {
+                      setSelectedRequest(firstEndpoint)
+                      updateUrlHash(`endpoint/${firstEndpoint.id}`, initialTabId)
+                    } else {
+                      setSelectedRequest(null)
+                      updateUrlHash('', initialTabId)
+                    }
+                  }
                   switchToDocs()
                 } else {
                   // Doc group tab - select first page
-                  const tabDocGroup = data.docGroups?.find((g: BrainfishDocGroup) => {
-                    const groupTabPart = g.id.replace('group-', '').split('-')[0]
-                    return groupTabPart === initialTabId
-                  })
+                  setSelectedRequest(null)
+                  const tabDocGroup = data.docGroups?.find((g: BrainfishDocGroup) => 
+                    isGroupForTab(g.id, initialTabId)
+                  )
 
                   if (tabDocGroup && tabDocGroup.pages.length > 0) {
                     const firstPage = tabDocGroup.pages[0]
@@ -819,12 +923,12 @@ function DocsContent() {
                     switchToDocs()
                   } else {
                     setSelectedDocPage(null)
+                    updateUrlHash('', initialTabId)
                     switchToDocs()
                   }
                 }
               } else if (hash === 'notes' || hash.startsWith('notes/')) {
                 // Notes mode - handled by ModeContext, just clear API selection
-                console.log('[Docs] Initial hash is notes mode')
                 setSelectedRequest(null)
                 setSelectedDocSection(null)
               } else {
@@ -846,14 +950,13 @@ function DocsContent() {
                 const actualId = isLegacyFormat ? parts.slice(1).join('/') : hashId
                 
                 if (actualType === 'endpoint' && actualId) {
-                  console.log('[Docs] Looking for endpoint on load:', actualId)
                   const request = findRequestById(data, actualId)
-                  console.log('[Docs] Found:', request?.name || 'NOT FOUND')
                   if (request) {
                     setSelectedRequest(request)
                     setSelectedDocSection(null)
                     setSelectedDocPage(null)
                     switchToDocs()
+                    return
                   } else {
                     setSelectedRequest(null)
                     setSelectedDocSection(null)
@@ -878,9 +981,49 @@ function DocsContent() {
                   }, 100)
                 } else if (hashTab && !hashType) {
                   // Just a tab, show its default content
-                  setSelectedRequest(null)
                   setSelectedDocSection(null)
-                  setSelectedDocPage(null)
+                  
+                  // Check if this is an API tab
+                  const tabConfig = data.navigationTabs?.find((t: NavigationTab) => t.id === hashTab)
+                  const isApiTab = tabConfig?.type === 'openapi' || tabConfig?.type === 'graphql' || hashTab === 'api-reference'
+                  
+                  if (isApiTab) {
+                    // Check if there are doc groups for this tab (MDX pages)
+                    const hasGroups = hasDocGroupsForTab(data.docGroups, hashTab)
+                    
+                    if (hasGroups) {
+                      // Has doc groups - select the first page from groups
+                      const firstPage = getFirstDocPageForTab(data.docGroups, hashTab)
+                      if (firstPage) {
+                        setSelectedDocPage(firstPage)
+                        setSelectedRequest(null)
+                        updateUrlHash(`page/${firstPage}`, hashTab)
+                      } else {
+                        // No pages in groups - auto-select first endpoint
+                        setSelectedDocPage(null)
+                        const firstEndpoint = getFirstEndpoint(data)
+                        if (firstEndpoint) {
+                          setSelectedRequest(firstEndpoint)
+                          updateUrlHash(`endpoint/${firstEndpoint.id}`, hashTab)
+                        } else {
+                          setSelectedRequest(null)
+                        }
+                      }
+                    } else {
+                      // No doc groups - auto-select first endpoint
+                      setSelectedDocPage(null)
+                      const firstEndpoint = getFirstEndpoint(data)
+                      if (firstEndpoint) {
+                        setSelectedRequest(firstEndpoint)
+                        updateUrlHash(`endpoint/${firstEndpoint.id}`, hashTab)
+                      } else {
+                        setSelectedRequest(null)
+                      }
+                    }
+                  } else {
+                    setSelectedDocPage(null)
+                    setSelectedRequest(null)
+                  }
                   switchToDocs()
                 }
               }
@@ -1170,17 +1313,13 @@ function DocsWithMode({
   // Find the active tab's config
   const activeTabConfig = collection.navigationTabs?.find(t => t.id === activeTab)
   const activeTabType = activeTabConfig?.type || 'docs'
-  // Use the tab name for page header
-  const activeTabTitle = activeTabConfig?.tab || 'Documentation'
 
   
   // Filter doc groups for sidebar based on active tab
   // Group IDs are like "group-guides-getting-started", tab IDs are like "guides"
-  const filteredDocGroups = collection.docGroups?.filter(g => {
-    // Extract the tab part from the group ID (e.g., "guides" from "group-guides-getting-started")
-    const groupTabPart = g.id.replace('group-', '').split('-')[0]
-    return groupTabPart === activeTab
-  }) || []
+  // Filter doc groups for sidebar based on active tab
+  // Group IDs are formatted as: group-{tab-id}-{group-name}
+  const filteredDocGroups = collection.docGroups?.filter(g => isGroupForTab(g.id, activeTab)) || []
   
   // Show endpoints in sidebar only when OpenAPI tab is active
   const showEndpoints = activeTabType === 'openapi'
@@ -1386,7 +1525,12 @@ function DocsWithMode({
                 ) : selectedDocPage ? (
                   <DocPage slug={selectedDocPage} />
                 ) : (
-                  <Introduction collection={collection} />
+                  <div className="flex-1 flex items-center justify-center bg-background">
+                    <div className="text-center text-muted-foreground">
+                      <Book className="h-12 w-12 mx-auto mb-3 opacity-40" />
+                      <p className="text-sm">Select an endpoint from the sidebar</p>
+                    </div>
+                  </div>
                 )}
               </div>
             </DocsNavigationProvider>

package/renderer/components/docs-viewer/sidebar/index.tsx

@@ -15,7 +15,6 @@ import { CollectionTree } from './collection-tree'
 import { SidebarSection } from './sidebar-section'
 import { SidebarItem, SlidingIndicatorProvider } from './sidebar-item'
 import { SidebarGroup } from './sidebar-group'
-import { extractMarkdownHeadings, type MarkdownHeading } from '@/lib/api-docs/utils'
 import { useMobile } from '@/lib/api-docs/mobile-context'
 import { cn } from '@/lib/utils'
 
@@ -84,92 +83,8 @@ export function DocsSidebar({
     }
   }
   
-  // Extract documentation headings from collection description
-  const docHeadings = useMemo(() => {
-    return collection.description 
-      ? extractMarkdownHeadings(collection.description)
-      : []
-  }, [collection.description])
-  
   // Get doc groups from collection
   const docGroups = collection.docGroups || []
-
-  const handleDocClick = (headingId: string) => {
-    handleDocClickWithClose(headingId)
-  }
-  
-  // Determine if Introduction should be highlighted
-  const isIntroductionSelected = !selectedRequest && !selectedDocSection && !selectedDocPage
-
-  // Check if a heading or any of its children is selected
-  const isHeadingSelected = (heading: MarkdownHeading): boolean => {
-    if (selectedDocSection === heading.id) return true
-    if (heading.children?.some(child => selectedDocSection === child.id)) return true
-    return false
-  }
-  
-  // Get the selected child heading ID for a heading group
-  const getSelectedChildHeading = (heading: MarkdownHeading): string | null => {
-    if (selectedDocSection === heading.id) return heading.id
-    const selected = heading.children?.find(child => selectedDocSection === child.id)
-    return selected?.id || null
-  }
-
-  // Render a documentation heading item (may have children)
-  const renderHeading = (heading: MarkdownHeading, index: number) => {
-    const hasChildren = heading.children && heading.children.length > 0
-    const isSelected = selectedDocSection === heading.id
-    
-    // If heading is "Introduction", handle it specially
-    if (heading.text === 'Introduction') {
-      return (
-        <SidebarItem
-          key={`${heading.id}-${index}`}
-          itemId={`heading-introduction`}
-          selected={isIntroductionSelected}
-          onClick={() => handleDocClick('introduction')}
-        >
-          Introduction
-        </SidebarItem>
-      )
-    }
-    
-    if (hasChildren) {
-      return (
-        <SidebarGroup
-          key={`${heading.id}-${index}`}
-          title={heading.text}
-          defaultOpen={isHeadingSelected(heading)}
-          selected={isSelected}
-          selectedChildSlug={getSelectedChildHeading(heading)}
-          onClick={() => handleDocClick(heading.id)}
-        >
-          {heading.children!.map((child, childIndex) => (
-            <SidebarItem
-              key={`${child.id}-${childIndex}`}
-              itemId={`heading-${child.id}`}
-              selected={selectedDocSection === child.id}
-              indent={1}
-              onClick={() => handleDocClick(child.id)}
-            >
-              {child.text}
-            </SidebarItem>
-          ))}
-        </SidebarGroup>
-      )
-    }
-    
-    return (
-      <SidebarItem
-        key={`${heading.id}-${index}`}
-        itemId={`heading-${heading.id}`}
-        selected={isSelected}
-        onClick={() => handleDocClick(heading.id)}
-      >
-        {heading.text}
-      </SidebarItem>
-    )
-  }
   
   // Check if any child in a group is selected
   const isChildSelected = (page: BrainfishDocPage): boolean => {
@@ -300,14 +215,7 @@ export function DocsSidebar({
 
         {/* Scrollable content with sliding indicator */}
         <SlidingIndicatorProvider className="docs-sidebar-content flex-1 overflow-y-auto overflow-x-hidden custom-scroll">
-          {/* Documentation Section (from description headings) - Only shown in API Reference tab */}
-          {activeTab === 'api-reference' && docHeadings.length > 0 && (
-            <SidebarSection title="Documentation">
-              {docHeadings.map((heading, index) => renderHeading(heading, index))}
-            </SidebarSection>
-          )}
-          
-          {/* Documentation Pages Section (from docs.json) */}
+          {/* Documentation Pages Section (from docs.json groups) */}
           {docGroups.length > 0 && (
             <>
               {docGroups.map((group, index) => (
@@ -315,7 +223,7 @@ export function DocsSidebar({
                   key={group.id} 
                   title={group.title}
                   icon={group.icon}
-                  className={index > 0 || (activeTab === 'api-reference' && docHeadings.length > 0) ? '' : ''}
+                  className={index > 0 ? '' : ''}
                 >
                   {group.pages.map(renderDocPage)}
                 </SidebarSection>
@@ -327,7 +235,7 @@ export function DocsSidebar({
           {(collection.folders.length > 0 || collection.requests.length > 0) && (
             <SidebarSection 
               title="Endpoints" 
-              className={((activeTab === 'api-reference' && docHeadings.length > 0) || docGroups.length > 0) ? 'border-t border-sidebar-border' : ''}
+              className={docGroups.length > 0 ? 'border-t border-sidebar-border' : ''}
             >
               <CollectionTree
                 collection={collection}

package/renderer/lib/api-docs/factories.ts

@@ -11,39 +11,61 @@ import type {
 } from './types'
 
 /**
- * Generates a unique ID for collections and requests
- * If a seed is provided, generates a deterministic hash-based ID
+ * Generates a URL-friendly slug from a string
+ * Converts to lowercase, replaces spaces and special chars with hyphens
  */
-function generateUniqueId(prefix: string, seed?: string): string {
-  if (seed) {
-    // Generate deterministic ID from seed using simple hash
-    let hash = 0
-    for (let i = 0; i < seed.length; i++) {
-      const char = seed.charCodeAt(i)
-      hash = ((hash << 5) - hash) + char
-      hash = hash & hash // Convert to 32bit integer
-    }
-    // Convert to positive number and base36
-    const hashStr = Math.abs(hash).toString(36)
-    return `${prefix}_${hashStr}`
+function slugify(str: string): string {
+  return str
+    .toLowerCase()
+    .replace(/[{}]/g, '') // Remove braces from path params
+    .replace(/[^a-z0-9]+/g, '-') // Replace non-alphanumeric with hyphens
+    .replace(/^-+|-+$/g, '') // Remove leading/trailing hyphens
+    .replace(/-+/g, '-') // Collapse multiple hyphens
+}
+
+/**
+ * Generates a human-readable, deterministic ID for requests
+ * Uses operationId if available, otherwise method + path
+ */
+function generateRequestId(method: string, path: string, operationId?: string): string {
+  if (operationId) {
+    // Use operationId directly (it's already unique per spec)
+    return slugify(operationId)
+  }
+  
+  // Generate from method + path: "get-users-id" for "GET /users/{id}"
+  const pathSlug = slugify(path)
+  return `${method.toLowerCase()}-${pathSlug}`
+}
+
+/**
+ * Generates a unique ID for collections
+ * If a seed is provided, generates a deterministic slug-based ID
+ */
+function generateCollectionId(name?: string): string {
+  if (name) {
+    return `coll-${slugify(name)}`
   }
-  return `${prefix}_${Date.now()}_${Math.random().toString(36).substr(2, 9)}`
+  return `coll_${Date.now()}_${Math.random().toString(36).substr(2, 9)}`
 }
 
 /**
  * Creates a BrainfishRESTRequest with defaults
- * If method and endpoint are provided, generates a deterministic ID
+ * Generates human-readable, deterministic IDs based on operationId or method+path
  */
 export function makeBrainfishRESTRequest(
-  request: Omit<BrainfishRESTRequest, 'id'>
+  request: Omit<BrainfishRESTRequest, 'id'> & { operationId?: string }
 ): BrainfishRESTRequest {
-  // Generate deterministic ID from method + endpoint
-  const idSeed = request.method && request.endpoint 
-    ? `${request.method}:${request.endpoint}` 
-    : undefined
+  // Extract path from endpoint (remove base URL)
+  const path = request.endpoint 
+    ? request.endpoint.replace(/^https?:\/\/[^/]+/, '') || '/'
+    : '/'
+  
+  // Generate human-readable ID
+  const id = generateRequestId(request.method || 'GET', path, request.operationId)
   
   return {
-    id: generateUniqueId('req', idSeed),
+    id,
     name: request.name || 'Untitled Request',
     description: request.description ?? null,
     method: request.method || 'GET',
@@ -65,11 +87,8 @@ export function makeBrainfishRESTRequest(
 export function makeBrainfishCollection(
   collection: Omit<BrainfishCollection, 'id'>
 ): BrainfishCollection {
-  // Generate deterministic ID from collection name
-  const idSeed = collection.name ? `collection:${collection.name}` : undefined
-  
   return {
-    id: generateUniqueId('coll', idSeed),
+    id: generateCollectionId(collection.name),
     name: collection.name || 'Untitled Collection',
     description: collection.description ?? null,
     folders: collection.folders || [],

package/renderer/lib/api-docs/parsers/graphql/parser.ts

@@ -238,7 +238,7 @@ function extractOperations(
   const fields = rootType.getFields()
   
   return Object.values(fields).map(field => ({
-    id: `${operationType}-${field.name}`,
+    id: `${operationType}-${field.name}`.toLowerCase(),
     name: field.name,
     description: field.description || null,
     operationType,

package/renderer/lib/api-docs/parsers/openapi/transformer.ts

@@ -178,6 +178,7 @@ function convertPathToBrainfishReqs(
         requestVariables,
         responses,
         tags: (info as any).tags ?? [],
+        operationId: (info as any).operationId ?? undefined,
       })
 
       return {

package/renderer/lib/docs/config/schema.ts

@@ -58,6 +58,16 @@ const openapiTabSchema = z.object({
   path: z.string().optional(),
   versions: z.array(openapiVersionSchema).optional(),
   spec: z.string().optional(),
+  groups: z.array(groupSchema).optional(), // Doc groups alongside API reference
+})
+
+const graphqlTabSchema = z.object({
+  tab: z.string(),
+  type: z.literal('graphql'),
+  path: z.string().optional(),
+  schema: z.string(), // GraphQL schema file path
+  endpoint: z.string().optional(), // GraphQL endpoint URL
+  groups: z.array(groupSchema).optional(), // Doc groups alongside API reference
 })
 
 const changelogTabSchema = z.object({
@@ -66,7 +76,7 @@ const changelogTabSchema = z.object({
   path: z.string().optional(),
 })
 
-const tabSchema = z.union([docsTabSchema, openapiTabSchema, changelogTabSchema])
+const tabSchema = z.union([docsTabSchema, openapiTabSchema, graphqlTabSchema, changelogTabSchema])
 
 const navigationSchema = z.object({
   tabs: z.array(tabSchema).optional(),

package/renderer/components/docs-viewer/content/introduction.tsx

@@ -1,21 +0,0 @@
-'use client'
-
-import { MarkdownRenderer } from '../shared/markdown-renderer'
-import type { BrainfishCollection } from '@/lib/api-docs/types'
-
-interface IntroductionProps {
-  collection: BrainfishCollection
-}
-
-export function Introduction({ collection }: IntroductionProps) {
-  return (
-    <div className="docs-introduction docs-content max-w-4xl mx-auto px-4 py-6 sm:px-8 sm:py-8">
-      <h1 className="docs-content-title text-2xl sm:text-3xl font-bold mb-4 sm:mb-6 text-foreground">{collection.name}</h1>
-      {collection.description && (
-        <div className="docs-prose prose prose-sm max-w-none prose-headings:text-foreground prose-p:text-muted-foreground prose-strong:text-foreground prose-code:text-foreground prose-pre:bg-muted prose-code:bg-muted prose-code:px-1 prose-code:py-0.5 prose-code:rounded prose-pre:overflow-x-auto prose-table:w-full prose-th:text-left prose-th:p-3 prose-th:bg-muted prose-td:p-3 prose-td:border-b prose-td:border-border">
-          <MarkdownRenderer content={collection.description} />
-        </div>
-      )}
-    </div>
-  )
-}