@flamingo-stack/openframe-frontend-core 0.0.213 → 0.0.214-snapshot.20260528192313

package/src/components/navigation/.navigation-sidebar.md

@@ -1,47 +1,46 @@
-<!-- source-hash: 8c6b1731317ceb2fdadddd784b3f86f1 -->
-A responsive navigation sidebar component that adapts to different screen sizes with collapsible functionality and mobile overlay support.
+<!-- source-hash: 6f802a22aab4156f34b7564f49df9553 -->
+Responsive navigation sidebar component that renders a collapsible, accessible side navigation panel with distinct behavior for tablet (overlay/floating) and desktop (push layout) viewports.
 
 ## Key Components
 
-- **NavigationSidebar**: Main component that renders a collapsible sidebar with navigation items
-- **NavigationSidebarProps**: Interface defining the configuration prop
-- **renderNavigationItem**: Renders individual navigation items with active states and badges
-- **renderSidebarContent**: Renders the complete sidebar content structure
-- **Constants**: `MINIMIZED_WIDTH` (56px) and `EXPANDED_WIDTH` (224px) for responsive sizing
+| Export | Type | Description |
+|--------|------|-------------|
+| `NavigationSidebar` | Component | Main sidebar component with responsive layout logic |
+| `NavigationSidebarProps` | Interface | Props: `config: NavigationSidebarConfig`, `disabled?: boolean` |
+| `MINIMIZED_WIDTH` | Constant | Collapsed width: `56px` |
+| `EXPANDED_WIDTH` | Constant | Expanded width: `224px` |
+| `STORAGE_KEY` | Constant | localStorage key for desktop minimized state |
+
+### Behavior by Breakpoint
+
+| Viewport | Behavior | State Persistence |
+|----------|----------|-------------------|
+| `< md` | Hidden | — |
+| `md` (tablet) | Floating overlay, starts minimized | In-memory only |
+| `≥ lg` (desktop) | Push layout | localStorage |
+
+### Key Internal Logic
+
+- **`minimized`** — resolves to `tabletMinimized` or `desktopMinimized` based on viewport
+- **`transitionsEnabled`** — deferred via `requestAnimationFrame` to prevent flash of wrong width on hydration
+- **`isOverlayOpen`** — drives backdrop scrim visibility and `Escape` key dismissal
+- **`primaryItems` / `secondaryItems`** — items split by `section !== 'secondary'` filter
 
 ## Usage Example
 
 ```typescript
 import { NavigationSidebar } from './navigation-sidebar'
-import { HomeIcon, SettingsIcon } from '../icons'
+import { NavigationSidebarConfig } from '../../types/navigation'
 
-const sidebarConfig = {
+const config: NavigationSidebarConfig = {
+  minimized: false,
   items: [
-    {
-      id: 'home',
-      label: 'Home',
-      icon: <HomeIcon />,
-      path: '/',
-      isActive: true
-    },
-    {
-      id: 'settings',
-      label: 'Settings',
-      icon: <SettingsIcon />,
-      path: '/settings',
-      section: 'secondary',
-      badge: '2'
-    }
+    { id: 'dashboard', label: 'Dashboard', path: '/dashboard', icon: HomeIcon },
+    { id: 'settings', label: 'Settings', path: '/settings', icon: SettingsIcon, section: 'secondary' },
   ],
-  onNavigate: (path: string) => router.push(path),
-  onToggleMinimized: () => console.log('Sidebar toggled')
-}
-
-function App() {
-  return (
-    <NavigationSidebar config={sidebarConfig} />
-  )
+  onNavigate: (path) => router.push(path),
+  onToggleMinimized: () => console.log('toggled'),
 }
-```
 
-The component automatically handles minimization state persistence via localStorage, responsive behavior across screen sizes, and provides accessibility features including ARIA labels and keyboard navigation support.
+<NavigationSidebar config={config} disabled={false} />
+```

package/src/components/navigation/.sliding-sidebar.md

@@ -1,54 +1,65 @@
-<!-- source-hash: 0d3d7a7563f831b086854a240f9a64d9 -->
-A React component that creates an animated sliding sidebar navigation with collapsible menu items, dynamic header height detection, and smooth animations using Framer Motion.
+<!-- source-hash: 84f0966556e789258670b58482f3bc27 -->
+A client-side animated sidebar component that slides in from either edge of the screen, supporting nested navigation items, dynamic header offset calculation, and animated expand/collapse for sub-menus.
 
 ## Key Components
 
-- **SlidingSidebar** - Main component that renders a slide-in navigation sidebar
-- **SlidingSidebarProps** - Interface defining the component's configuration props
-- **renderMenuItem** - Internal method that recursively renders navigation items with proper nesting
-- **Dynamic header height calculation** - Automatically adjusts sidebar positioning based on header and announcement bar heights
-- **Expandable menu items** - Support for collapsible navigation sections with smooth animations
+### `SlidingSidebarProps`
+| Prop | Type | Description |
+|------|------|-------------|
+| `config` | `SlidingSidebarConfig` | Full sidebar configuration including `isOpen`, `position`, `items`, `onClose`, `footer`, and `className` |
+
+### Internal State
+| State | Purpose |
+|-------|---------|
+| `expandedItems` | Tracks which nav items have their children visible |
+| `mounted` | Guards against SSR hydration mismatches |
+| `headerHeight` | Dynamic offset calculated from `<header>` and `[data-announcement-bar]` elements |
+
+### `renderMenuItem(item, level)`
+Recursive renderer that handles three item variants:
+- **Custom element** — renders `item.element` directly
+- **Parent node** — renders a toggle button with animated `AnimatePresence` child list
+- **Leaf node** — renders a `Button` that calls `item.onClick?.()` then `config.onClose()`
+
+### Header Height Detection
+Uses `ResizeObserver` + `MutationObserver` to dynamically track the combined height of `<header>` and `[data-announcement-bar]`, keeping the sidebar content correctly offset as layout changes.
 
 ## Usage Example
 
 ```typescript
-import { SlidingSidebar } from './components/sliding-sidebar'
-import { SlidingSidebarConfig } from './types/navigation'
-
-function App() {
-  const [sidebarOpen, setSidebarOpen] = useState(false)
-  
-  const sidebarConfig: SlidingSidebarConfig = {
-    isOpen: sidebarOpen,
-    onClose: () => setSidebarOpen(false),
-    position: 'left',
-    items: [
-      {
-        id: 'dashboard',
-        label: 'Dashboard',
-        href: '/dashboard',
-        icon: <DashboardIcon />,
-        isActive: true
-      },
-      {
-        id: 'docs',
-        label: 'Documentation',
-        children: [
-          {
-            id: 'getting-started',
-            label: 'Getting Started',
-            href: '/docs/getting-started'
-          }
-        ]
-      }
-    ],
-    footer: <div>Footer content</div>
-  }
+import { SlidingSidebar } from './sliding-sidebar'
+import { useState } from 'react'
+
+function AppShell() {
+  const [isOpen, setIsOpen] = useState(false)
 
   return (
-    <SlidingSidebar config={sidebarConfig} />
+    <SlidingSidebar
+      config={{
+        isOpen,
+        onClose: () => setIsOpen(false),
+        position: 'left',
+        items: [
+          {
+            id: 'dashboard',
+            label: 'Dashboard',
+            href: '/dashboard',
+            isActive: true,
+          },
+          {
+            id: 'settings',
+            label: 'Settings',
+            children: [
+              { id: 'profile', label: 'Profile', href: '/settings/profile' },
+              { id: 'billing', label: 'Billing', href: '/settings/billing' },
+            ],
+          },
+        ],
+        footer: <div>v1.0.0</div>,
+      }}
+    />
   )
 }
 ```
 
-The component automatically handles header height detection, provides smooth slide animations, supports nested navigation items with expand/collapse functionality, and includes an overlay backdrop for mobile-friendly interaction.
+> **Note:** The sidebar is client-only (`"use client"`). It returns `null` until after mount to prevent SSR/hydration mismatches. Nest it inside a layout that also renders the `<header>` element so the offset calculation works correctly.

package/src/components/navigation/.sticky-section-nav.md

@@ -1,55 +1,63 @@
-<!-- source-hash: f62d6311c11f9d6b1b7bac738d969108 -->
-A reusable sticky navigation component that provides section-based navigation with visual indicators and automatic scroll spy functionality, commonly used for page sections in vendor details, documentation, and knowledge base pages.
+<!-- source-hash: fab223205d06a85cbd1f071b97356037 -->
+Sticky section navigation component and scroll-spy hook for section-based page navigation, used across vendor detail pages, knowledge base, and documentation surfaces.
 
 ## Key Components
 
-- **`StickySectionNav`** - Main navigation component with customizable ribbon positioning and colors
-- **`StickyNavSection`** - Interface defining section structure with id and label
-- **`useSectionNavigation`** - Hook that handles scroll spy detection and smooth scrolling to sections
-- **`StickySectionNavProps`** - Configuration interface for ribbon position, colors, and styling
+### `StickySectionNav`
+A `<nav>` component that renders a vertical list of section buttons with an animated yellow ribbon indicator for the active section.
+
+**Props:**
+
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| `sections` | `StickyNavSection[]` | — | Array of `{ id, label }` nav items |
+| `activeSection` | `string` | — | ID of the currently active section |
+| `onSectionClick` | `(id: string) => void` | — | Click handler for nav items |
+| `ribbonPosition` | `'left' \| 'right'` | `'left'` | Side the active ribbon renders on |
+| `ribbonColor` | `string` | `'#FFC008'` | Active ribbon color |
+| `className` | `string` | — | Optional extra class names |
+
+### `useSectionNavigation`
+A hook that wires up scroll-spy and programmatic scrolling for a set of section refs.
+
+**Returns:** `{ activeSection, handleSectionClick }`
+
+**Options:**
+
+| Option | Type | Default | Description |
+|--------|------|---------|-------------|
+| `offset` | `number` | `100` | Header offset in px passed to `scrollElementIntoView` |
 
 ## Usage Example
 
 ```typescript
-import { StickySectionNav, useSectionNavigation } from './sticky-section-nav'
-import { useRef } from 'react'
-
-function DocumentationPage() {
-  const overviewRef = useRef<HTMLElement>(null)
-  const featuresRef = useRef<HTMLElement>(null)
-  const apiRef = useRef<HTMLElement>(null)
-
-  const sections = [
-    { id: 'overview', ref: overviewRef },
-    { id: 'features', ref: featuresRef },
-    { id: 'api', ref: apiRef }
-  ]
-
-  const { activeSection, handleSectionClick } = useSectionNavigation(sections, {
-    offset: 100
-  })
-
-  const navSections = [
-    { id: 'overview', label: 'Overview' },
-    { id: 'features', label: 'Features' },
-    { id: 'api', label: 'API Reference' }
-  ]
-
-  return (
-    <div className="flex">
-      <StickySectionNav
-        sections={navSections}
-        activeSection={activeSection}
-        onSectionClick={handleSectionClick}
-        ribbonPosition="left"
-        ribbonColor="#FFC008"
-      />
-      <main>
-        <section ref={overviewRef} id="overview">Overview content</section>
-        <section ref={featuresRef} id="features">Features content</section>
-        <section ref={apiRef} id="api">API content</section>
-      </main>
-    </div>
-  )
-}
-```
+const heroRef = useRef<HTMLElement>(null)
+const detailsRef = useRef<HTMLElement>(null)
+
+const sections = [
+  { id: 'hero', ref: heroRef },
+  { id: 'details', ref: detailsRef },
+]
+
+const { activeSection, handleSectionClick } = useSectionNavigation(sections, {
+  offset: 80,
+})
+
+return (
+  <>
+    <StickySectionNav
+      sections={[
+        { id: 'hero', label: 'Overview' },
+        { id: 'details', label: 'Details' },
+      ]}
+      activeSection={activeSection}
+      onSectionClick={handleSectionClick}
+      ribbonPosition="left"
+    />
+    <section id="hero" ref={heroRef}>...</section>
+    <section id="details" ref={detailsRef}>...</section>
+  </>
+)
+```
+
+> **Scroll-spy behavior:** Scroll events are throttled at 100ms. A `isScrollingFromClick` guard suppresses the spy for 500ms after a nav click to prevent active-state flicker during programmatic scrolling.

package/src/components/platform/.ScriptArguments.md

@@ -1,36 +1,50 @@
-<!-- source-hash: 99caf09e90cf5afd729e419a643f7530 -->
-React component for managing script arguments as editable key-value pairs with add/delete functionality. Provides a dynamic interface for users to configure command-line arguments or parameters for script execution.
+<!-- source-hash: a38e5427737fa8905946762e9d50beed -->
+Manages a dynamic list of script arguments as editable key-value pairs, allowing users to add, modify, and delete entries through a controlled form interface.
 
 ## Key Components
 
-- **`ScriptArgument`** - Interface defining a script argument with id, key, and value properties
-- **`ScriptArgumentsProps`** - Component props including arguments array, change handlers, and customization options
-- **`ScriptArguments`** - Main component rendering argument inputs with add/delete controls
-- **Event handlers** - `handleKeyChange`, `handleValueChange`, `handleDelete`, `handleAdd` for managing argument state
+### Interfaces
+
+| Interface | Description |
+|-----------|-------------|
+| `ScriptArgument` | Represents a single argument with `id`, `key`, and `value` fields |
+| `ScriptArgumentsProps` | Props for the component including arguments array, change callbacks, and display options |
+
+### Component
+
+**`ScriptArguments`** — A controlled React component that renders a vertically stacked list of key-value input rows. Each row contains:
+- A **key input** (with label shown only on the first row)
+- A **value input** (placeholder indicates empty = flag-type argument)
+- A **delete button** (`Trash2` icon) to remove the row
+
+An **"Add Script Argument"** button appends a new empty entry using `crypto.randomUUID()` for unique IDs.
 
 ## Usage Example
 
 ```typescript
 import { ScriptArguments, ScriptArgument } from './ScriptArguments'
 
-function MyForm() {
-  const [arguments, setArguments] = useState<ScriptArgument[]>([
-    { id: '1', key: 'port', value: '3000' },
-    { id: '2', key: 'verbose', value: '' }, // empty value = flag
-  ])
-
-  return (
-    <ScriptArguments
-      arguments={arguments}
-      onArgumentsChange={setArguments}
-      titleLabel="Script Parameters"
-      keyPlaceholder="Parameter name"
-      valuePlaceholder="Parameter value (empty for flags)"
-      addButtonLabel="Add Parameter"
-      disabled={false}
-    />
-  )
-}
+const [args, setArgs] = useState<ScriptArgument[]>([
+  { id: '1', key: 'port', value: '3000' },
+  { id: '2', key: 'verbose', value: '' }, // empty value = flag
+])
+
+<ScriptArguments
+  titleLabel="Argument"
+  arguments={args}
+  onArgumentsChange={setArgs}
+  keyPlaceholder="Enter Key"
+  valuePlaceholder="Enter Value (empty=flag)"
+  addButtonLabel="Add Script Argument"
+  disabled={false}
+/>
 ```
 
-The component automatically generates unique IDs for new arguments and supports both valued parameters and flag-style arguments (with empty values).
+### Prop Defaults
+
+| Prop | Default |
+|------|---------|
+| `keyPlaceholder` | `'Enter Key'` |
+| `valuePlaceholder` | `'Enter Value (empty=flag)'` |
+| `addButtonLabel` | `'Add Script Argument'` |
+| `disabled` | `false` |

package/src/components/platform/.ScriptInfoSection.md

@@ -1,37 +1,41 @@
-<!-- source-hash: 6ae48e8d11c816cbe6572cd9e9fc314e -->
-This React component renders script information in a structured card layout with responsive design that adapts from mobile to desktop viewing.
+<!-- source-hash: c574ff5a6a70b0f22372e3d68b48aaf2 -->
+Displays script metadata in a structured card layout, including title, description, shell type, supported platforms, category, and author information. Adapts between a 2×2 grid on mobile/tablet and a single 4-column row on desktop.
 
 ## Key Components
 
-- **ScriptInfoSection** - Main component that displays script metadata in a card format
-- **InfoCell** - Internal component for rendering label-value pairs with optional avatar
-- **ScriptAuthor** - Interface defining author information (name, initials, photo)
-- **ScriptInfoSectionProps** - Props interface for the main component
-- **formatSupportedPlatforms()** - Utility function to format platform arrays into readable strings
-- **getInitials()** - Helper function to extract initials from full names
+### Exported Interfaces
+- **`ScriptAuthor`** — Author data shape: `name`, optional `initials`, optional `photoUrl`
+- **`ScriptInfoSectionProps`** — Component props: `headline`, `subheadline`, `shellType`, `supportedPlatforms`, `category`, `author`, `className`
+
+### Internal Helpers
+- **`formatSupportedPlatforms(platforms?)`** — Maps platform strings (e.g., `'darwin'`) to display labels (e.g., `'macOS'`) via `getOSLabel`; returns `'All Platforms'` when empty
+- **`getInitials(name)`** — Derives two-letter uppercase initials from a full name
+- **`InfoCell`** — Internal cell component rendering a label/value pair with an optional circular avatar
+
+### Main Export
+- **`ScriptInfoSection`** — Card component composing the header row and two responsive detail rows
 
 ## Usage Example
 
 ```typescript
 import { ScriptInfoSection } from './ScriptInfoSection'
 
-function ScriptDetails() {
-  return (
-    <ScriptInfoSection
-      headline="System Backup Script"
-      subheadline="Comprehensive Linux system backup with compression and encryption"
-      shellType="BASH"
-      supportedPlatforms={['linux', 'darwin']}
-      category="System Maintenance"
-      author={{
-        name: 'John Doe',
-        photoUrl: '/avatars/john.jpg',
-        initials: 'JD'
-      }}
-      className="max-w-4xl"
-    />
-  )
-}
+<ScriptInfoSection
+  headline="System Backup Script"
+  subheadline="Comprehensive Linux system backup with rotation support."
+  shellType="BASH"
+  supportedPlatforms={['linux', 'darwin']}
+  category="System Maintenance"
+  author={{
+    name: "Jane Smith",
+    photoUrl: "/avatars/jane.jpg"
+  }}
+/>
 ```
 
-The component features a responsive grid layout: 2x2 grid on mobile/tablet with row dividers, and a single 4-column row on desktop. It includes author avatars with fallback initials, platform formatting using utility functions, and consistent typography styling.
+## Layout Behavior
+
+| Breakpoint | Layout |
+|---|---|
+| Mobile / Tablet (`< lg`) | Two rows, 2 columns each (Shell + Platforms / Category + Author) |
+| Desktop (`lg+`) | Single row, 4 columns |

package/src/components/platform/.ShellTypeBadge.md

@@ -1,12 +1,12 @@
-<!-- source-hash: 56bd1f5693dc1a245a2efd122314c5ff -->
-React component that displays a badge for shell/script types with appropriate icons and labels, supporting all Tactical RMM shell types including PowerShell, CMD, Bash, Python, Nushell, Deno, and generic Shell.
+<!-- source-hash: f614dd9faeadf368597d094822bcd3c7 -->
+Displays a badge combining an icon and label for a given shell/script type, supporting all Tactical RMM shell types (PowerShell, CMD, Bash, Python, Nushell, Deno, Shell).
 
 ## Key Components
 
-- **`ShellTypeBadge`** - Main React component that renders shell type badge with icon and label
-- **`shellIconMap`** - Typed configuration mapping shell types to their corresponding icons and styling
-- **`ShellIconConfig`** - Interface defining icon component structure with size and styling props
-- **`ShellTypeBadgeProps`** - Component props interface accepting shell type and optional className
+- **`shellIconMap`** — A typed `Record<ShellType, ShellIconConfig>` mapping every shell type to its corresponding icon component and display props, ensuring exhaustive coverage at compile time.
+- **`defaultIconConfig`** — Fallback icon config (`ShellIcon`) used when an unrecognized shell type is passed.
+- **`ShellTypeBadgeProps`** — Props interface accepting `shellType`, optional `className` for the wrapper, and optional `iconClassName` for icon styling overrides.
+- **`ShellTypeBadge`** — Main React component that normalizes the shell type to uppercase, resolves the label via `getShellLabel`, and renders the icon + label in a flex row.
 
 ## Usage Example
 
@@ -14,17 +14,22 @@ React component that displays a badge for shell/script types with appropriate ic
 import { ShellTypeBadge } from './components/ShellTypeBadge'
 import { ShellTypeValues } from './types/shell.types'
 
-// Basic usage with PowerShell
+// Basic usage
 <ShellTypeBadge shellType={ShellTypeValues.POWERSHELL} />
 
-// With custom styling
-<ShellTypeBadge 
+// With custom wrapper and icon class overrides
+<ShellTypeBadge
   shellType={ShellTypeValues.PYTHON}
-  className="bg-gray-100 p-2 rounded"
+  className="bg-ods-surface-secondary px-2 py-1 rounded"
+  iconClassName="opacity-75"
 />
 
-// Dynamic shell type from data
-<ShellTypeBadge shellType={script.shellType} />
+// Dynamic shell type from API data
+<ShellTypeBadge shellType={script.shell_type} />
 ```
 
-The component automatically normalizes shell types to uppercase, displays appropriate brand icons (PowerShell, Python) or generic icons for other types, and falls back to a default shell icon for unrecognized types. Each icon is configured with specific sizing and color properties for consistent visual presentation across different shell types.
+## Notes
+
+- Shell type input is normalized to uppercase before lookup, making the component tolerant of mixed-case values from API responses.
+- Icon props support either a `className` (for CSS-driven theming) or a `color` string — the component automatically forwards whichever is applicable.
+- Falls back to `ShellIcon` for any unknown or undefined shell type rather than throwing.

package/src/components/platform/.SoftwareInfo.md

@@ -1,44 +1,40 @@
-<!-- source-hash: b88d68aa0af114862a5c535b5b678159 -->
-A React component for displaying software information including name, vendor, and version in a clean, hierarchical layout as part of the OpenFrame Design System.
+<!-- source-hash: c5159aa07b6a4d2c8ddb68c466359feb -->
+Displays software name with optional vendor and version information, part of the ODS (OpenFrame Design System) platform components.
 
 ## Key Components
 
-**SoftwareInfo** - Main component that renders software details with typography and spacing from the ODS design system
+### `SoftwareInfo`
+A React functional component that renders software metadata in a stacked layout.
 
-**SoftwareInfoProps** - TypeScript interface defining:
-- `name` (required) - Software name displayed prominently
-- `vendor` (optional) - Vendor name shown below the software name
-- `version` (optional) - Version displayed as a badge next to the name
-- `className` (optional) - Additional CSS classes for customization
+### `SoftwareInfoProps`
+| Prop | Type | Required | Description |
+|------|------|----------|-------------|
+| `name` | `string` | ✅ | Software name |
+| `vendor` | `string` | ❌ | Software vendor/publisher |
+| `version` | `string` | ❌ | Software version, rendered as a styled badge |
+| `className` | `string` | ❌ | Additional CSS classes for the root element |
 
 ## Usage Example
 
 ```typescript
 import { SoftwareInfo } from './components/SoftwareInfo'
 
-// Basic usage with name and vendor
-<SoftwareInfo 
-  name="Visual Studio Code" 
-  vendor="Microsoft" 
-/>
-
-// With version badge
-<SoftwareInfo 
-  name="Node.js" 
-  vendor="OpenJS Foundation"
-  version="v18.17.0"
+// Full usage with all props
+<SoftwareInfo
+  name="Visual Studio Code"
+  vendor="Microsoft"
+  version="1.85.0"
 />
 
 // Name only
 <SoftwareInfo name="Chrome" />
 
-// With custom styling
-<SoftwareInfo 
-  name="Docker Desktop"
-  vendor="Docker Inc."
-  version="4.21.1"
-  className="bg-white p-4 rounded-lg"
-/>
+// Name + version badge, no vendor
+<SoftwareInfo name="Node.js" version="20.11.0" />
 ```
 
-The component uses ODS design tokens for consistent typography (DM Sans font family) and color schemes, with the version displayed as a subtle badge and vendor information appearing below the main software name.
+## Rendering Behavior
+
+- **Name** — rendered with `text-h4` and primary text color, always visible.
+- **Version** — rendered inline next to the name as a pill badge with secondary text and a soft-grey background.
+- **Vendor** — rendered below the name row in secondary text color using DM Sans 16px.

package/src/components/platform/.SoftwareSourceBadge.md

@@ -1,33 +1,42 @@
-<!-- source-hash: e3bd453fdd18c74568345f593289f472 -->
-A React component that displays styled badges for different software source types from Fleet MDM, with appropriate icons and labels for package managers, browsers, applications, and system-specific sources across macOS, Windows, and Linux platforms.
+<!-- source-hash: 71f33513a3eb1de6b10214a8a00cf9e8 -->
+Displays a badge with an icon and label for Fleet MDM software source types, mapping all osquery source identifiers to human-readable names with platform-appropriate icons.
 
 ## Key Components
 
-- **`SoftwareSource`** - TypeScript union type defining 18+ supported software source types
-- **`SoftwareSourceBadgeProps`** - Component props interface with source type and optional className
-- **`sourceConfig`** - Configuration object mapping source types to human-readable labels and platform-specific icons
-- **`SoftwareSourceBadge`** - Main component that renders a button-styled badge with icon and label
+- **`SoftwareSource`** — Union type of all 18 supported Fleet MDM software source strings
+- **`SoftwareSourceBadgeProps`** — Props interface accepting `source` and optional `className`
+- **`sourceConfig`** — Internal mapping of each source type to a label and platform icon (macOS, Windows, Linux, or generic Package)
+- **`SoftwareSourceBadge`** — Main component rendering an inline icon + label span; falls back to a `PackageIcon` with the raw source string if the type is unrecognized
 
 ## Usage Example
 
 ```typescript
-import { SoftwareSourceBadge } from './components/SoftwareSourceBadge'
+import { SoftwareSourceBadge } from './SoftwareSourceBadge'
 
-// Basic usage with different source types
+// macOS application
 <SoftwareSourceBadge source="apps" />
-<SoftwareSourceBadge source="chrome_extensions" />
-<SoftwareSourceBadge source="python_packages" />
+// → 🍎 App
+
+// Linux package manager
+<SoftwareSourceBadge source="apt_sources" />
+// → 🐧 APT
+
+// Windows package
+<SoftwareSourceBadge source="chocolatey_packages" />
+// → 🪟 Chocolatey
 
 // With custom styling
-<SoftwareSourceBadge 
-  source="homebrew_packages" 
-  className="ml-2" 
+<SoftwareSourceBadge
+  source="python_packages"
+  className="text-sm font-medium"
 />
-
-// Platform-specific examples
-<SoftwareSourceBadge source="chocolatey_packages" /> // Windows
-<SoftwareSourceBadge source="apt_sources" />        // Linux/Debian
-<SoftwareSourceBadge source="homebrew_packages" />  // macOS
 ```
 
-The component automatically selects appropriate icons (MacOSIcon, WindowsIcon, LinuxIcon, PackageIcon) based on the source type and provides fallback handling for unknown sources.
+## Source-to-Platform Mapping
+
+| Platform | Sources |
+|----------|---------|
+| macOS | `apps`, `homebrew_packages` |
+| Windows | `chocolatey_packages`, `programs` |
+| Linux | `apt_sources`, `deb_packages`, `rpm_packages`, `yum_sources`, `portage_packages` |
+| Generic | All browser extensions, `npm_packages`, `python_packages`, `atom_packages`, `vscode_extensions`, `pkg_packages` |