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

package/src/stories/.NotificationDrawer.stories.md

@@ -1,20 +1,22 @@
-<!-- source-hash: fd9f374934342611a000534ff097b06e -->
-Storybook stories for the `NotificationDrawer` feature, providing interactive visual tests for notification tile variants, drawer states, and live notification dispatching via the `useNotifications` hook.
+<!-- source-hash: f63f316c3ca0b7f0616cd692ac686468 -->
+Storybook stories file for the `NotificationDrawer` feature, providing visual documentation and interactive playground stories for notification tiles, drawer states, and approval workflows.
 
 ## Key Components
 
-| Export | Description |
-|---|---|
-| `AllTileVariants` | Static preview of all five `NotificationVariant` tile styles (`default`, `success`, `error`, `warning`, `info`) in a settled/read state |
-| `LiveTile` | Demonstrates the animated progress-bar lifecycle of a freshly arrived tile, with a replay button |
-| `DrawerEmpty` | Drawer rendered with zero notifications (empty state), auto-opened on mount |
-| `DrawerWithSeedData` | Drawer pre-seeded with six notifications mirroring the Figma reference design |
-| `LivePlayground` | Interactive sandbox for firing notifications of any variant, toggling the drawer, and testing `markAllRead`/`clear` |
+| Export | Type | Description |
+|---|---|---|
+| `AllTileVariants` | Story | Static preview of all notification tile variants (`default`, `success`, `error`, `warning`, `info`) |
+| `SeverityIconAndImage` | Story | Demonstrates the `severity` field (`INFO`, `WARNING`, `DANGER`) with image, icon, and dot fallback states |
+| `LiveTile` | Story | Animated tile showing the 4-second progress bar + dismiss UX before settling into resting state |
+| `DrawerEmpty` | Story | `NotificationDrawer` rendered with no notifications (empty state) |
+| `DrawerWithSeedData` | Story | Drawer pre-seeded with `SEED` data covering all approval resolution states: pending, approved, rejected, cancelled |
+| `AutoOpen` | Helper | Internal component that calls `useNotifications().open()` on mount to auto-expand the drawer in stories |
+| `approvalSeed` | Helper | Factory function generating `Notification` objects for approval-request tiles in a given resolution state |
 
 ## Usage Example
 
 ```typescript
-// Minimal setup mirroring how stories bootstrap the notification system
+// Minimal provider + drawer setup (mirrors DrawerEmpty story)
 import {
   NotificationsProvider,
   NotificationDrawer,
@@ -24,32 +26,41 @@ import {
 function App() {
   return (
     <NotificationsProvider
-      initialNotifications={[]}
+      initialNotifications={SEED}
       onHistoryClick={() => router.push('/notifications')}
-      onShowPopupsChange={(enabled) => console.log('popups:', enabled)}
+      historyHref="/notifications"
+      renderTile={renderApprovalTile}
     >
       <NotificationDrawer />
-      <FireButton />
     </NotificationsProvider>
   );
 }
 
-function FireButton() {
+// Fire a notification from any realtime source
+function RealtimeListener() {
   const { addNotification } = useNotifications();
-  return (
-    <button
-      onClick={() =>
-        addNotification({
-          variant: 'success',
-          title: 'Deployment Complete',
-          description: 'HP EliteBook deployed to Marketing Dept',
-        })
-      }
-    >
-      Fire notification
-    </button>
-  );
+
+  useEffect(() => {
+    socket.on('alert', (event) => {
+      addNotification({
+        id: event.id,
+        severity: 'WARNING',
+        type: 'Disk Space Warning',
+        icon: <AlertTriangleIcon size={16} />,
+        title: event.device,
+        description: event.message,
+        createdAt: Date.now(),
+        read: false,
+      });
+    });
+  }, [addNotification]);
+
+  return null;
 }
 ```
 
-> Mount `<NotificationsProvider>` once at the app root. The `<NotificationDrawer>` can be placed anywhere within the provider tree; the bell button in `AppHeader` toggles it automatically.
+## Notes
+
+- Mount `<NotificationsProvider>` once at the app root; the bell button in `AppHeader` toggles the drawer automatically.
+- The `severity` field (`INFO` | `WARNING` | `DANGER`) overrides `variant` for color; `imageUrl` takes priority over `icon`, which falls back to a severity dot.
+- Source: [`NotificationDrawer.stories.tsx`](https://github.com/flamingo-stack/openframe-oss-lib/blob/main/NotificationDrawer.stories.tsx)

package/src/stories/.OSTypeBadge.stories.md

@@ -1,34 +1,43 @@
-<!-- source-hash: 5ace583dbfd66c8797d551088d516a48 -->
-Storybook configuration file defining visual documentation and interactive examples for the OSTypeBadge component system. This file creates comprehensive stories showcasing different OS type displays, normalization capabilities, and component variants.
+<!-- source-hash: f7b466b1e3952004dc2b4484708db888 -->
+Storybook stories for the `OSTypeBadge`, `OSTypeIcon`, and `OSTypeLabel` components, covering OS type rendering, alias normalization, display modes, and sizing variants.
 
 ## Key Components
 
-- **OSTypeBadge Stories** - Main component stories with various OS types and display modes
-- **OSTypeIcon Stories** - Icon-only variant stories with different sizes
-- **OSTypeLabel Stories** - Label-only variant stories
-- **Alias Demonstrations** - Stories showing OS type string normalization from different sources
-- **Configuration Objects** - Meta configurations for each component variant
+| Export | Type | Description |
+|---|---|---|
+| `Default` / `Windows` / `MacOS` / `Linux` | `Story` | Basic OS badge rendering per platform |
+| `Darwin` / `Ubuntu` | `Story` | Alias normalization (e.g. `"Darwin"` → macOS, `"Ubuntu"` → Linux) |
+| `IconOnly` / `LabelOnly` | `Story` | Display mode variants |
+| `LargeIcon` | `Story` | Custom icon sizing via Tailwind class |
+| `Unknown` | `Story` | Graceful fallback for undefined OS type |
+| `AllOSTypes` | `Story` | Side-by-side comparison of all three platforms |
+| `Aliases` | `Story` | Normalization showcase for `Darwin`, `win32`, `Ubuntu`, `Fedora` |
+| `Icons` / `IconSizes` | `IconStory` | `OSTypeIcon` standalone stories with size variants |
+| `Labels` | `LabelStory` | `OSTypeLabel` standalone story |
 
 ## Usage Example
 
 ```typescript
-// Example story configuration for Windows OS display
-export const Windows: Story = {
-  args: {
-    osType: 'windows',
-  },
-};
-
-// Custom render function for comparison stories
-export const AllOSTypes: Story = {
-  render: () => (
-    <div style={{ display: 'flex', flexDirection: 'column', gap: '1rem' }}>
-      <OSTypeBadge osType="windows" />
-      <OSTypeBadge osType="macos" />
-      <OSTypeBadge osType="linux" />
-    </div>
-  ),
-};
+// Full badge (icon + label)
+<OSTypeBadge osType="Darwin" />          // normalizes → macOS
+<OSTypeBadge osType="win32" />           // normalizes → Windows
+
+// Icon only
+<OSTypeBadge osType="linux" iconOnly />
+<OSTypeIcon  osType="linux" size="w-6 h-6" />
+
+// Label only
+<OSTypeBadge osType="macos" labelOnly />
+<OSTypeLabel osType="macos" />
+
+// Unknown / missing type (renders fallback)
+<OSTypeBadge osType={undefined} labelOnly />
 ```
 
-The stories demonstrate OS type normalization from various MDM sources (Fleet) with support for aliases like "Darwin" → "macOS" and "win32" → "Windows". Includes examples for icon-only, label-only, and combined display modes with customizable sizing options.
+## Notes
+
+- The `meta` object configures three separate Storybook entries: `Features/OSTypeBadge`, `Features/OSTypeIcon`, and `Features/OSTypeLabel`.
+- `osType` accepts case-insensitive strings and platform aliases sourced from Fleet MDM, OpenFrame RMM, and similar integrations.
+- `iconSize` / `size` accept Tailwind width/height classes (e.g. `"w-6 h-6"`).
+
+**Source:** [`OSTypeBadge.stories.tsx`](https://github.com/flamingo-stack/openframe-oss-lib/blob/main/OSTypeBadge.stories.tsx)

package/src/stories/.OnboardingGuideCard.stories.md

@@ -0,0 +1,41 @@
+<!-- source-hash: 158823868f1a6fa08bcd360e6e3fc0c6 -->
+Storybook stories for the `OnboardingGuideCard` component, covering all three display densities used across the MSP platform UI.
+
+## Key Components
+
+| Export | Description |
+|---|---|
+| `meta` | Storybook metadata — registers the component under `Chat/EntityCards/OnboardingGuideCard` with fullscreen layout |
+| `ChatInlineSm` | Compact `sm` size story, matches the `size="sm"` + `displayAction: true` output from the chat dispatcher |
+| `Default` | Horizontal step-card layout at the `default` density |
+| `Catalog` | Full hero + author grid layout at the `catalog` density |
+
+## Usage Example
+
+```typescript
+// Render the chat-inline variant directly in your component
+import { OnboardingGuideCard } from '../components/chat/entity-cards'
+import { onboardingGuide } from './__fixtures__/chat-cards'
+
+<OnboardingGuideCard
+  guide={onboardingGuide}
+  href={`/guides/${onboardingGuide.slug}`}
+  size="sm"
+  target="_blank"
+  rel="noopener noreferrer"
+/>
+```
+
+## Size Variants
+
+| Size | Use Case |
+|---|---|
+| `sm` | Chat-inline compact — always used by the chat dispatcher |
+| `default` | Horizontal step-card — standard page embeds |
+| `catalog` | Hero + author grid — browse/catalog views |
+
+## Notes
+
+- All stories are wrapped in `ChatColumnDecorator` to simulate the chat column width constraint.
+- The `sm` story mirrors the exact props the chat dispatch layer injects at runtime (`size="sm"`, `displayAction: true`).
+- Fixture data is sourced from [`__fixtures__/chat-cards`](https://github.com/flamingo-stack/openframe-oss-lib/blob/main/stories/__fixtures__/chat-cards.ts).

package/src/stories/.PageActions.stories.md

@@ -1,39 +1,41 @@
-<!-- source-hash: cad0666dc893f948d0160200a40d9384 -->
-Storybook stories file for the `PageActions` component, documenting all interactive variants and states for use in the Flamingo/OpenFrame UI library.
+<!-- source-hash: c2ab0103ae9c6603a7acd3db11530c37 -->
+Storybook stories for the `PageActions` UI component, covering all layout variants, responsive behaviors, and interactive states.
 
 ## Key Components
 
-**Exported Stories:**
+### Stories
 
 | Story | Variant | Description |
 |---|---|---|
-| `IconButtons` | `icon-buttons` | Icon + label buttons, collapses to dropdown on mobile |
-| `PrimaryButtons` | `primary-buttons` | Accent + outline buttons, fixed bottom bar on mobile |
+| `IconButtons` | `icon-buttons` | Icon-labeled buttons; collapses to dropdown on mobile |
+| `PrimaryButtons` | `primary-buttons` | Accent + outline buttons; fixed bottom bar on mobile |
 | `PrimaryButtonsWithIcons` | `primary-buttons` | Primary buttons with leading icons |
-| `SinglePrimaryButton` | `primary-buttons` | Single accent CTA |
-| `SingleIconButton` | `icon-buttons` | Single icon button (stays visible on mobile, no menu collapse) |
-| `ThreeIconButtons` | `icon-buttons` | Three-action icon row |
-| `WithStates` | `primary-buttons` | `loading` and `disabled` prop states |
-| `MenuPrimary` | `menu-primary` | `...` overflow menu + primary button |
-| `MenuPrimaryLoading` | `menu-primary` | Loading state on primary button |
-| `MobileOnlyActions` | `icon-buttons` | `showOnlyMobile` prop — hides specific actions on desktop |
-| `LinkActions` | `menu-primary` | `href`-based actions rendering as `<a>` elements |
-| `SplitButtonWithMenu` | `menu-primary` | `submenu` chevron split button pattern |
-| `SplitButtonTwoActions` | `menu-primary` | `iconAction` dual-target split button |
+| `SinglePrimaryButton` | `primary-buttons` | Single accent button |
+| `SingleIconButton` | `icon-buttons` | Single icon button (no dropdown collapse on mobile) |
+| `ThreeIconButtons` | `icon-buttons` | Three icon buttons |
+| `WithStates` | `primary-buttons` | Loading and disabled button states |
+| `MenuPrimary` | `menu-primary` | `...` dropdown menu + primary button |
+| `MenuPrimaryLoading` | `menu-primary` | Primary button in loading state |
+| `MobileOnlyActions` | `icon-buttons` | Actions hidden on desktop via `showOnlyMobile` |
+| `LinkActions` | `menu-primary` | Actions rendered as Next.js `<Link>` via `href` |
+| `SplitButtonWithMenu` | `menu-primary` | Primary button with chevron submenu |
+| `SplitButtonTwoActions` | `menu-primary` | Two independently clickable button halves via `iconAction` |
 
 ## Usage Example
 
 ```typescript
-// Basic icon-buttons usage in a page header
+import { PageActions } from '../components/ui/page-actions'
+import { PlusCircleIcon, PlayCircleIcon, PenEditIcon } from '../components/icons-v2-generated'
+
+// icon-buttons variant (e.g. list pages)
 <PageActions
   variant="icon-buttons"
   actions={[
     { label: 'Add Script', onClick: handleAdd, icon: <PlusCircleIcon size={24} /> },
-    { label: 'Edit Categories', onClick: handleEdit, icon: <ColorsIcon size={24} /> },
   ]}
 />
 
-// menu-primary with split button and overflow menu
+// menu-primary variant with split button and submenu
 <PageActions
   variant="menu-primary"
   actions={[
@@ -42,7 +44,6 @@ Storybook stories file for the `PageActions` component, documenting all interact
       variant: 'outline',
       submenu: [
         { id: 'cmd', label: 'CMD', onClick: openCmd, icon: <TerminalIcon size={24} /> },
-        { id: 'powershell', label: 'Power Shell', onClick: openPs, icon: <TerminalIcon size={24} /> },
       ],
     },
   ]}
@@ -50,11 +51,10 @@ Storybook stories file for the `PageActions` component, documenting all interact
     {
       items: [
         { id: 'edit', label: 'Edit Device', onClick: handleEdit, icon: <PenEditIcon size={24} /> },
-        { id: 'delete', label: 'Delete Device', onClick: handleDelete, icon: <TrashIcon size={24} /> },
       ],
     },
   ]}
 />
 ```
 
-> **Tip:** Use `PageActions` via the `headerActions` prop on `PageContainer` for consistent page-level layouts across the Flamingo platform.
+Pair with `PageContainer`'s `headerActions` prop for consistent page-level layouts. See the full source at [`PageActions.stories.tsx`](https://github.com/flamingo-stack/openframe-oss-lib/blob/main/PageActions.stories.tsx).

package/src/stories/.PageContainer.stories.md

@@ -1,25 +1,18 @@
-<!-- source-hash: f72131cedcde7906c303bc3ea8538959 -->
-Storybook stories for the `PageContainer` layout component, covering legacy and advanced usage variants including list, detail, form, and content page layouts.
+<!-- source-hash: 6f5a95b06338851dcc16b8ce6b05192a -->
+Storybook stories for the `PageContainer` layout component, covering legacy usage patterns and all advanced variants (list, detail, form, content) with header and padding configurations.
 
 ## Key Components
 
-- **`Legacy`** — Basic container with full-width background and no structured header
-- **`LegacyCustomBackground`** / **`LegacyContentWidthBackground`** — Legacy mode with custom background and content-width options
-- **`ListPage`** / **`ListPageMultipleActions`** — List variant with title, subtitle, and action buttons
-- **`DetailPage`** / **`DetailPageWithActions`** — Detail variant with back button navigation and optional actions
-- **`FormPage`** — Form variant with cancel/save/publish actions
-- **`ContentPage`** — Generic content layout variant
-- **`CustomHeaderContent`** / **`WithHeaderActions`** / **`HiddenHeader`** — Header customization stories
-- **`WithPaddingAndBackground`** — Demonstrates `padding` and `background` prop combinations
-
-## Storybook Controls
-
-| Control | Options |
-|---------|---------|
-| `variant` | `list`, `detail`, `form`, `content` |
-| `padding` | `none`, `sm`, `md`, `lg` |
-| `background` | `default`, `card`, `transparent` |
-| `showHeader` | `boolean` |
+- **`Legacy`** — Basic container with full-width background using className-based styling
+- **`LegacyCustomBackground`** / **`LegacyContentWidthBackground`** — Legacy mode with custom background and scoped content-width background
+- **`ListPage`** / **`ListPageMultipleActions`** — List variant with title, subtitle, and one or more action buttons
+- **`DetailPage`** / **`DetailPageWithActions`** — Detail variant with back button and optional action buttons
+- **`FormPage`** — Form variant with cancel back button and draft/publish actions
+- **`ContentPage`** — Generic content variant with title
+- **`CustomHeaderContent`** — List variant using a fully custom `headerContent` ReactNode
+- **`WithHeaderActions`** — List variant combining `headerActions` slot with standard `actions` array
+- **`HiddenHeader`** — Content variant with `showHeader: false`
+- **`WithPaddingAndBackground`** — Demonstrates `padding` (`lg`) and `background` (`card`) props
 
 ## Usage Example
 
@@ -30,21 +23,33 @@ Storybook stories for the `PageContainer` layout component, covering legacy and
   title="Devices"
   subtitle="24 devices found"
   actions={[
-    { label: 'Add Device', onClick: handleAdd, icon: <Plus />, variant: 'primary' }
+    { label: 'Add Device', onClick: handleAdd, icon: <Plus className="w-5 h-5" />, variant: 'accent' },
   ]}
 >
-  <DeviceTable />
+  <DeviceList />
 </PageContainer>
 
 // Detail page with back navigation
 <PageContainer
   variant="detail"
   title="Device Details"
+  subtitle="MacBook Pro — Online"
   backButton={{ label: 'Back to Devices', onClick: handleBack }}
   actions={[
-    { label: 'Delete', onClick: handleDelete, variant: 'outline' }
+    { label: 'Delete', onClick: handleDelete, icon: <Trash2 className="w-5 h-5" />, variant: 'outline' },
   ]}
 >
-  <DeviceDetails />
+  <DeviceDetail />
 </PageContainer>
-```
+```
+
+## Configurable Controls
+
+| Prop | Type | Options |
+|---|---|---|
+| `variant` | select | `list`, `detail`, `form`, `content` |
+| `padding` | select | `none`, `sm`, `md`, `lg` |
+| `background` | select | `default`, `card`, `transparent` |
+| `showHeader` | boolean | `true` / `false` |
+
+**Source:** [`PageContainer.stories.tsx`](https://github.com/flamingo-stack/openframe-oss-lib/blob/main/PageContainer.stories.tsx)

package/src/stories/.PageLayout.stories.md

@@ -1,60 +1,43 @@
-<!-- source-hash: 3e5784b9b627d4143a0bac991ef6fb48 -->
-Storybook stories for the `PageLayout` component, covering all major layout variants including title-only, subtitle/image combinations, mobile responsive behavior, and action button configurations.
+<!-- source-hash: b09fa95f839417d0e19c0699fdf0b67c -->
+Storybook stories for the `PageLayout` component, covering layout variants including title-only, subtitle/image combinations, mobile responsive behavior, and action button configurations.
 
 ## Key Components
 
 | Export | Description |
-|--------|-------------|
-| `TitleOnly` | Minimal header with title and content only |
-| `WithSubtitleAndImage` | Full organization detail header with back button, thumbnail, subtitle, and icon-button actions |
-| `MobileActionsMenu` | Same as `WithSubtitleAndImage` at mobile viewport — actions collapse to `…` dropdown |
-| `WithSubtitleOnly` | Title + one-line context note with primary-button actions |
-| `WithImageOnly` | Branded entity header without a subtitle line |
-| `WithSelector` | Desktop tab selector (table/grid toggle) rendered before action buttons |
-| `WithSelectorMobile` | `WithSelector` at mobile viewport — selector hidden, only `…` dropdown remains |
-| `LongTitleTruncates` | Verifies ellipsis truncation when title/subtitle overflow the header |
+|---|---|
+| `TitleOnly` | Baseline header with title and content, no extras |
+| `WithSubtitleAndImage` | Full org detail page with thumbnail, subtitle, back button, and icon-button actions |
+| `MobileActionsMenu` | `WithSubtitleAndImage` at mobile viewport — actions collapse into a `…` dropdown |
+| `WithSubtitleOnly` | Title + one-line subtitle with primary-button actions, no image |
+| `WithImageOnly` | Branded entity header with thumbnail, no subtitle |
+| `WithSelector` | Adds a desktop-only `TabSelector` (table/grid toggle) before action buttons |
+| `WithSelectorMobile` | `WithSelector` at mobile viewport — selector is hidden, only `…` dropdown remains |
+| `LongTitleTruncates` | Validates ellipsis truncation for overflowing titles and subtitles |
 
 ## Usage Example
 
 ```typescript
-// Minimal usage
+// Minimal title-only layout
 <PageLayout title="Devices">
   <Table data={devices} columns={columns} rowKey="id" />
 </PageLayout>
 
-// Full organization detail page
+// Full org detail layout with image, subtitle, back button, and actions
 <PageLayout
   title="TechFlow Solutions"
   subtitle="techflow.com • Software Development"
-  image={{ src: logoSrc, alt: 'TechFlow logo' }}
+  image={{ src: logoSrc, alt: 'TechFlow Solutions logo' }}
   backButton={{ label: 'Back to Organizations', onClick: handleBack }}
   actionsVariant="icon-buttons"
   actions={[
     { label: 'Archive Organization', onClick: handleArchive, variant: 'outline', icon: <BoxArchiveIcon size={24} /> },
-    { label: 'Edit Organization',    onClick: handleEdit,    variant: 'outline', icon: <PenEditIcon size={24} />    },
+    { label: 'Edit Organization',    onClick: handleEdit,    variant: 'outline', icon: <PenEditIcon size={24} /> },
   ]}
 >
   <Table data={devices} columns={columns} rowKey="id" />
 </PageLayout>
-
-// With desktop tab selector (hidden on mobile)
-<PageLayout
-  title="Devices"
-  actionsVariant="icon-buttons"
-  actions={[{ label: 'Add Device', onClick: fn(), variant: 'outline', icon: <PlusCircleIcon size={24} /> }]}
-  selector={
-    <TabSelector
-      value={view}
-      onValueChange={setView}
-      items={[
-        { id: 'table', label: '', icon: <TableCellIcon size={24} /> },
-        { id: 'grid',  label: '', icon: <GridLayoutIcon size={24} /> },
-      ]}
-    />
-  }
->
-  <Table data={devices} columns={columns} rowKey="id" />
-</PageLayout>
 ```
 
-**`actionsVariant` options:** `icon-buttons` (labeled outline buttons → `…` menu on mobile), `primary-buttons` (always visible primary buttons), `menu-primary` (menu trigger with primary style).
+**`actionsVariant` options:** `icon-buttons` (outline buttons that collapse to `…` on mobile) · `primary-buttons` (always visible) · `menu-primary`.
+
+**Source:** [`PageLayout.stories.tsx`](https://github.com/flamingo-stack/openframe-oss-lib/blob/main/PageLayout.stories.tsx)

package/src/stories/.PolicyConfigurationPanel.stories.md

@@ -0,0 +1,58 @@
+<!-- source-hash: 26e88f6d6986aabc12b20690300de3c7 -->
+Storybook stories for the `PolicyConfigurationPanel` component, demonstrating AI guardrails permission configuration UI in read-only and interactive edit modes.
+
+## Key Components
+
+| Export | Description |
+|---|---|
+| `ReadOnly` | Panel in view-only mode — approval levels rendered as static text, no dropdowns |
+| `EditMode` | Interactive story with per-policy and bulk category approval dropdowns; state updates mirror the OpenFrame guardrails editor hook |
+| `GroupedPolicySections` | Composes multiple `PolicyConfigurationPanel` instances under labeled group headings (e.g., "Device Management", "Data Access") |
+| `applyPolicyLevel` | Helper that immutably updates a single policy's `ApprovalLevel` within a category list |
+| `applyCategoryLevel` | Helper that bulk-applies an `ApprovalLevel` to every policy in a given category |
+
+**Sample fixture data** covers three device-action categories (`Device Actions`, `Remote Access`, `Scripts & Automation`) and one data-access category (`Read Access`), referencing tools such as `OPENFRAME_RMM`, `FLEET_MDM`, `MESHCENTRAL`, and `OSQUERY`.
+
+## Usage Example
+
+```typescript
+// Replicate the EditMode story locally
+import { useState } from 'react'
+import { PolicyConfigurationPanel } from '../components/features/policy-configuration-panel'
+import type { ApprovalLevel, PermissionCategory } from '../types/permissions'
+
+function GuardrailsTab({ categories }: { categories: PermissionCategory[] }) {
+  const [cats, setCats] = useState(categories)
+
+  return (
+    <PolicyConfigurationPanel
+      categories={cats}
+      editMode={true}
+      onPolicyPermissionChange={(categoryId, policyId, level) =>
+        setCats(prev =>
+          prev.map(c =>
+            c.id !== categoryId ? c : {
+              ...c,
+              policies: c.policies.map(p =>
+                p.id === policyId ? { ...p, approvalLevel: level } : p
+              ),
+            }
+          )
+        )
+      }
+      onCategoryPermissionChange={(categoryId, level) =>
+        setCats(prev =>
+          prev.map(c =>
+            c.id !== categoryId ? c : {
+              ...c,
+              policies: c.policies.map(p => ({ ...p, approvalLevel: level })),
+            }
+          )
+        )
+      }
+    />
+  )
+}
+```
+
+**Source:** [`PolicyConfigurationPanel.stories.tsx`](https://github.com/flamingo-stack/openframe-oss-lib/blob/main/PolicyConfigurationPanel.stories.tsx)

package/src/stories/.ProductReleaseCard.stories.md

@@ -0,0 +1,39 @@
+<!-- source-hash: 290738d76bac6ec31d0611cc77b0adc1 -->
+Storybook stories for `ProductReleaseCard`, covering the `product_release` doc type at two density variants (`sm` and `lg`) used across chat inline views and catalog/release pages.
+
+## Key Components
+
+| Export | Description |
+|---|---|
+| `ChatInlineSm` | Compact `sm` density card for inline chat display |
+| `ChatInlineSmWithVideoCover` | Compact `sm` card with `hasVideoCover` enabled |
+| `Large` | Rich `lg` density card with hero cover, version pill, changelog stats, and a 4-cell metadata grid footer |
+
+## Usage Example
+
+```typescript
+import { ProductReleaseCard } from '../components/chat/entity-cards'
+import { productReleaseSmProps, productReleaseLgProps } from './__fixtures__/chat-cards'
+import { makeAnchorProps } from './__fixtures__/chat-card-decorator'
+
+// Compact inline chat card
+<ProductReleaseCard
+  {...productReleaseSmProps}
+  size="sm"
+  anchorProps={makeAnchorProps('/releases/2-5-0')}
+/>
+
+// Rich catalog/release page card
+<ProductReleaseCard
+  {...productReleaseLgProps}
+  size="lg"
+  anchorProps={makeAnchorProps('/releases/2-5-0')}
+/>
+```
+
+## Notes
+
+- Both densities share a **flat prop signature** — no `item` wrapper object required.
+- The `lg` variant is intended for `/releases`, the DevCenter tab, and investor-update related-content sections.
+- Stories are wrapped in `ChatColumnDecorator` to simulate the chat column layout context.
+- Source: [`ProductReleaseCard.stories.tsx`](https://github.com/flamingo-stack/openframe-oss-lib/blob/main/ProductReleaseCard.stories.tsx)

package/src/stories/.ProgramCard.stories.md

@@ -0,0 +1,51 @@
+<!-- source-hash: abf8ccf174f6c325f8b6a86c8368e747 -->
+Storybook stories for the `ProgramCard` component, covering the three supported program doc types (`podcast`, `webinar`, `event`) at both `sm` (chat-dispatch) and `default` (catalog page) sizes.
+
+## Key Components
+
+| Export | Description |
+|---|---|
+| `ProgramCard` | Generic card component for program-type content entities |
+| `DEFAULT_PROGRAM_CONFIGS` | Pre-built safe minimum configs per doc type (`podcast`, `webinar`, `event`) |
+| `ChatColumnDecorator` | Storybook decorator that wraps stories in a chat column layout |
+| `podcastItem` / `webinarItem` / `eventItem` | Fixture data for each program type |
+
+## Stories
+
+| Story | Size | Notes |
+|---|---|---|
+| `PodcastSm` | `sm` | Chat-dispatch rendering for podcast cards |
+| `WebinarSm` | `sm` | Chat-dispatch rendering for webinar cards |
+| `EventSm` | `sm` | Chat-dispatch rendering for event cards |
+| `PodcastDefault` | `default` | Full density; used on the podcast catalog page, not inline in chat |
+
+## Usage Example
+
+```typescript
+import { ProgramCard } from '../components/chat/entity-cards'
+import { DEFAULT_PROGRAM_CONFIGS } from '../components/chat/entity-cards/program-card-defaults'
+
+// Minimal chat-safe rendering (sm size used by chat dispatch)
+<ProgramCard
+  config={DEFAULT_PROGRAM_CONFIGS.podcast}
+  item={podcastItem}
+  size="sm"
+  href={`/podcasts/${podcastItem.id}`}
+  target="_blank"
+  rel="noopener noreferrer"
+/>
+
+// Override config per type for full catalog rendering
+<ProgramCard
+  config={{ ...DEFAULT_PROGRAM_CONFIGS.podcast, ...customCatalogConfig }}
+  item={podcastItem}
+  size="default"
+  href={`/podcasts/${podcastItem.id}`}
+/>
+```
+
+> **Note:** `DEFAULT_PROGRAM_CONFIGS[type]` ships a safe minimum config for compact chat rendering. Embedders can override per type with a full catalog config via the `config` prop.
+
+## Source
+
+[`ProgramCard.stories.tsx`](https://github.com/flamingo-stack/openframe-oss-lib/blob/main/ProgramCard.stories.tsx)