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

package/src/stories/.Input.stories.md

@@ -1,55 +1,65 @@
-<!-- source-hash: 07edf12b9aece7d3d65330a955505e1f -->
-Storybook stories for the `Input` UI component, demonstrating all supported variants, adornments, states, and compositions.
+<!-- source-hash: 7985287071ae710bfda62ca359ff5865 -->
+Storybook stories for the `Input` UI component, covering all supported props, states, and adornment combinations for visual testing and documentation.
 
 ## Key Components
 
-| Export | Description |
-|--------|-------------|
+| Story | Description |
+|---|---|
 | `Default` | Basic input with placeholder text |
 | `WithEndAdornmentText` | Input with trailing text label (e.g., "Seconds") |
-| `WithStartAdornmentIcon` | Input with leading icon/emoji |
-| `WithBothAdornments` | Input with both start and end adornments (e.g., currency) |
+| `WithStartAdornmentIcon` | Input with leading icon or emoji |
+| `WithBothAdornments` | Combined start and end adornments (e.g., currency `$` / `USD`) |
 | `DisabledWithAdornments` | Disabled state with adornments |
-| `InvalidWithAdornments` | Error/invalid state with adornments |
-| `WithLabel` | Input with a visible label |
-| `WithLabelAndError` | Input with label and validation error message |
-| `SearchInput` | Controlled input with `SearchIcon` start adornment |
-| `Loading` | Input with loading spinner state |
+| `InvalidWithAdornments` | Error state with adornments |
+| `NumberWithUnit` | Numeric input with unit suffix |
+| `WithLabel` | Input with an accessible label |
+| `WithLabelAndError` | Label + inline error message |
+| `SearchInput` | Controlled search input with `SearchIcon` start adornment |
+| `Loading` | Input showing a loading spinner |
 | `WithButton` | Input paired with a submit `Button` |
-| `AllVariants` | Side-by-side showcase of all input states |
+| `AllVariants` | Side-by-side comparison of all visual states |
+| `ErrorState` | Full matrix of error/status variants: short, long-wrapping, success, and muted |
 
 ## Usage Example
 
 ```typescript
-// Basic input
-<Input placeholder="Enter text..." />
+// Controlled search input with icon adornment
+import { useState } from 'react';
+import { Input } from '../components/ui/input';
+import { SearchIcon } from '../components/icons-v2-generated/interface/search-icon';
 
-// With adornments
-<Input
-  placeholder="0.00"
-  startAdornment="$"
-  endAdornment="USD"
-/>
+function SearchField() {
+  const [value, setValue] = useState('');
+  return (
+    <Input
+      value={value}
+      onChange={(e) => setValue(e.target.value)}
+      placeholder="Search..."
+      startAdornment={<SearchIcon size={20} />}
+      loading={false}
+    />
+  );
+}
 
-// With label and error
+// Input with label, error, and end adornment
 <Input
-  label="Username"
-  placeholder="Enter text..."
-  error="This field is required"
+  label="Timeout"
+  defaultValue="90"
+  endAdornment="Seconds"
+  error="Value must be between 1 and 300"
 />
 
-// Controlled search input with icon
-const [value, setValue] = useState('');
+// Error status variants
 <Input
-  value={value}
-  onChange={(e) => setValue(e.target.value)}
-  placeholder="Search..."
-  startAdornment={<SearchIcon size={20} />}
+  label="Email"
+  defaultValue="ada@example.com"
+  error="Email is available"
+  errorVariant="success"
 />
+```
 
-// Disabled state
-<Input placeholder="90" endAdornment="Seconds" disabled />
+## Notes
 
-// Loading state
-<Input placeholder="Searching..." loading={true} startAdornment={<SearchIcon size={20} />} />
-```
+- `errorVariant` accepts `"success"` and `"muted"` in addition to the default error styling.
+- Long error messages wrap up to two lines before truncating with ellipsis.
+- Stories using stateful interactions (e.g., `SearchInput`, `WithButton`) use the `render` function pattern with `useState`.

package/src/stories/.InvestorUpdateCard.stories.md

@@ -0,0 +1,41 @@
+<!-- source-hash: 8a28e7f09b42f9392270067eafb565cd -->
+Storybook stories for the `InvestorUpdateCard` component, covering both compact chat-inline (`sm`) and full-size (`default`) display variants.
+
+## Key Components
+
+| Export | Type | Description |
+|--------|------|-------------|
+| `meta` | `Meta<typeof InvestorUpdateCard>` | Storybook metadata; registers stories under `Chat/EntityCards/InvestorUpdateCard` |
+| `ChatInlineSm` | `Story` | Compact `sm` size variant for inline chat display |
+| `Default` | `Story` | Standard `default` size variant |
+
+## Usage Example
+
+```typescript
+import { ChatInlineSm, Default } from './InvestorUpdateCard.stories'
+
+// Render the sm (chat-inline) variant
+<InvestorUpdateCard
+  update={investorUpdate}
+  href={`/investor-updates/${investorUpdate.slug}`}
+  size="sm"
+  target="_blank"
+  rel="noopener noreferrer"
+/>
+
+// Render the default (full-size) variant
+<InvestorUpdateCard
+  update={investorUpdate}
+  href={`/investor-updates/${investorUpdate.slug}`}
+  size="default"
+  target="_blank"
+  rel="noopener noreferrer"
+/>
+```
+
+## Notes
+
+- All stories are wrapped in `ChatColumnDecorator` to simulate a realistic chat column layout context.
+- The period badge (e.g. `"Mar 2025 - May 2025"`) is composed internally via `formatInvestorUpdatePeriod`.
+- Fixture data is sourced from [`__fixtures__/chat-cards`](https://github.com/flamingo-stack/openframe-oss-lib/blob/main/src/stories/__fixtures__/chat-cards.ts).
+- The `size` prop is the primary differentiator between stories: `sm` for compact chat use, `default` for full presentation.

package/src/stories/.MarqueeWall.stories.md

@@ -0,0 +1,53 @@
+<!-- source-hash: 349081fc6c3741b461a3b5d973f96c1d -->
+Storybook stories for the `MarqueeWall` component, demonstrating its scrolling wall variants including horizontal/vertical loops, synced pairs, plain mode, and reversed travel.
+
+## Key Components
+
+| Export | Type | Description |
+|--------|------|-------------|
+| `Horizontal` | `Story` | Default horizontal marquee with right-edge fade |
+| `Vertical` | `Story` | Vertical scrolling marquee with bottom fade inside a height-capped container |
+| `SyncedPair` | `Story` | Two walls sharing a single position driver via `useMarqueeSync` |
+| `Plain` | `Story` | Static layout opt-out — no motion, no fades |
+| `Reversed` | `Story` | Right-traveling marquee with dual-edge fades and custom fade sizing |
+| `Tile` | Component | Internal demo tile rendering an MSP tool label |
+| `TILES` | `string[]` | Sample content labels (MSP tool names) used across all stories |
+
+## Usage Example
+
+```typescript
+import { MarqueeWall, useMarqueeSync } from '../components/ui/marquee-wall'
+
+// Basic horizontal marquee
+<MarqueeWall
+  fade="right"
+  copyGap="var(--spacing-system-mf)"
+  className="w-full"
+  contentClassName="flex items-center gap-[var(--spacing-system-mf)]"
+>
+  <MyTile label="ConnectWise" />
+  <MyTile label="HaloPSA" />
+</MarqueeWall>
+
+// Pixel-locked sync across multiple walls
+function SyncedWalls() {
+  const sync = useMarqueeSync()
+  return (
+    <>
+      <MarqueeWall sync={sync} axis="x" className="w-full" contentClassName="flex items-center gap-4">
+        <MyTile label="Row A" />
+      </MarqueeWall>
+      <MarqueeWall sync={sync} axis="x" className="w-full" contentClassName="flex items-center gap-4">
+        <MyTile label="Row B" />
+      </MarqueeWall>
+    </>
+  )
+}
+```
+
+## Notes
+
+- Stories use ODS design tokens (`--spacing-system-mf`, `--color-bg-card`) for spacing and color — ensure the token stylesheet is loaded in Storybook.
+- `MarqueeWall` auto-statics when content fits the container or when `prefers-reduced-motion` is active.
+- `useMarqueeSync` is used in the `FreeTrialCTA` resolve-strip; `SyncedPair` reproduces that exact pattern.
+- Source: [`MarqueeWall.stories.tsx`](https://github.com/flamingo-stack/openframe-oss-lib/blob/main/MarqueeWall.stories.tsx)

package/src/stories/.MingoAiButton.stories.md

@@ -0,0 +1,31 @@
+<!-- source-hash: f5a16b4e2ffb17c391572edd22291edb -->
+Storybook stories for the `MingoAiButton` component, documenting the marketing-header AI launcher button in its realistic 72px unified header context.
+
+## Key Components
+
+| Export | Type | Description |
+|--------|------|-------------|
+| `meta` | `Meta<typeof MingoAiButton>` | Story configuration with decorator simulating the `Header` (`config.mingo`) layout context |
+| `Default` | `Story` | Full button with "Mingo AI" wordmark visible, sourced from `'flamingo'` |
+| `IconOnly` | `Story` | Mobile viewport variant showing icon-only display when wordmark hides below `md` breakpoint |
+
+## Usage Example
+
+```typescript
+import { MingoAiButton } from '../components/navigation/mingo-ai-button'
+
+// Render the button inside a 72px header (as seen in Header config.mingo)
+<div className="flex h-[72px] items-center justify-end border-b border-ods-border bg-ods-card">
+  <MingoAiButton source="flamingo" />
+</div>
+```
+
+## Notes
+
+- The decorator wraps every story in a `360px × 72px` header shell to accurately reproduce the left border divider and traveling accent edge light seen in the real `Header` component.
+- `source` controls the analytics/tracking origin passed to the launcher; accepts any string value via the `text` control in Storybook.
+- The `IconOnly` story uses `mobile1` viewport to demonstrate responsive hiding of the "Mingo AI" label below the `md` breakpoint — no code change required, purely viewport-driven via Tailwind responsive classes.
+
+## Source
+
+[`MingoAiButton.stories.tsx`](https://github.com/flamingo-stack/openframe-oss-lib/blob/main/MingoAiButton.stories.tsx)

package/src/stories/.MingoChatModals.stories.md

@@ -0,0 +1,47 @@
+<!-- source-hash: eeac5fa6d99d16a54c9e7e71931d0495 -->
+Storybook stories for the `RenameChatModal` and `ArchiveChatModal` chat management dialogs, providing interactive previews of both modal variants used in the Mingo chat interface.
+
+## Key Components
+
+| Export | Type | Description |
+|---|---|---|
+| `meta` | `Meta` | Storybook metadata under `Chat/MingoChatModals`; maps to Figma frames `7592:225962` (Rename) and `7592:226181` (Archive) |
+| `Rename` | `Story` | Interactive story for `RenameChatModal` — pre-seeded input, Cancel + Save actions |
+| `Archive` | `Story` | Interactive story for `ArchiveChatModal` — destructive confirmation dialog |
+
+## Usage Example
+
+```typescript
+// Simulate the Rename story in isolation
+import { RenameChatModal } from '../components/chat/mingo-chat-modals'
+
+<RenameChatModal
+  isOpen={open}
+  initialName="Troubleshooting Exchange Online connection issues"
+  onClose={() => setOpen(false)}
+  onSave={(name) => {
+    console.log('save', name)
+    setOpen(false)
+  }}
+/>
+
+// Simulate the Archive story in isolation
+import { ArchiveChatModal } from '../components/chat/mingo-chat-modals'
+
+<ArchiveChatModal
+  isOpen={open}
+  onClose={() => setOpen(false)}
+  onConfirm={() => {
+    console.log('archive confirmed')
+    setOpen(false)
+  }}
+/>
+```
+
+Both stories open with `isOpen={true}` by default and include a toggle button to re-open the modal after dismissal. The decorator wraps each story in a full-viewport `bg-ods-bg` container. Modals are built on `ModalV2` with an Azeret Mono title, `p-40`/`gap-24` spacing, and an in-house overlay.
+
+## Notes
+
+- Triggered from the chat header `⋯` menu and dialog-history row menus in production
+- `Archive` uses a destructive red action button; use with care in UI testing
+- Source: [`MingoChatModals.stories.tsx`](https://github.com/flamingo-stack/openframe-oss-lib/blob/main/MingoChatModals.stories.tsx)

package/src/stories/.MingoInfoCard.stories.md

@@ -0,0 +1,50 @@
+<!-- source-hash: 3ba205c8b3aec59e3fa2ed5249902509 -->
+Storybook stories file for `MingoInfoCard`, a horizontal info-row card component used in chat interfaces. Covers Figma-spec variants and optional-element permutations.
+
+## Key Components
+
+**Exported Stories**
+
+| Story | Description |
+|---|---|
+| `WithImage` | Card with a 40px avatar image as the leading media element |
+| `WithIcon` | Card with a boxed glyph (`MonitorIcon`) as the leading media element |
+| `WithoutStatus` | Icon variant with the status pill omitted |
+| `WithoutDescription` | Image variant with the description line omitted |
+| `WithoutMenu` | Card with the trailing overflow menu omitted |
+| `Clickable` | Full card with an `onClick` handler wired to the entire row |
+| `StatusVariants` | Side-by-side showcase of all four `Tag` palette variants: `success`, `warning`, `error`, `grey` |
+| `LongContentTruncates` | Validates text truncation on overflow for both title and description |
+
+**Supporting Fixtures**
+
+- `AVATAR_SRC` — Pravatar placeholder image URL used across image-based stories
+- `SAMPLE_MENU` — Two-item menu group (`Copy link`, `Remove`) reused across stories
+
+## Usage Example
+
+```typescript
+import { MingoInfoCard } from '../components/chat/mingo-info-card'
+import { MonitorIcon } from '../components/icons-v2-generated/devices/monitor-icon'
+
+// Basic card with icon and status
+<MingoInfoCard
+  title="Production Host"
+  description="All systems operational"
+  icon={<MonitorIcon size={24} />}
+  status={{ label: 'Online', variant: 'success' }}
+  menuGroups={[{
+    items: [
+      { id: 'copy', label: 'Copy link', icon: <Copy01Icon size={16} />, onClick: () => {} },
+      { id: 'remove', label: 'Remove', icon: <TrashIcon size={16} />, danger: true, onClick: () => {} },
+    ],
+  }]}
+  onClick={() => console.log('card clicked')}
+/>
+```
+
+> **Layout note:** `MingoInfoCard` is `w-full` and must be placed inside a block-level container. The Storybook canvas uses `layout: 'fullscreen'` rather than `centered` to allow the card to reflow correctly when the viewport is resized.
+
+## Source
+
+[`MingoInfoCard.stories.tsx`](https://github.com/flamingo-stack/openframe-oss-lib/blob/main/MingoInfoCard.stories.tsx)

package/src/stories/.MingoOnboardingCard.stories.md

@@ -1,42 +1,42 @@
-<!-- source-hash: 3d1f4ac24e4bcadba43f4bdf62347d8d -->
-Storybook stories for `MingoOnboardingCard`, the single-row card used in Mingo's chat empty-state list. Covers isolated prop variants and a full stacked list mirroring the Figma empty-state layout.
+<!-- source-hash: d66fd15df5fb4fcaec69fc58ba1c8b1a -->
+Storybook stories for `MingoOnboardingCard`, a single-row chat empty-state card component. Covers isolated prop variants and a full stacked list mirroring the Figma empty-state design (`7363:205938`).
 
 ## Key Components
 
 | Export | Description |
-|--------|-------------|
+|---|---|
 | `Default` | Base card with icon, title, slash command, and description |
 | `WithoutDescription` | Card omitting the description field |
 | `WithoutSlashCommand` | Card omitting the slash command badge |
-| `LongTitleTruncates` | Validates truncation behavior for long titles and commands |
+| `LongTitleTruncates` | Validates truncation behavior for overflowing text |
 | `Clickable` | Card with an `onClick` handler wired to console output |
-| `WithActions` | Card with multiple outline-chip action buttons (Recent, Search, Find) |
-| `ChipCommands` | Full stacked list of 13 cards driven by `SAMPLE_CHIP_COMMANDS`, mirroring Figma node `7363:205938` |
+| `WithActions` | Card with a row of outline-chip action buttons (Recent / Search / Find) |
+| `ChipCommands` | Full stacked list of 13 cards sourced from `SAMPLE_CHIP_COMMANDS`, mirroring the runtime empty-state |
+
+**`SAMPLE_CHIP_COMMANDS`** — internal fixture array defining icon names (resolved via `resolveIcon`), labels, slash commands, descriptions, and action chip labels for the `ChipCommands` story.
 
 ## Usage Example
 
 ```typescript
-// Single card with actions
+// Minimal card
 <MingoOnboardingCard
   icon={<CompassIcon size={16} />}
   title="ClickUp Roadmap"
   slashCommand="/roadmap"
   description="Public product roadmap with upcoming features and releases"
-  actions={[
-    { id: 'recent', label: 'Recent', onClick: () => {} },
-    { id: 'search', label: 'Search', onClick: () => {} },
-  ]}
 />
 
-// Stacked list — icons resolved from the shared registry
-const Icon = resolveOnboardingIcon('rocket-02')
+// Card with action chips
 <MingoOnboardingCard
-  icon={<Icon size={16} />}
-  title="Product Releases"
-  slashCommand="/release-notes"
-  description="OpenFrame version releases, changelogs, and update notes"
-  actions={[{ id: 'recent', label: 'Recent', onClick: () => {} }]}
+  icon={<CompassIcon size={16} />}
+  title="ClickUp Roadmap"
+  slashCommand="/roadmap"
+  description="Public product roadmap with upcoming features and releases"
+  actions={[
+    { id: 'recent', label: 'Recent', onClick: () => console.log('recent') },
+    { id: 'search', label: 'Search', onClick: () => console.log('search') },
+  ]}
 />
 ```
 
-> **Decorator context:** All stories wrap cards inside a `rounded-md` border container. The bottom border on each card acts as a 1-px divider between siblings, collapsed on the last row via `last:border-b-0`.
+Icons are sourced directly from `icons-v2-generated` for static stories, or resolved dynamically via `resolveIcon(iconName)` in the `ChipCommands` story to stay in sync with the chat runtime mapping. The decorator wraps each story in a `520px` container replicating the `rounded-md` / `border-ods-border` shell used in production.

package/src/stories/.MingoWelcome.stories.md

@@ -0,0 +1,41 @@
+<!-- source-hash: 240d97a568a9d22b85f350a706e05276 -->
+Storybook stories for the `MingoWelcome` component, covering the chat empty-state UI across its key display variants.
+
+## Key Components
+
+| Export | Description |
+|---|---|
+| `Default` | Full welcome state with Guide CTA promo card and yellow chip wired to `onStartGuideChat` |
+| `WithoutGuide` | Guide mode omitted — promo card and "Start Guide Chat" chip are suppressed |
+| `WithQuickActions` | Extends Default with additional quick-action chips appended after the built-in Guide chip |
+| `ReturningUser` | Returning user view — hides "New to OpenFrame?" notification, mutes Guide chip style, renders `MingoChatHistory` |
+| `Wide` | Desktop/wide-panel layout variant at 960px width |
+
+## Usage Example
+
+```typescript
+import { MingoWelcome } from '../components/chat/mingo-welcome'
+
+// New user — full onboarding state
+<MingoWelcome
+  onStartGuideChat={() => switchToGuideMode()}
+/>
+
+// Returning user with existing chat history
+<MingoWelcome
+  onStartGuideChat={() => switchToGuideMode()}
+  hasExistingChats={true}
+  dialogHistory={<MingoChatHistory dialogs={dialogs} ... />}
+  quickActions={[
+    { id: 'weekly', label: 'Weekly Log Summary' },
+  ]}
+/>
+```
+
+## Notes
+
+- All stories render inside a decorator that mimics the narrow drawer panel (`440×760px`) to validate `flex-1` centering and pinned chip row behavior.
+- `title`, `subtitle`, `promo`, `quickActions`, and `onStartGuideChat` controls are disabled in Storybook — only `hasExistingChats` is toggle-controllable via the controls panel.
+- Corresponds to Figma node `113:69208`.
+
+**Source:** [`MingoWelcome.stories.tsx`](https://github.com/flamingo-stack/openframe-oss-lib/blob/main/MingoWelcome.stories.tsx)

package/src/stories/.MobileNavPanel.stories.md

@@ -0,0 +1,52 @@
+<!-- source-hash: 58d9af4560f1028379a158cfe6c749c5 -->
+Storybook stories for the `MobileNavPanel` component, covering default chrome, custom styling, disabled footer states, and a short-viewport scrolling regression test.
+
+## Key Components
+
+| Export | Description |
+|---|---|
+| `Default` | Standard panel with auth footer (`Sign Up` button) using `bg-ods-card` chrome |
+| `CustomChrome` | Flamingo-style panel with custom `className` override via `config.className` |
+| `DisabledFooter` | TMCG-style panel with a disabled footer button and a `StatusBadge` "Coming Soon" indicator |
+| `ShortViewportLongList` | Regression story validating scroll + pinned footer behavior on short viewports (~660px tall) with 30 items |
+| `PanelHarness` | Internal render helper managing `isOpen` state with a toggle button |
+
+## Usage Example
+
+```typescript
+import { MobileNavPanel } from '../components/navigation/mobile-nav-panel'
+import type { MobileNavConfig } from '../types/navigation'
+
+const sections: MobileNavConfig['sections'] = [
+  {
+    title: 'Product',
+    items: [
+      { id: 'home', label: 'Home', href: '/', isActive: true },
+      { id: 'pricing', label: 'Pricing', href: '/pricing' },
+    ],
+  },
+]
+
+function MyNav() {
+  const [open, setOpen] = useState(false)
+  return (
+    <MobileNavPanel
+      isOpen={open}
+      config={{
+        sections,
+        onClose: () => setOpen(false),
+        footer: <Button className="w-full">Sign Up</Button>,
+      }}
+    />
+  )
+}
+```
+
+## Notes
+
+- All stories use `layout: 'fullscreen'` for realistic viewport simulation.
+- `PanelHarness` wraps each story to provide controlled open/close state without boilerplate.
+- `ShortViewportLongList` exists specifically to guard against regressions where the footer scrolls off-screen; test it at ~660px viewport height.
+- `config.className` accepts Tailwind classes to override default panel chrome per-product (OpenMSP vs Flamingo vs TMCG).
+
+**Source:** [`MobileNavPanel.stories.tsx`](https://github.com/flamingo-stack/openframe-oss-lib/blob/main/MobileNavPanel.stories.tsx)

package/src/stories/.Modal.stories.md

@@ -1,23 +1,23 @@
-<!-- source-hash: a814b843aeaf82abd73ff945b405ef13 -->
-Storybook stories for the `Modal` UI component, demonstrating two interaction patterns: a basic modal with header/content/footer, and a modal containing an `Autocomplete` dropdown with portal-aware rendering.
+<!-- source-hash: f30f001db374caa2804f9c6e873f3b59 -->
+Storybook stories for the `Modal` UI component, demonstrating default usage and a modal containing an `Autocomplete` dropdown.
 
 ## Key Components
 
-| Export | Description |
-|---|---|
-| `Default` | Basic modal story with open/close toggle, header, body text, and Cancel/Confirm footer buttons |
-| `WithAutocomplete` | Modal story embedding an `Autocomplete` multi-select with `overflow-visible` and a `ref` callback to capture the modal DOM node for portal containment |
+| Export | Type | Description |
+|---|---|---|
+| `Default` | `Story` | Basic modal with header, content, and footer sections |
+| `WithAutocomplete` | `Story` | Modal containing a multi-select `Autocomplete`, using `portalContainer` to avoid z-index conflicts |
 
 ## Usage Example
 
 ```typescript
-// Default modal pattern
+// Default modal
 <Modal isOpen={isOpen} onClose={() => setIsOpen(false)}>
   <ModalHeader>
     <ModalTitle>Modal Title</ModalTitle>
   </ModalHeader>
   <ModalContent className="px-6 py-4">
-    <p>Modal body content</p>
+    <p>Modal body content.</p>
   </ModalContent>
   <ModalFooter>
     <Button variant="outline" onClick={() => setIsOpen(false)}>Cancel</Button>
@@ -25,19 +25,19 @@ Storybook stories for the `Modal` UI component, demonstrating two interaction pa
   </ModalFooter>
 </Modal>
 
-// Autocomplete inside modal — capture modal ref to avoid z-index conflicts
+// Modal with Autocomplete — attach a ref to keep the dropdown in the modal's DOM tree
 const [modalElement, setModalElement] = useState<HTMLDivElement | null>(null)
-const modalRef = useCallback((node: HTMLDivElement | null) => {
-  setModalElement(node)
-}, [])
+const modalRef = useCallback((node: HTMLDivElement | null) => setModalElement(node), [])
 
-<Modal ref={modalRef} isOpen={isOpen} onClose={...} className="max-w-lg overflow-visible">
+<Modal ref={modalRef} isOpen={isOpen} onClose={() => setIsOpen(false)} className="max-w-lg overflow-visible">
   <ModalContent className="px-6 py-4">
     <Autocomplete
+      multiple
       options={options}
       value={selected}
       onChange={setSelected}
-      placeholder="Search..."
+      label="Industries"
+      placeholder="Search industries..."
     />
   </ModalContent>
 </Modal>
@@ -45,5 +45,8 @@ const modalRef = useCallback((node: HTMLDivElement | null) => {
 
 ## Notes
 
-- `WithAutocomplete` uses `useCallback` ref to capture the modal DOM node, enabling dropdown portals to render inside the modal's subtree and avoid z-index stacking issues.
-- Both stories manage `isOpen` via local `useState`, decoupled from Storybook's `args.isOpen` control after initial render.
+- Both stories manage open/close state locally via `useState`, keeping each story self-contained with a trigger `Button`.
+- The `WithAutocomplete` story captures the modal's DOM node via a `useCallback` ref. Pass `modalElement` as `portalContainer` to the `Autocomplete` if your implementation renders the dropdown in a portal, preventing z-index stacking issues.
+- The `isOpen` and `className` args are exposed as Storybook controls (`boolean` and `text` respectively).
+
+**Source:** [`Modal.stories.tsx`](https://github.com/flamingo-stack/openframe-oss-lib/blob/main/Modal.stories.tsx)

package/src/stories/.MspOrganizationCard.stories.md

@@ -0,0 +1,45 @@
+<!-- source-hash: 66b7b4649ed15eb53a24145addff0a43 -->
+Storybook stories for the `MspOrganizationCard` component, covering the AI Assistant welcome screen card that identifies the managing MSP organization.
+
+## Key Components
+
+| Export | Type | Description |
+|---|---|---|
+| `meta` | `Meta` | Storybook metadata — mounts under `Chat/AI Assistant Welcome Screen/MSP Organization`, centered in a 600px wrapper mirroring the Figma container |
+| `Default` | `Story` | Card with a square logo image, website label, and external-link anchor (new tab) |
+| `NoLogo` | `Story` | Fallback state — renders initials derived from `name` when no `logoUrl` is provided |
+| `WithCallback` | `Story` | Button fires `onOpenWebsite` callback instead of navigating via `href` |
+| `WithoutAction` | `Story` | Trailing button hidden when both `href` and `onOpenWebsite` are omitted |
+| `LongValues` | `Story` | Truncation behavior — long `name` and `website` values clamp to a single line |
+| `Loading` | `Story` | Renders `MspOrganizationCardSkeleton` as the placeholder shown while tenant data loads |
+
+## Usage Example
+
+```typescript
+import { MspOrganizationCard } from '../components/chat/msp-organization-card'
+import { MspOrganizationCardSkeleton } from '../components/chat/msp-organization-card-skeleton'
+
+// Anchor variant — opens organization website in a new tab
+<MspOrganizationCard
+  name="TechFlow Solutions"
+  website="www.techflow.com"
+  href="https://www.techflow.com"
+  logoUrl="https://cdn.example.com/techflow-logo.png"
+/>
+
+// Callback variant — handle navigation in-app
+<MspOrganizationCard
+  name="TechFlow Solutions"
+  website="www.techflow.com"
+  onOpenWebsite={() => openOrgPanel()}
+/>
+
+// Loading state while tenant info resolves
+<MspOrganizationCardSkeleton />
+```
+
+## Notes
+
+- The card is width-unconstrained and fills its parent; wrap it in a container to control width (Figma reference: node `1:5540`, `600×80px`).
+- The trailing external-link button renders **only** when either `href` or `onOpenWebsite` is provided.
+- Source: [`MspOrganizationCard.stories.tsx`](https://github.com/flamingo-stack/openframe-oss-lib/blob/main/MspOrganizationCard.stories.tsx)