@flamingo-stack/openframe-frontend-core 0.0.481 → 0.0.482

package/src/components/navigation/.app-header.md

@@ -1,58 +1,65 @@
-<!-- source-hash: 898258d76810df35b3a9175ed9b09824 -->
-Responsive application header component for the OpenFrame platform, providing navigation controls, search, organization filtering, notifications, and user account management across mobile and desktop breakpoints.
+<!-- source-hash: 569a7a0949370aa9107f6c577d74779f -->
+Responsive application header component for the OpenFrame shell, providing navigation controls, search, organization filtering, notifications, time tracking, Mingo AI access, and user account management across desktop and mobile breakpoints.
 
 ## Key Components
 
-| Export | Type | Description |
-|--------|------|-------------|
-| `AppHeader` | `React.memo` component | Main header component with full prop-driven configuration |
-| `AppHeaderProps` | Interface | Full prop contract for the header |
-| `NotificationsHeaderButton` | Internal component | Bell icon button with unread badge, integrates with `NotificationsContext` |
+### `AppHeader`
 
-## Props Overview
+The primary exported component — a memoized `<header>` element that composes all header controls based on feature flags passed via props.
+
+**`AppHeaderProps`** — full prop surface:
 
 | Prop | Type | Description |
-|------|------|-------------|
-| `isMobileMenuOpen` | `boolean` | Required; controls burger menu icon state |
-| `onToggleMobileMenu` | `() => void` | Callback to toggle the mobile sidebar |
-| `disabled` | `boolean` | Dims all controls except the mobile burger toggle |
-| `showSearch` | `boolean` | Renders global search (desktop) or search button (mobile) |
-| `showOrganizations` | `boolean` | Renders org filter dropdown (large screens only) |
-| `showNotifications` | `boolean` | Renders notification bell with unread badge |
-| `showUser` | `boolean` | Renders user avatar + dropdown (desktop only) |
+|---|---|---|
+| `showSearch` | `boolean` | Renders global search (desktop) or search icon (mobile) |
+| `showOrganizations` | `boolean` | Renders org filter dropdown (desktop only) |
+| `showNotifications` | `boolean` | Renders notifications bell with unread badge |
+| `showTimeTracker` | `boolean` | Renders time-tracker button; requires `<TimeTrackerProvider>` |
+| `showMingoAI` | `boolean` | Renders Mingo AI launcher button |
+| `isMingoAIActive` | `boolean` | Pressed state for the Mingo AI drawer toggle |
+| `showUser` | `boolean` | Renders user avatar with profile/logout dropdown (desktop only) |
+| `isMobileMenuOpen` | `boolean` | Controls burger icon state |
+| `disabled` | `boolean` | Dims and disables all controls except the mobile burger toggle |
+
+### `NotificationsHeaderButton` (internal)
+
+Reads live state from `useOptionalNotifications()` context; falls back to `fallbackUnreadCount` when no provider is present. Toggles between a bell icon (with unread dot) and a close icon when the panel is open.
 
 ## Usage Example
 
 ```typescript
-import { AppHeader } from './app-header'
+import { AppHeader } from '@openframe-oss-lib/ui'
 
-export function Shell() {
-  const [mobileOpen, setMobileOpen] = React.useState(false)
+function Shell() {
+  const [mobileMenuOpen, setMobileMenuOpen] = React.useState(false)
+  const [mingoOpen, setMingoOpen] = React.useState(false)
 
   return (
     <AppHeader
-      isMobileMenuOpen={mobileOpen}
-      onToggleMobileMenu={() => setMobileOpen(prev => !prev)}
       showSearch
-      onSearch={(query) => console.log(query)}
       showOrganizations
       organizations={[{ id: 'org-1', name: 'Acme Corp' }]}
       selectedOrgId="org-1"
-      onOrgChange={(id) => console.log(id)}
+      onOrgChange={(id) => console.log('org changed', id)}
       showNotifications
       unreadCount={3}
+      showTimeTracker
+      showMingoAI
+      onMingoAI={() => setMingoOpen((v) => !v)}
+      isMingoAIActive={mingoOpen}
       showUser
-      userName="Jane Doe"
+      userName="Jane Smith"
       userEmail="jane@acme.com"
+      userAvatarUrl={null}
       onProfile={() => router.push('/profile')}
       onLogout={() => signOut()}
+      isMobileMenuOpen={mobileMenuOpen}
+      onToggleMobileMenu={() => setMobileMenuOpen((v) => !v)}
     />
   )
 }
 ```
 
-## Behavior Notes
+> **Note:** `showTimeTracker` requires wrapping your app in `<TimeTrackerProvider>`. `showMingoAI` pairs with an `AppLayoutDrawer` positioned at `z-[103]`; the user dropdown renders at `z-[104]` to stay above it.
 
-- **Responsive layout:** Mobile renders a burger icon + logo; desktop shows the full search bar and org filter
-- **Disabled state:** Setting `disabled={true}` applies `pointer-events-none opacity-50` to all controls except the mobile menu toggle
-- **Notifications:** Prefers live unread count from `NotificationsContext` when available, falls back to the `unreadCount` prop; switches between `BellIcon` and `BellRingingIcon` based on count
+**Source:** [`app-header.tsx`](https://github.com/flamingo-stack/openframe-oss-lib/blob/main/app-header.tsx)

package/src/components/navigation/.app-layout-context.md

@@ -0,0 +1,48 @@
+<!-- source-hash: 68a6be14b0f426e8391409d08ace02ec -->
+Provides React context primitives for `AppLayout`'s drawer portal targeting and multi-panel open/close coordination, intentionally isolated to prevent circular module imports.
+
+## Key Components
+
+| Export | Type | Description |
+|---|---|---|
+| `AppLayoutDrawerContainerContext` | `Context<HTMLElement \| null>` | Reference to the `<main>` wrapper element used as the portal mount target for `AppLayoutDrawer` |
+| `useAppLayoutDrawerContainer` | Hook | Consumes `AppLayoutDrawerContainerContext`; returns `null` outside of `AppLayout` |
+| `AppLayoutDrawerHandle` | Interface | Shape each panel must expose — a single `close()` method |
+| `AppLayoutDrawerCoordination` | Interface | Coordination contract: `notifyDrawerDidOpen` and `registerDrawer` |
+| `AppLayoutDrawerCoordinationContext` | `Context<AppLayoutDrawerCoordination \| null>` | Shared bus enforcing the one-panel-at-a-time rule |
+| `useAppLayoutDrawerCoordination` | Hook | Consumes `AppLayoutDrawerCoordinationContext`; returns `null` outside of `AppLayout` |
+
+## Usage Example
+
+```typescript
+// Inside a drawer panel (e.g. AppLayoutDrawer or NotificationDrawer)
+import {
+  useAppLayoutDrawerContainer,
+  useAppLayoutDrawerCoordination,
+  type AppLayoutDrawerHandle,
+} from './app-layout-context'
+
+function MyDrawer() {
+  const container = useAppLayoutDrawerContainer()
+  const coordination = useAppLayoutDrawerCoordination()
+
+  const handle: AppLayoutDrawerHandle = { close: () => setOpen(false) }
+
+  useEffect(() => {
+    if (!coordination) return
+    // Register so other panels can close this one
+    return coordination.registerDrawer(handle)
+  }, [coordination])
+
+  function open() {
+    // Closes the burger menu + every other registered panel
+    coordination?.notifyDrawerDidOpen(handle)
+    setOpen(true)
+  }
+
+  if (!container) return null
+  return createPortal(<div>Drawer content</div>, container)
+}
+```
+
+> **Why a separate module?** `AppLayout` renders `AppLayoutDrawer`, `NotificationDrawer`, and `TimeTrackerHeaderButton`. If those panels imported `AppLayout` to access these contexts, a module cycle would form. Keeping contexts here breaks the cycle.

package/src/components/navigation/.app-layout-drawer.md

@@ -0,0 +1,56 @@
+<!-- source-hash: 1cd276668c638c6cf3605fa41bf21802 -->
+Renders a drawer panel anchored inside the `AppLayout` main content area (rather than the viewport), keeping the header and sidebar visible and interactive while the drawer is open.
+
+## Key Components
+
+| Export | Type | Description |
+|---|---|---|
+| `AppLayoutDrawerRoot` | Component | Root wrapper; manages open state, coordination with other layout panels, and `DialogPrimitive.Root` in non-modal mode |
+| `AppLayoutDrawerTrigger` | Component | Re-export of `DialogPrimitive.Trigger` |
+| `AppLayoutDrawerClose` | Component | Re-export of `DialogPrimitive.Close` |
+| `AppLayoutDrawerResizeHandle` | Component | Drag handle for resizing the drawer panel via pointer events |
+| `useContainedResizableSize` | Hook | Manages panel size state with localStorage persistence and container-aware clamping |
+| `appLayoutDrawerVariants` | CVA | Tailwind variants for the outer positioning wrapper (`side`, `flush`) |
+| `appLayoutDrawerPanelVariants` | CVA | Tailwind variants for the inner panel surface (`side`, `flush`) |
+| `DrawerOpenContext` | Context | Exposes the current open state to descendant components for animation control |
+| `PERSIST_CLOSED_HOLD` | Constant | Tailwind class that pins `fill-mode: forwards` on exit animations when `forceMount` is used |
+
+Re-exported from `ui/drawer`: `DrawerBody`, `DrawerDescription`, `DrawerFooter`, `DrawerHeader`, `DrawerTitle`.
+
+## Usage Example
+
+```typescript
+import {
+  AppLayoutDrawerRoot,
+  AppLayoutDrawerTrigger,
+  AppLayoutDrawerClose,
+} from "./app-layout-drawer"
+import { DrawerHeader, DrawerTitle, DrawerBody, DrawerFooter } from "../ui/drawer"
+
+export function ExamplePanel() {
+  const [open, setOpen] = React.useState(false)
+
+  return (
+    <AppLayoutDrawerRoot open={open} onOpenChange={setOpen}>
+      <AppLayoutDrawerTrigger asChild>
+        <button>Open details</button>
+      </AppLayoutDrawerTrigger>
+
+      {/* Content is portalled into the AppLayout container, not document.body */}
+      <AppLayoutDrawerContent side="right" resizable storageKey="details-panel-width">
+        <DrawerHeader>
+          <DrawerTitle>Details</DrawerTitle>
+        </DrawerHeader>
+        <DrawerBody>Panel content here</DrawerBody>
+        <DrawerFooter>
+          <AppLayoutDrawerClose asChild>
+            <button>Close</button>
+          </AppLayoutDrawerClose>
+        </DrawerFooter>
+      </AppLayoutDrawerContent>
+    </AppLayoutDrawerRoot>
+  )
+}
+```
+
+> **Note:** `modal={false}` is set by default so clicks outside the drawer do not block the header or sidebar. A custom overlay div is rendered as a portal sibling to catch pointer events and prevent close-and-reopen flicker on trigger elements.

package/src/components/navigation/.app-layout.md

@@ -1,39 +1,42 @@
-<!-- source-hash: 4a7aa4db8bec1fcce07d28f27fea4092 -->
-Orchestrates the top-level application shell, combining the sidebar, header, mobile menu, and notification drawer into a single full-screen layout with managed mobile menu state.
+<!-- source-hash: 037ca5a09298f549d1712277264f7348 -->
+The root shell component that composes the full application chrome — sidebar, header, mobile burger menu, notification drawer, and a drawer portal target — into a responsive, context-driven layout.
 
 ## Key Components
 
 | Export | Type | Description |
-|--------|------|-------------|
-| `AppLayout` | Component | Root layout wrapper rendering all chrome elements and the main content area |
-| `AppLayoutProps` | Interface | Configuration interface for the layout component |
-
-**Key props:**
-- `sidebarConfig` — Navigation structure passed to both `NavigationSidebar` and `MobileBurgerMenu`
-- `headerProps` — Forwarded to `AppHeader` (mobile menu state/toggle are managed internally)
-- `mobileBurgerMenuProps` — Forwarded to `MobileBurgerMenu` (open/close/config are managed internally)
-- `disabled` — Freezes header and sidebar interactions without affecting `children`
-- `loadingFallback` — Custom `Suspense` fallback for the main content area
+|---|---|---|
+| `AppLayout` | Component | Main layout shell wrapping all page chrome and content |
+| `AppLayoutProps` | Interface | Full prop surface for `AppLayout` |
+| `useAppLayoutDrawerContainer` | Hook (re-export) | Access the drawer portal container element |
+| `useAppLayoutDrawerCoordination` | Hook (re-export) | Access drawer open/close coordination context |
+| `AppLayoutDrawerHandle` | Type (re-export) | Handle type for registering a drawer with the layout |
+
+### Notable Props
+
+| Prop | Type | Description |
+|---|---|---|
+| `topBar` | `ReactNode` | Optional full-width banner pinned above sidebar and header |
+| `drawer` | `ReactNode` | Slot for an `AppLayoutDrawer` that portals into the main area |
+| `disabled` | `boolean` | Freezes nav/header chrome while keeping `children` interactive |
+| `loadingFallback` | `ReactNode` | `Suspense` fallback rendered inside `<main>` |
 
 ## Usage Example
 
 ```typescript
 import { AppLayout } from './app-layout'
-import { sidebarConfig } from '../config/navigation'
 
 export default function RootLayout({ children }: { children: React.ReactNode }) {
   return (
     <AppLayout
-      sidebarConfig={sidebarConfig}
+      sidebarConfig={navigationConfig}
       headerProps={{
         logo: <Logo />,
         actions: <UserMenu />,
       }}
-      mobileBurgerMenuProps={{
-        footerContent: <SupportLink />,
-      }}
-      loadingFallback={<PageSkeleton />}
-      mainClassName="p-6"
+      mobileBurgerMenuProps={{ footer: <SupportLink /> }}
+      topBar={<OnboardingBanner />}
+      drawer={<AppLayoutDrawer />}
+      mainClassName="bg-white"
     >
       {children}
     </AppLayout>
@@ -41,8 +44,6 @@ export default function RootLayout({ children }: { children: React.ReactNode })
 }
 ```
 
-## Notes
+## Drawer Coordination
 
-- Mobile menu open/close state is fully self-contained — consumers only provide content-level props via `mobileBurgerMenuProps`
-- `children` are wrapped in `Suspense`, enabling async page transitions out of the box
-- `disabled` is intended for loading or onboarding states where navigation should be temporarily locked
+The layout enforces a **single open drawer** policy via `AppLayoutDrawerCoordinationContext`. When a drawer opens, all other registered drawers are closed programmatically. Opening the mobile burger menu also closes any active drawer (and vice versa), preventing layering conflicts where the menu would render invisibly beneath an open drawer.

package/src/components/navigation/.header-mingo-button.md

@@ -0,0 +1,46 @@
+<!-- source-hash: 167c9c053052f1a347bb1bb0405477b2 -->
+Accessible launcher button for the Mingo AI drawer within `AppHeader`, toggling between a branded icon+wordmark and a close affordance based on active and display state.
+
+## Key Components
+
+### `HeaderMingoButton`
+
+A styled `<button>` that integrates the Mingo AI branding into the app header. Implements the `HeaderButton` visual contract (full sticky-header height, `ods-card` rest / `ods-bg-hover` hover) and exposes open state via `aria-pressed`.
+
+**Props (`HeaderMingoButtonProps`):**
+
+| Prop | Type | Default | Description |
+|---|---|---|---|
+| `isActive` | `boolean` | `false` | Marks the button as pressed while the Mingo drawer is open |
+| `iconOnly` | `boolean` | `false` | Hides the "Mingo AI" wordmark; collapses to icon-only for narrow viewports |
+| `className` | `string` | — | Additional classes merged via `cn()` |
+
+**Behavior:**
+- When `iconOnly && isActive`: renders an `XmarkIcon` and sets `aria-label` to `"Close Mingo AI"`
+- Otherwise: renders `MingoIcon` with ODS cyan accent colors
+- When `!iconOnly`: appends the bold `"Mingo AI"` wordmark
+
+## Usage Example
+
+```typescript
+import { HeaderMingoButton } from '@openframe/ui'
+
+// Full button with wordmark (default)
+<HeaderMingoButton
+  isActive={isMingoOpen}
+  onClick={() => setIsMingoOpen(prev => !prev)}
+/>
+
+// Icon-only mode for mobile/narrow layouts
+<HeaderMingoButton
+  iconOnly
+  isActive={isMingoOpen}
+  onClick={() => setIsMingoOpen(prev => !prev)}
+/>
+```
+
+## Notes
+
+- Designed for use inside `AppHeader`'s `divide-x` divider layout; no standalone active background is applied.
+- Figma reference: `7532:222103 — button-full`
+- Source: [`header-mingo-button.tsx`](https://github.com/flamingo-stack/openframe-oss-lib/blob/main/header-mingo-button.tsx)

package/src/components/navigation/.header-organization-filter.md

@@ -1,36 +1,50 @@
-<!-- source-hash: dec1eb29c513b449612c49f5b36f6f9d -->
-A client-side dropdown filter component for switching between organizations in the OpenFrame header, displaying the selected organization's name and device count.
+<!-- source-hash: 6379158ce442c1637f43fff8dfba4467 -->
+A client-side dropdown component for filtering content by organization in the OpenFrame header, displaying the selected organization name and device count.
 
 ## Key Components
 
 ### Interfaces
-- **`HeaderOrganizationFilterOrganization`** — Shape for each organization entry (`id`, `name`, `deviceCount?`)
-- **`HeaderOrganizationFilterProps`** — Component props including `organizations`, `selectedOrgId`, `onOrgChange`, `totalDeviceCount`, and `className`
+
+- **`HeaderOrganizationFilterOrganization`** — Shape for each organization entry (`id`, `name`, optional `deviceCount`)
+- **`HeaderOrganizationFilterProps`** — Props for the filter component
 
 ### Component
-- **`HeaderOrganizationFilter`** — Renders a styled trigger button with a filter icon, organization name, and device count, wired to a dropdown menu listing all organizations plus an "All Organizations" reset option
+
+- **`HeaderOrganizationFilter`** — Renders a styled trigger button with a filter icon, organization name, and device count, backed by a dropdown menu of selectable organizations
+
+### Behavior
+
+- Defaults to `"All Organizations"` when no `selectedOrgId` matches
+- Shows `totalDeviceCount` when no specific org is selected; shows org-level `deviceCount` when one is selected
+- Calls `onOrgChange('')` to reset to all organizations; calls `onOrgChange(org.id)` on selection
 
 ## Usage Example
 
 ```typescript
-import { HeaderOrganizationFilter } from './header-organization-filter'
+import {
+  HeaderOrganizationFilter,
+  HeaderOrganizationFilterOrganization
+} from './header-organization-filter'
 
-const orgs = [
+const orgs: HeaderOrganizationFilterOrganization[] = [
   { id: 'org-1', name: 'Acme Corp', deviceCount: 42 },
   { id: 'org-2', name: 'Globex Inc', deviceCount: 17 },
 ]
 
-<HeaderOrganizationFilter
-  organizations={orgs}
-  selectedOrgId="org-1"
-  totalDeviceCount={59}
-  onOrgChange={(id) => console.log('Selected org:', id)}
-/>
+function Header() {
+  const [selectedOrgId, setSelectedOrgId] = useState('')
+
+  return (
+    <HeaderOrganizationFilter
+      organizations={orgs}
+      selectedOrgId={selectedOrgId}
+      onOrgChange={setSelectedOrgId}
+      totalDeviceCount={59}
+    />
+  )
+}
 ```
 
-## Behavior Notes
+## Source
 
-- When no `selectedOrgId` matches, defaults to **"All Organizations"** and shows `totalDeviceCount`
-- Selecting "All Organizations" from the dropdown calls `onOrgChange('')`
-- Device count is formatted with `toLocaleString()` (e.g., `1,234 Devices`)
-- Fixed width of `240px` with `border-l` separator, designed for header toolbar placement
+[`header-organization-filter.tsx`](https://github.com/flamingo-stack/openframe-oss-lib/blob/main/header-organization-filter.tsx)

package/src/components/navigation/.header.md

@@ -1,62 +1,55 @@
-<!-- source-hash: 1a8c2c67117a2cb265b878e7d99e1a25 -->
-A responsive, sticky navigation header component with auto-hide on scroll, dropdown menus, and configurable layout zones (logo, navigation, actions).
+<!-- source-hash: b45b42d2833c6191aa9bdecbae716475 -->
+Renders a sticky, auto-hiding site header with configurable logo, navigation items, dropdown menus, and action slots for the OpenFrame platform shell.
 
 ## Key Components
 
 ### `Header`
-The primary exported component that renders a full-width sticky header. Accepts a `HeaderConfig` object to control all visual and behavioral aspects.
+The main exported component. Accepts a `HeaderConfig` object and optional `platform` string to render a full application header with:
 
-**Props:**
-| Prop | Type | Description |
-|------|------|-------------|
-| `config` | `HeaderConfig` | Full layout/behavior configuration |
-| `platform` | `string` | Optional platform identifier |
+- **Auto-hide on scroll** — hides when scrolling down past 50px, re-appears on scroll up (opt-in via `config.autoHide`)
+- **Dropdown menus** — custom-built dropdowns using `inert` for accessibility-safe show/hide (avoids `aria-hidden` focus retention bugs)
+- **Click-outside / Escape dismissal** — event listeners attached only while a dropdown is open
+- **Navigation rendering** — `renderNavigationItem` handles four cases: custom elements, dropdown parents, link/action buttons, and plain action buttons
 
-### Behaviors
+### Exported Types
 
-- **Auto-hide on scroll** — Hides when scrolling down past 50px, reappears on scroll up. Controlled via `config.autoHide`.
-- **Dropdown menus** — Custom-built dropdowns using `inert` (not `aria-hidden`) for proper a11y/focus management. Closes on outside click or `Escape`.
-- **Mobile menu toggle** — Shows a hamburger icon button on small screens, hidden on `md+` breakpoints.
-
-### Layout Zones
-| Zone | Description |
-|------|-------------|
-| Left | Logo link + optional `config.actions.left` slot |
-| Center/Right | Navigation items (positioned via `config.navigation.position`) |
-| Right | Desktop action slot + mobile menu toggle |
+| Export | Description |
+|---|---|
+| `HeaderProps` | `{ config: HeaderConfig; platform?: string }` |
+| `HeaderConfig` | Re-exported from `../../types/navigation` for consumer convenience |
 
 ## Usage Example
 
 ```typescript
-import { Header, HeaderConfig } from './header'
+import { Header } from './header'
+import type { HeaderConfig } from './header'
 
 const config: HeaderConfig = {
   logo: {
     href: '/',
     element: <img src="/logo.svg" alt="Flamingo" />,
   },
+  autoHide: true,
+  backgroundColor: 'bg-ods-card',
   navigation: {
     position: 'center',
     items: [
       { id: 'docs', label: 'Docs', href: '/docs' },
       {
-        id: 'products',
-        label: 'Products',
+        id: 'community',
+        label: 'Community',
         children: [
-          { id: 'openframe', label: 'OpenFrame', href: '/openframe' },
-          { id: 'mingo', label: 'Mingo AI', href: '/mingo' },
+          { id: 'slack', label: 'Slack', href: 'https://www.openmsp.ai/', isExternal: true },
         ],
       },
     ],
   },
-  actions: {
-    right: <Button href="/login">Sign In</Button>,
-  },
-  autoHide: true,
-  mobile: { enabled: true, onToggle: () => setMenuOpen(v => !v) },
+  mingo: { enabled: true },
 }
 
 export default function Layout() {
-  return <Header config={config} />
+  return <Header config={config} platform="openframe" />
 }
-```
+```
+
+> **Accessibility note:** Dropdowns use the HTML `inert` attribute (React 19 native) instead of `aria-hidden` to fully remove hidden content from the tab order and accessibility tree simultaneously.

package/src/components/navigation/.index.md

@@ -1,65 +1,51 @@
-<!-- source-hash: c04d31cdc4af8b84cec9f6c825727d97 -->
-Main entry point for the navigation component library, providing a clean public API with comprehensive exports for headers, sidebars, mobile navigation, and layout components along with their TypeScript type definitions.
+<!-- source-hash: a398abbb0ec4fa945ec8435f34cfbc15 -->
+Barrel export file for the navigation component library, aggregating all navigation-related components, hooks, constants, and TypeScript types into a single `"use client"` entry point.
 
 ## Key Components
 
-**Core Navigation Components:**
-- `Header` - Main header component with configuration support
-- `AppHeader` - Application-level header implementation  
-- `AppLayout` - Full page layout wrapper with navigation
-- `NavigationSidebar` - Primary sidebar navigation component
-
-**Mobile Navigation:**
-- `MobileNavPanel` - Mobile-optimized navigation panel
-- `MobileBurgerMenu` - Hamburger menu for mobile devices
-- `ClientOnlyHeader` - Header that only renders on client-side
-
-**Interactive Elements:**
-- `SlidingSidebar` - Animated sidebar with slide transitions
-- `StickySectionNav` - Section navigation with scroll tracking
-- `HeaderGlobalSearch` - Global search functionality in header
-- `HeaderOrganizationFilter` - Organization filtering component
-
-**Utility Components:**
-- `HeaderSkeleton` - Loading placeholder for header
-- `HeaderButton` - Styled button component for header actions
+| Export | Type | Description |
+|---|---|---|
+| `Header` / `AppHeader` | Component | Primary and application-level header components |
+| `ClientOnlyHeader` | Component | Header rendered exclusively on the client side |
+| `HeaderSkeleton` | Component | Loading placeholder for the header |
+| `AppLayout` | Component | Top-level layout wrapper with drawer support |
+| `AppLayoutDrawer` + sub-components | Components | Composable drawer primitives (trigger, close, content, header, title, description, body, footer) |
+| `SlidingSidebar` / `NavigationSidebar` | Components | Persistent sidebar navigation surfaces |
+| `MobileNavPanel` | Component | Mobile slide-out navigation panel |
+| `MobileBurgerMenu` | Component | Hamburger toggle for mobile navigation |
+| `StickySectionNav` | Component | In-page section navigation with scroll tracking |
+| `MultiLevelNavigation` / `MobileNavigationDropdown` | Components | Tree-shaped navigation for doc viewers and nested content |
+| `MingoAiButton` / `HeaderMingoButton` | Components | Mingo AI access buttons in the header |
+| `HeaderGlobalSearch` | Component | Global search trigger in the header |
+| `HeaderOrganizationFilter` | Component | Organization switcher/filter in the header |
+| `useAppLayoutDrawerContainer` | Hook | Accesses the drawer container context |
+| `useSectionNavigation` | Hook | Drives active-section tracking for `StickySectionNav` |
+| `MOBILE_NAV_PANEL_ID` | Constant | DOM ID for the mobile nav panel |
 
 ## Usage Example
 
 ```typescript
-import { 
-  AppLayout, 
-  Header, 
+import {
+  AppLayout,
+  AppHeader,
   NavigationSidebar,
+  AppLayoutDrawer,
+  AppLayoutDrawerTrigger,
+  AppLayoutDrawerContent,
+  useAppLayoutDrawerContainer,
   type AppLayoutProps,
-  type HeaderConfig 
-} from '@/components/navigation'
-
-// Basic layout setup
-function MyApp() {
-  const headerConfig: HeaderConfig = {
-    showSearch: true,
-    showOrgFilter: true
-  }
+  type NavigationSidebarConfig,
+} from '@openframe/ui/navigation'
 
+export function Shell({ children }: AppLayoutProps) {
   return (
-    <AppLayout
-      header={<Header config={headerConfig} />}
-      sidebar={<NavigationSidebar items={navItems} />}
-    >
-      <main>Your app content</main>
+    <AppLayout>
+      <AppHeader />
+      <NavigationSidebar config={sidebarConfig} />
+      {children}
     </AppLayout>
   )
 }
+```
 
-// Mobile-responsive header
-import { ClientOnlyHeader, MobileNavPanel } from '@/components/navigation'
-
-function ResponsiveHeader() {
-  return (
-    <ClientOnlyHeader>
-      <MobileNavPanel items={mobileNavItems} />
-    </ClientOnlyHeader>
-  )
-}
-```
+> **Source:** [`packages/ui/navigation/index.ts`](https://github.com/flamingo-stack/openframe-oss-lib/blob/main/packages/ui/navigation/index.ts)

package/src/components/navigation/.mingo-ai-button.md

@@ -0,0 +1,41 @@
+<!-- source-hash: 265a30408590dca0bb0f521e12abe9bf -->
+Stateless marketing-header launcher button for the Mingo AI chat panel. Dispatches an `ask-ai:open` CustomEvent on click, allowing the mounted `EmbeddableChat` to respond without tight coupling.
+
+## Key Components
+
+| Export | Type | Description |
+|---|---|---|
+| `MingoAiButton` | `React.FC` | The launcher button component |
+| `MingoAiButtonProps` | `interface` | Extends `React.ButtonHTMLAttributes<HTMLButtonElement>` |
+
+### Props
+
+| Prop | Type | Default | Description |
+|---|---|---|---|
+| `source` | `string` | `undefined` | Identifies the chat panel instance; coalesced to `''` when dispatching |
+| `icon` | `React.ReactNode` | `undefined` | Custom identity glyph; falls back to the packaged `MingoIcon` |
+| `label` | `string` | `'Mingo AI'` | Wordmark text and `aria-label`; pass the server-configured assistant name |
+| `className` | `string` | `undefined` | Additional classes merged via `cn()` |
+| `onClick` | `MouseEventHandler` | `undefined` | Optional callback called after the CustomEvent is dispatched |
+
+## Usage Example
+
+```typescript
+import { MingoAiButton } from '@openframe/ui'
+
+// Basic usage — falls back to packaged MingoIcon and 'Mingo AI' label
+<MingoAiButton source="marketing-header" />
+
+// With server-configured identity (recommended)
+<MingoAiButton
+  source="marketing-header"
+  icon={<EntityIcon assistantIcon={config.mingo.assistantIcon} />}
+  label={config.mingo.assistantName}
+/>
+```
+
+> **Note:** This component is distinct from `HeaderMingoButton` (the dashboard `AppHeader` toggle). They serve different surfaces with different layout contracts — do not merge them.
+
+The button fires `new CustomEvent('ask-ai:open', { detail: { source } })` on `window`. Any `EmbeddableChat` mounted with a matching `source` will open in response.
+
+**Source:** [`mingo-ai-button.tsx`](https://github.com/flamingo-stack/openframe-oss-lib/blob/main/mingo-ai-button.tsx)