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

package/src/components/onboarding-guides/.onboarding-guide-detail-view.md

@@ -0,0 +1,55 @@
+<!-- source-hash: be0c6c024827bca8a7ca7b42a3a5a47e -->
+Detail view component for rendering a single onboarding guide at `/onboarding-guides/<slug>`, supporting both SSR-controlled and self-fetching embed modes.
+
+## Key Components
+
+### `OnboardingGuideDetailViewProps`
+Configuration interface with two operating modes:
+- **Controlled (SSR):** Pass `initialData` with a server-fetched `OnboardingGuide`
+- **Self-fetching:** Pass `slug` + `guideEndpoint` factory; the component fetches independently via `useSelfFetch`
+
+Key props:
+
+| Prop | Type | Description |
+|---|---|---|
+| `initialData` | `OnboardingGuide` | Server-fetched guide for SSR mode |
+| `slug` / `guideEndpoint` | `string` / `fn` | Self-fetch mode identifiers |
+| `MarkdownRenderer` | `ComponentType` | Swappable markdown renderer (defaults to `RichMarkdownRenderer`) |
+| `renderRelatedCard` | `fn` | Per-row related guide card override |
+| `relatedContent` | `ReactNode` | Host slot for cross-type related/FAQ rail |
+| `shell` | `boolean` | Wraps in `<PageShell>` when `true` (default); padding-only when `false` |
+
+### `OnboardingGuideDetailView`
+Main exported component. Renders:
+1. Tag badges (`EntityTagBadges`)
+2. Author/metadata grid with section and step order (`EntityAuthorCard`)
+3. Video player with warmup and captions (`EntityVideoSection`)
+4. Markdown body (`MarkdownRenderer`)
+5. Video bites strip (`VideoBitesStrip`)
+6. End-of-article author byline (`ArticleAuthorByline`)
+7. Same-section related guides list
+8. Host-injected `relatedContent` slot
+
+## Usage Example
+
+```typescript
+// SSR / controlled mode (hub page)
+<OnboardingGuideDetailView
+  initialData={serverFetchedGuide}
+  related={relatedGuides}
+  authorHref={`/authors/${guide.author.slug}`}
+  relatedContent={<FAQRail />}
+/>
+
+// Self-fetching / config-only embed mode
+<OnboardingGuideDetailView
+  slug={params.slug}
+  guideEndpoint={(s) => `/content/api/onboarding-guides/${s}`}
+  basePath="/onboarding-guides"
+  shell={false}
+/>
+```
+
+## Source
+
+[`onboarding-guide-detail-view.tsx`](https://github.com/flamingo-stack/openframe-oss-lib/blob/main/onboarding-guide-detail-view.tsx)

package/src/components/onboarding-guides/.onboarding-guides-catalog-skeleton.md

@@ -0,0 +1,33 @@
+<!-- source-hash: 3697dbc9bc0443fb641ee0824c085171 -->
+Loading skeleton component for the `/onboarding-guides` catalog page, rendering chrome-less placeholder UI that mirrors the layout of `<OnboardingGuidesCatalogView>` to prevent layout shifts during data fetching.
+
+## Key Components
+
+- **`OnboardingGuidesCatalogSkeleton`** — Default export-less named function component that renders an animated pulse skeleton matching the catalog view structure:
+  - Search input placeholder (`h-12`)
+  - Section pill/filter row with 4 pill placeholders
+  - Three grouped sections (4, 3, 3 cards) using `<OnboardingGuideCardSkeleton size="catalog" />`
+
+## Usage Example
+
+```typescript
+// app/onboarding-guides/loading.tsx
+import { OnboardingGuidesCatalogSkeleton } from '@/components/onboarding-guides-catalog-skeleton'
+
+// Next.js automatically renders this during page-level Suspense.
+// The host page owns the <DevSectionPage> shell; this component
+// renders only the inner content region.
+export default function Loading() {
+  return <OnboardingGuidesCatalogSkeleton />
+}
+```
+
+## Notes
+
+- **Chrome-less by design**: The host page provides the `<DevSectionPage sectionKey="onboarding">` shell (hero + back button). This skeleton must not re-render that shell — doing so causes duplicate hero/back-button during loading.
+- **Zero layout shift**: Card heights match the loaded `<OnboardingGuideCardSkeleton size="catalog" />` exactly, so no reflow occurs on hydration.
+- **Section structure**: Mirrors the loaded view's three sections with card counts `[4, 3, 3]` and a `w-full flex flex-col gap-10` wrapper.
+
+## Source
+
+[`onboarding-guides-catalog-skeleton.tsx`](https://github.com/flamingo-stack/openframe-oss-lib/blob/main/onboarding-guides-catalog-skeleton.tsx)

package/src/components/onboarding-guides/.onboarding-guides-catalog-view.md

@@ -0,0 +1,50 @@
+<!-- source-hash: 29aaa826793fe156eae898997f8d9746 -->
+Public-facing catalog view component for the `/onboarding-guides` route, supporting both SSR-controlled (hub) and self-fetching (config-only embed) data modes.
+
+## Key Components
+
+### `OnboardingGuidesCatalogViewProps`
+Interface defining two mutually exclusive data modes:
+- **Controlled mode**: `initialGuides` + `initialSections` (server-fetched, host manages re-renders)
+- **Self-fetch mode**: `guidesEndpoint` + `sectionsEndpoint` (component fetches independently, refetches on `?section=` changes)
+
+### `OnboardingGuidesCatalogView`
+Main exported component that renders:
+- `DocSearchBar` — RAG search scoped to `onboarding-guides` table IDs
+- `FilterPillRow` — Dynamic section pills derived from content data
+- Grouped, step-ordered guide cards via `OnboardingGuideCard`
+- `LoadError` / `OnboardingGuidesCatalogSkeleton` for async states
+
+**Notable behaviors:**
+- Section filtering pushes `?section=` to the router; controlled mode triggers host RSC re-fetch, self-fetch mode triggers `useSelfFetch` refetch
+- Card hrefs are composed via `runtime.composeContentUrl` (falling back to relative paths via `resolveContentHref`)
+- Skeleton renders only on cold load; subsequent empty-section transitions dim the grid (`opacity-60`) instead
+- Guides are grouped by `section`, sorted by `section_order`, then each group sorted by `step_order`
+
+## Usage Example
+
+```typescript
+// Controlled (SSR hub) mode
+<OnboardingGuidesCatalogView
+  initialGuides={serverGuides}
+  initialSections={serverSections}
+  initialSection={searchParams.section ?? ''}
+/>
+
+// Self-fetch (config-only embed) mode
+<OnboardingGuidesCatalogView
+  guidesEndpoint="/api/onboarding-guides"
+  sectionsEndpoint="/api/onboarding-guides/sections"
+  basePath="/onboarding-guides"
+/>
+
+// Custom card renderer override
+<OnboardingGuidesCatalogView
+  initialGuides={guides}
+  renderCard={(guide) => <MyCustomCard guide={guide} />}
+/>
+```
+
+> **Note:** This component renders body content only. Callers must wrap it in the appropriate page chrome (e.g., `<DevSectionPage sectionKey="onboarding">`).
+
+**Source:** [`onboarding-guides-catalog-view.tsx`](https://github.com/flamingo-stack/openframe-oss-lib/blob/main/onboarding-guides-catalog-view.tsx)

package/src/components/onboarding-guides/hooks/.use-onboarding-guides.md

@@ -0,0 +1,54 @@
+<!-- source-hash: 7cb9adf30fc30ada99b138146bf5376d -->
+React Query hooks for **public-read** access to Onboarding Guides, plus a shared cache key builder (`onboardingGuideKeys`) used by both this module and hub-side admin mutations.
+
+## Key Components
+
+### `onboardingGuideKeys`
+
+Structured cache key builder for the `['onboarding-guides']` namespace. Covers both public sub-keys and an `admin` sub-namespace, ensuring a single source of truth for cache invalidation across public and admin hooks.
+
+| Key | Description |
+|---|---|
+| `all` | Root namespace key |
+| `lists()` / `list(filters)` | Filtered list queries |
+| `details()` / `detail(slug)` | Single guide by slug |
+| `sections()` | Section summary list |
+| `admin.*` | Sub-namespace for hub-side admin mutations |
+
+### `useOnboardingGuides(filters?)`
+
+Fetches a paginated/filtered list of guides from `/api/onboarding-guides`. Supports `search`, `section`, `limit`, and `offset` filter params.
+
+### `useOnboardingGuide(slug)`
+
+Fetches a single guide by slug from `/api/onboarding-guides/:slug`. Query is disabled when `slug` is undefined or empty.
+
+### `useOnboardingGuideSections()`
+
+Fetches section summaries from `/api/onboarding-guides/sections`. Sets `staleTime: 0` to always revalidate on mount.
+
+## Usage Example
+
+```typescript
+import {
+  useOnboardingGuides,
+  useOnboardingGuide,
+  useOnboardingGuideSections,
+  onboardingGuideKeys,
+} from './use-onboarding-guides'
+
+// Filtered list
+const { data: guides } = useOnboardingGuides({ section: 'setup', limit: 10 })
+
+// Single guide — query skips when slug is undefined
+const { data: guide } = useOnboardingGuide('getting-started')
+
+// Section navigation
+const { data: sections } = useOnboardingGuideSections()
+
+// Admin hook (hub-side) — invalidates both admin and public caches
+queryClient.invalidateQueries({ queryKey: onboardingGuideKeys.all })
+queryClient.invalidateQueries({ queryKey: onboardingGuideKeys.admin.all })
+```
+
+> **Note:** Endpoints (`/api/onboarding-guides*`) are host-supplied. Non-Next.js embedders must reverse-proxy these routes before using these hooks.

package/src/components/platform/.CveLink.md

@@ -1,32 +1,43 @@
-<!-- source-hash: b7318fc1fffa50dcdbe4709ff641c588 -->
-A React component that renders CVE (Common Vulnerabilities and Exposures) identifiers as clickable links to the NIST National Vulnerability Database. The component displays the CVE ID with an external link icon and applies hover effects for enhanced user experience.
+<!-- source-hash: 6845fb3dc956be05f53fde1bb106780d -->
+Renders a CVE ID as a clickable external link pointing to the NIST National Vulnerability Database (NVD), with an accompanying external link icon.
 
 ## Key Components
 
-- **CveLink**: Main component that renders a CVE ID as an external link
-- **CveLinkProps**: TypeScript interface defining component props
-  - `cveId`: Required CVE identifier string
-  - `className`: Optional CSS classes for styling customization
+| Export | Type | Description |
+|---|---|---|
+| `CveLink` | `React.FC<CveLinkProps>` | Main component that renders the CVE ID link |
+| `CveLinkProps` | `interface` | Props definition for the component |
+
+### Props
+
+| Prop | Type | Required | Description |
+|---|---|---|---|
+| `cveId` | `string` | ✅ | CVE identifier (e.g., `"CVE-2024-1234"`) |
+| `className` | `string` | ❌ | Additional CSS classes to merge |
 
 ## Usage Example
 
 ```typescript
-import { CveLink } from './components/CveLink'
+import { CveLink } from '@openframe/oss-lib'
 
 // Basic usage
 <CveLink cveId="CVE-2024-1234" />
 
 // With custom styling
-<CveLink 
-  cveId="CVE-2023-5678" 
-  className="text-red-500 hover:text-red-700" 
+<CveLink
+  cveId="CVE-2023-44487"
+  className="text-sm font-mono"
 />
-
-// In a vulnerability report
-<div className="vulnerability-item">
-  <h3>Critical Security Issue</h3>
-  <p>Reference: <CveLink cveId="CVE-2024-9999" /></p>
-</div>
 ```
 
-The component automatically generates NIST NVD URLs, opens links in new tabs with proper security attributes, and includes accessibility features. It uses the OpenFrame Design System (ODS) styling tokens and includes smooth hover transitions for both the text and external link icon.
+Clicking the link opens `https://nvd.nist.gov/vuln/detail/{cveId}` in a new tab with `rel="noopener noreferrer"` for security.
+
+## Styling Behavior
+
+- Uses ODS design tokens (`ods-text-primary`, `ods-accent`, `ods-text-secondary`)
+- The external link icon transitions from `ods-text-secondary` → `ods-accent` on hover via the `group` utility
+- Accepts additional classes via `className` merged through the `cn` utility
+
+## Source
+
+[`CveLink.tsx`](https://github.com/flamingo-stack/openframe-oss-lib/blob/main/src/components/platform/CveLink.tsx)

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

@@ -1,23 +1,25 @@
-<!-- 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.
+<!-- source-hash: 7aa67860b1ab611a656cba5c50d1632b -->
+Manages a dynamic list of script arguments as editable key-value pairs, with support for adding and removing entries.
 
 ## Key Components
 
 ### 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 |
+- **`ScriptArgument`** — Represents a single argument with `id`, `key`, and `value` fields. Empty `value` strings indicate flag-type arguments.
+- **`ScriptArgumentsProps`** — Component props including the arguments array, change callbacks, placeholder text overrides, disabled state, and a required `titleLabel`.
 
 ### 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
+- **`ScriptArguments`** — Renders a vertically stacked list of key/value input rows. The column label appears only on the first row. Each row includes a delete button (trash icon); an "Add Script Argument" button appends a new blank entry using `crypto.randomUUID()`.
 
-An **"Add Script Argument"** button appends a new empty entry using `crypto.randomUUID()` for unique IDs.
+### Internal Handlers
+
+| Handler | Description |
+|---|---|
+| `handleKeyChange` | Updates the `key` field for a given argument `id` |
+| `handleValueChange` | Updates the `value` field for a given argument `id` |
+| `handleDelete` | Removes an argument by `id` |
+| `handleAdd` | Appends a new blank `ScriptArgument` |
 
 ## Usage Example
 
@@ -26,25 +28,18 @@ import { ScriptArguments, ScriptArgument } from './ScriptArguments'
 
 const [args, setArgs] = useState<ScriptArgument[]>([
   { id: '1', key: 'port', value: '3000' },
-  { id: '2', key: 'verbose', value: '' }, // empty value = flag
+  { id: '2', key: 'verbose', value: '' }, // flag-type argument
 ])
 
 <ScriptArguments
-  titleLabel="Argument"
+  titleLabel="Script Arguments"
   arguments={args}
   onArgumentsChange={setArgs}
-  keyPlaceholder="Enter Key"
-  valuePlaceholder="Enter Value (empty=flag)"
+  keyPlaceholder="Argument name"
+  valuePlaceholder="Value (empty = flag)"
   addButtonLabel="Add Script Argument"
   disabled={false}
 />
 ```
 
-### Prop Defaults
-
-| Prop | Default |
-|------|---------|
-| `keyPlaceholder` | `'Enter Key'` |
-| `valuePlaceholder` | `'Enter Value (empty=flag)'` |
-| `addButtonLabel` | `'Add Script Argument'` |
-| `disabled` | `false` |
+> **Note:** All mutation callbacks (`onArgumentsChange`) are no-ops when omitted, making the component safe to render in read-only contexts without extra guards.

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

@@ -1,41 +1,47 @@
-<!-- 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.
+<!-- source-hash: 78008c7e3ccfb1ba2cc09775fac553c1 -->
+Displays script metadata in a responsive card layout with a header (title, description) and a grid of detail cells (shell type, platforms, category, author).
 
 ## Key Components
 
-### 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
+| Export | Type | Description |
+|---|---|---|
+| `ScriptInfoSection` | `React.FC` | Main component rendering the full script info card |
+| `ScriptInfoSectionProps` | `interface` | Props for the main component |
+| `ScriptAuthor` | `interface` | Author shape with `name`, `initials`, and `photoUrl` |
+| `InfoCell` | Internal component | Single label/value cell, optionally renders an author avatar |
+| `formatSupportedPlatforms` | Helper function | Converts a platform array to a display string via `getOSLabel` |
+| `getInitials` | Helper function | Derives two-letter initials from a full name |
 
 ## Usage Example
 
 ```typescript
-import { ScriptInfoSection } from './ScriptInfoSection'
+import { ScriptInfoSection } from './components/ScriptInfoSection'
 
 <ScriptInfoSection
   headline="System Backup Script"
-  subheadline="Comprehensive Linux system backup with rotation support."
+  subheadline="Comprehensive Linux system backup with incremental support."
   shellType="BASH"
   supportedPlatforms={['linux', 'darwin']}
   category="System Maintenance"
   author={{
-    name: "Jane Smith",
-    photoUrl: "/avatars/jane.jpg"
+    name: 'Jane Smith',
+    photoUrl: '/avatars/jane.jpg',
   }}
 />
 ```
 
 ## Layout Behavior
 
-| Breakpoint | Layout |
-|---|---|
-| Mobile / Tablet (`< lg`) | Two rows, 2 columns each (Shell + Platforms / Category + Author) |
-| Desktop (`lg+`) | Single row, 4 columns |
+The detail grid is responsive:
+
+- **Mobile / Tablet (`< lg`):** Two rows of two cells each, separated by a border.
+- **Desktop (`lg+`):** All four cells rendered in a single four-column row; the mobile second row is hidden via `hidden lg:flex`.
+
+## Notes
+
+- `shellType` is resolved to a display label via `getShellLabel` (e.g., `"BASH"` → `"Bash"`).
+- `supportedPlatforms` defaults to `"All Platforms"` when absent or empty.
+- Author avatar falls back to computed initials (`getInitials`) when `photoUrl` is not provided.
+- Accepts an optional `className` prop for layout overrides at the card level.
+
+**Source:** [`ScriptInfoSection.tsx`](https://github.com/flamingo-stack/openframe-oss-lib/blob/main/ScriptInfoSection.tsx)

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

@@ -1,35 +1,51 @@
-<!-- source-hash: f614dd9faeadf368597d094822bcd3c7 -->
-Displays a badge combining an icon and label for a given shell/script type, supporting all OpenFrame RMM shell types (PowerShell, CMD, Bash, Python, Nushell, Deno, Shell).
+<!-- source-hash: a29c2af2ef838a1ce94f667c761fb1ab -->
+Displays a badge for RMM shell/script types, pairing an appropriate icon with a human-readable label for all supported shell environments.
 
 ## Key Components
 
-- **`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.
+### `ShellTypeBadge` (React.FC)
+The primary export. Renders an icon + label pair for a given `ShellType`.
+
+### `ShellTypeBadgeProps`
+| Prop | Type | Description |
+|---|---|---|
+| `shellType` | `ShellType` | The shell/script type to display |
+| `className` | `string?` | Additional classes for the wrapper `div` |
+| `iconClassName` | `string?` | Additional classes applied to the icon |
+
+### `shellIconMap`
+A fully-typed `Record<ShellType, ShellIconConfig>` ensuring exhaustive coverage of all supported shell types: `POWERSHELL`, `CMD`, `BASH`, `PYTHON`, `NUSHELL`, `DENO`, and `SHELL`.
+
+**Supported shell types and their icons:**
+
+| Shell | Icon Component |
+|---|---|
+| PowerShell | `PowershellLogoGreyIcon` |
+| CMD | `CmdIcon` |
+| Bash | `BashIcon` |
+| Python | `PythonLogoIcon` |
+| Nushell | `NushellIcon` |
+| Deno | `DenoIcon` |
+| Shell | `ShellIcon` (default fallback) |
 
 ## Usage Example
 
 ```typescript
-import { ShellTypeBadge } from './components/ShellTypeBadge'
-import { ShellTypeValues } from './types/shell.types'
+import { ShellTypeBadge } from './ShellTypeBadge'
+import { ShellTypeValues } from '../../types/shell.types'
 
 // Basic usage
 <ShellTypeBadge shellType={ShellTypeValues.POWERSHELL} />
 
-// With custom wrapper and icon class overrides
+// With custom wrapper and icon classes
 <ShellTypeBadge
   shellType={ShellTypeValues.PYTHON}
-  className="bg-ods-bg-surface px-2 py-1 rounded"
-  iconClassName="opacity-75"
+  className="bg-surface-secondary px-2 py-1 rounded"
+  iconClassName="opacity-80"
 />
 
-// Dynamic shell type from API data
-<ShellTypeBadge shellType={script.shell_type} />
+// Case-insensitive — input is normalized to uppercase internally
+<ShellTypeBadge shellType={"bash" as ShellType} />
 ```
 
-## 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.
+> **Note:** Unknown or unrecognized `shellType` values fall back to `ShellIcon` via `defaultIconConfig`, preventing render errors.

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

@@ -1,40 +1,42 @@
-<!-- source-hash: c5159aa07b6a4d2c8ddb68c466359feb -->
-Displays software name with optional vendor and version information, part of the ODS (OpenFrame Design System) platform components.
+<!-- source-hash: 746186688c607619ce30e85de8efbe70 -->
+Displays software name with optional vendor and version metadata, part of the ODS (OpenFrame Design System) platform components.
 
 ## Key Components
 
-### `SoftwareInfo`
-A React functional component that renders software metadata in a stacked layout.
-
 ### `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 |
+| `vendor` | `string` | ❌ | Software vendor |
+| `version` | `string` | ❌ | Software version (rendered as a badge) |
+| `className` | `string` | ❌ | Additional CSS classes |
+
+### `SoftwareInfo`
+
+A React functional component that renders a vertical stack: the software name alongside an optional version badge, with the vendor name displayed below in secondary text.
 
 ## Usage Example
 
 ```typescript
-import { SoftwareInfo } from './components/SoftwareInfo'
+// Name only
+<SoftwareInfo name="Chrome" />
+
+// Name with vendor
+<SoftwareInfo name="Visual Studio Code" vendor="Microsoft" />
 
-// Full usage with all props
+// Full usage with version and custom class
 <SoftwareInfo
   name="Visual Studio Code"
   vendor="Microsoft"
-  version="1.85.0"
+  version="1.89.0"
+  className="my-4"
 />
-
-// Name only
-<SoftwareInfo name="Chrome" />
-
-// Name + version badge, no vendor
-<SoftwareInfo name="Node.js" version="20.11.0" />
 ```
 
-## Rendering Behavior
+## Notes
 
-- **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.
+- Version is rendered as a pill/badge using `ods-bg-surface` background and `ods-text-secondary` color.
+- Vendor is rendered below the name row using secondary text styling.
+- Uses the [`cn`](https://github.com/flamingo-stack/openframe-oss-lib/blob/main/src/utils/cn.ts) utility for conditional class merging.
+- `displayName` is set to `'SoftwareInfo'` for improved React DevTools visibility.

package/src/components/platform/.ToolBadge.md

@@ -1,36 +1,38 @@
-<!-- source-hash: 5668aa064d8c050beff751a96d6469be -->
-A React component that renders a visual badge combining a tool icon and label for OpenFrame-integrated MSP tools (e.g., Fleet MDM, MeshCentral).
+<!-- source-hash: 2c040db85e1fc2ee2edcbf7fa6012881 -->
+Renders a compact badge combining a `ToolIcon` and label for a given OpenFrame tool type, designed for use in tables and lists to identify tool sources such as Fleet MDM, MeshCentral, and OpenFrame RMM.
 
 ## Key Components
 
-| Export | Type | Description |
-|--------|------|-------------|
-| `ToolBadge` | `React.FC<ToolBadgeProps>` | Main badge component |
-| `ToolBadgeProps` | `interface` | Props: `toolType`, `className`, `iconClassName` |
-| `ToolType` | `type` (re-export) | Enum/union of supported tool types |
+- **`ToolBadge`** — Main functional component that resolves a human-readable label via `getToolLabel` and renders it alongside its corresponding `ToolIcon`
+- **`ToolBadgeProps`** — Interface defining accepted props:
+  - `toolType: ToolType` — Required; identifies which tool to display
+  - `className?: string` — Optional CSS classes for the wrapper `div`
+  - `iconClassName?: string` — Optional CSS classes forwarded to `ToolIcon`
+- **Re-export** — `ToolType` is re-exported from `../../types/tool.types` for consumer convenience
 
 ## Usage Example
 
 ```typescript
 import { ToolBadge } from './components/ToolBadge'
 
-// Basic usage in a table cell
+// Basic usage
 <ToolBadge toolType="OPENFRAME_RMM" />
 
 // With custom styling
 <ToolBadge
   toolType="FLEET"
-  className="my-2"
-  iconClassName="opacity-80"
+  className="opacity-75"
+  iconClassName="text-blue-500"
 />
 
-// MeshCentral badge
-<ToolBadge toolType="MESHCENTRAL" />
+// In a table cell
+<td>
+  <ToolBadge toolType="MESHCENTRAL" />
+</td>
 ```
 
 ## Notes
 
-- Resolves the human-readable label via `getToolLabel()` from `tool-utils`
-- Renders a 16px `ToolIcon` alongside the label text
-- Supports `className` for the wrapper `div` and `iconClassName` for the icon independently
-- Uses `cn()` utility for conditional class merging (Tailwind-compatible)
+- Icon renders at a fixed size of `16px`; only the wrapper and icon accept className overrides
+- Label text uses `text-ods-text-primary` / `text-h4` design token classes — ensure your project includes the ODS theme
+- `displayName` is set to `'ToolBadge'` for accurate React DevTools identification