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

package/src/components/features/.warning-block.md

@@ -0,0 +1,53 @@
+<!-- source-hash: f09cbac6cf5f4d4f2a1fcee7319cb108 -->
+A composable warning card component that renders a highlighted alert banner header followed by optional body content, built for the OpenFrame Design System (ODS).
+
+## Key Components
+
+### `WarningBlock`
+
+The primary export — a card-style container with two regions:
+
+- **Banner** — styled with ODS warning colors (`bg-ods-warning-secondary`, `text-ods-warning`), displays an optional icon and a title
+- **Body** — renders `children` below the banner; fully composable (text, `PathsDisplay` lists, command rows, etc.)
+
+### `WarningBlockProps`
+
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| `title` | `React.ReactNode` | — | Content rendered inside the warning banner header |
+| `icon` | `React.ReactNode` | `<AlertTriangle />` | Icon shown at banner start; pass `null` to hide |
+| `children` | `React.ReactNode` | — | Body content below the banner |
+| `className` | `string` | — | Extra classes for the outer card container |
+
+## Usage Example
+
+```typescript
+import { WarningBlock } from './warning-block'
+import { PathsDisplay } from './paths-display'
+
+// Basic usage
+<WarningBlock title="Configuration required before proceeding">
+  <p>Ensure all paths are set correctly before continuing.</p>
+</WarningBlock>
+
+// With custom icon and composed body
+<WarningBlock
+  title="New device detected — action needed"
+  icon={<ShieldAlert className="h-6 w-6" />}
+  className="my-4"
+>
+  <PathsDisplay paths={requiredPaths} />
+  <p>Run the setup command to register this device.</p>
+</WarningBlock>
+
+// Without icon
+<WarningBlock title="Deprecated endpoint in use" icon={null}>
+  <p>Migrate to the v2 API before the next release cycle.</p>
+</WarningBlock>
+```
+
+## Notes
+
+- Spacing follows the ODS scale: card padding `16px` / gap `12px`, banner padding `12px` / gap `16px`
+- `title` uses `text-h3` — responsive (`14px` mobile, `18px` from `md` up), bold by token default
+- Client component (`'use client'`) — safe for interactive React trees

package/src/components/features/ai-enrich/.AIEnrichSection.md

@@ -1,43 +1,42 @@
-<!-- source-hash: 3297a26442c5b70d119e373c4687b748 -->
-Reusable AI enrichment panel component that renders a full-featured UI section for triggering AI-powered data enrichment, displaying status feedback, confidence scores, warnings, and optional custom instructions.
+<!-- source-hash: b6e50dac118cc70766e1c84f14a927c5 -->
+Reusable React section component that renders a complete AI enrichment UI panel, including a trigger button, optional custom instructions textarea, status feedback, warnings, confidence scoring, and result actions.
 
 ## Key Components
 
 ### Interfaces
 
-| Interface | Purpose |
-|-----------|---------|
-| `ConfidenceField` | Defines a field with an optional confidence score for display |
-| `AIRequiredField` | Describes a required form field, its fill state, and display label |
-| `AIEnrichSectionProps` | Full prop contract for the `AIEnrichSection` component |
+- **`ConfidenceField`** — Describes a field with an optional confidence score (`label`, `key`, `confidence`).
+- **`AIRequiredField`** — Describes a field required before enrichment can run (`key`, `label`, `isFilled`). Unfilled fields are displayed as badges when the button is disabled.
+- **`AIEnrichSectionProps`** — Full prop surface for the section component, covering button state, status, warnings, layout variant, custom instructions, and action callbacks.
 
-### Component: `AIEnrichSection`
+### Component
 
-The main exported component. Renders a card-style panel with:
-
-- **Header** — Icon (defaults to `SparklesIcon`), title, and optional description
-- **Custom Instructions** (opt-in) — Controlled `<Textarea>` for user-provided AI focus hints, passed upstream to Claude via `buildEditorFocusBlock()`
-- **Action Buttons** — `AIEnrichButton` (primary) and optional cancel button during loading
-- **Disabled State** — Shows `disabledMessage` with badge-styled list of unfilled required fields
-- **Loading State** — Spinner with live `statusMessage`
-- **Results Section** — Success/error status indicator, confidence badge, `AIWarningsSection`, custom `children`, and a clear button
+- **`AIEnrichSection`** — The primary export. Renders a card-style panel containing:
+  - Icon + title + description header
+  - Optional controlled `<Textarea>` for editor-supplied AI focus instructions
+  - `AIEnrichButton` trigger (full-width)
+  - Optional cancel button (visible only during loading)
+  - Disabled state message with unfilled-field badges
+  - Loading spinner + status message
+  - Success/error result block with confidence badge, warnings (`AIWarningsSection`), slot for custom children, and a "Clear Results" button
 
 ## Usage Example
 
 ```typescript
+import { AIEnrichSection } from './AIEnrichSection'
+
 <AIEnrichSection
-  title="Enrich Asset"
-  description="Use AI to auto-fill missing asset details."
+  title="AI Enrichment"
+  description="Auto-fill fields using Claude."
   onEnrich={handleEnrich}
   loading={isLoading}
-  canEnrich={hasRequiredFields}
+  canEnrich={!!formData.version}
   status={enrichStatus}
-  statusMessage="Analyzing asset data..."
+  statusMessage={enrichMessage}
   overallConfidence={87}
   warnings={enrichWarnings}
   requiredFields={[
-    { key: 'version', label: 'Version', isFilled: !!formValues.version },
-    { key: 'vendor', label: 'Vendor', isFilled: !!formValues.vendor },
+    { key: 'version', label: 'Version', isFilled: !!formData.version },
   ]}
   showCustomInstructions
   customInstructions={instructions}
@@ -50,6 +49,6 @@ The main exported component. Renders a card-style panel with:
 
 ## Notes
 
-- Supports `'default'` and `'compact'` layout variants via the `variant` prop
-- `customInstructions` is fully controlled — the parent owns the string value
-- `requiredFields` drives both `canEnrich` gating and the unfilled-fields badge display
+- `canEnrich` and `disabled` are OR'd together — both must be falsy for the button to be active.
+- The custom instructions value is **fully controlled** by the parent; the component never owns it internally. The string is forwarded to the backend and injected into the Claude prompt via `buildEditorFocusBlock()`.
+- Supports `variant="compact"` for tighter padding in space-constrained layouts.

package/src/components/features/ai-enrich/.AIRequiredBadge.md

@@ -1,35 +1,36 @@
-<!-- source-hash: 8ed764a47cc7c014a7a0e2d2397b6e54 -->
-A React badge component that visually indicates fields required for AI enrichment, featuring a sparkles icon and ODS cyan styling with responsive sizing options.
+<!-- source-hash: 54e34158f258c13928a52d614d0189f7 -->
+A badge component that visually marks form fields or UI elements as required for AI enrichment, rendered with a cyan sparkle icon and "AI-required" label.
 
 ## Key Components
 
-- **AIRequiredBadge** - Main component that renders an inline badge with sparkles icon
-- **AIRequiredBadgeProps** - Interface defining className and size props
-- **SparklesIcon** - Imported icon component for visual enhancement
-- **cn** - Utility function for conditional class name merging
+### `AIRequiredBadgeProps`
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| `className` | `string` | — | Additional CSS classes |
+| `size` | `'sm' \| 'md'` | `'sm'` | Controls badge sizing and icon dimensions |
+
+### `AIRequiredBadge`
+A client-side React functional component that renders a pill-shaped badge using ODS flamingo cyan colors and a `SparklesIcon`. Icon size scales with the `size` prop (`12px` for `sm`, `14px` for `md`).
 
 ## Usage Example
 
 ```typescript
-import { AIRequiredBadge } from './components/ui/badges/AIRequiredBadge'
+import { AIRequiredBadge } from '@openframe-oss-lib/components'
 
-// Small inline badge (default)
+// Default small variant (inline with a label)
 <label>
-  Description
+  Company Name
   <AIRequiredBadge />
 </label>
 
-// Medium size variant
-<div className="form-section">
-  AI Content Field
-  <AIRequiredBadge size="md" />
-</div>
-
-// With custom styling
-<AIRequiredBadge 
-  size="sm" 
-  className="ml-4 opacity-80" 
-/>
+// Medium variant with custom class
+<AIRequiredBadge size="md" className="ml-4" />
 ```
 
-The component uses ODS (Open Design System) Flamingo cyan colors with 10% opacity background, includes a sparkles icon that scales with the badge size, and applies DM Sans font styling. The badge is designed to be placed inline next to form labels or field descriptions to clearly communicate AI functionality requirements.
+## Notes
+
+- Marked `'use client'` — compatible with Next.js App Router client boundaries.
+- Styling relies on ODS design tokens (`--ods-flamingo-cyan-base`, `bg-ods-flamingo-cyan/10`) — ensure the ODS token stylesheet is loaded in the consuming app.
+- Use `size="md"` for standalone/prominent placements; `size="sm"` (default) suits compact inline field labels.
+
+**Source:** [`flamingo-stack/openframe-oss-lib`](https://github.com/flamingo-stack/openframe-oss-lib)

package/src/components/features/ai-enrich/.AIStatusIndicator.md

@@ -1,44 +1,51 @@
-<!-- source-hash: 99dd713ce86aad3a5fa950334530599b -->
-A React component that displays AI operation status with visual indicators, confidence levels, and custom messaging for different AI processing states.
+<!-- source-hash: 3b10940f9d91c7107c1ed331709d076d -->
+Displays an AI processing status badge with optional confidence scoring, rendering a sparkles icon alongside state-aware labels and color theming for idle, loading, success, and error states.
 
 ## Key Components
 
-- **AIStatusIndicator**: Main component that renders status badges with sparkle icons
-- **AIStatus**: Type union defining four states: `'idle' | 'loading' | 'success' | 'error'`
-- **AIStatusIndicatorProps**: Interface for component props including status, confidence, message, and styling options
-- **statusConfig**: Configuration object mapping each status to colors, backgrounds, and default labels
+- **`AIStatus`** — Union type: `'idle' | 'loading' | 'success' | 'error'`
+- **`AIStatusIndicatorProps`** — Props interface accepting `status`, `confidence` (0–100), `message`, `showConfidence`, and `className`
+- **`statusConfig`** — Internal map of per-state colors, backgrounds, and default labels
+- **`AIStatusIndicator`** — Main exported component; animates the sparkles icon on `loading`, applies confidence-based color classes on `success`, and renders a bordered confidence badge when `showConfidence` is true
 
 ## Usage Example
 
 ```typescript
-import { AIStatusIndicator, AIStatus } from './AIStatusIndicator'
-
-function AIProcessingPanel() {
-  const [status, setStatus] = useState<AIStatus>('idle')
-  const [confidence, setConfidence] = useState<number>()
-
-  return (
-    <div className="space-y-4">
-      {/* Basic status indicator */}
-      <AIStatusIndicator status="loading" />
-      
-      {/* With confidence score */}
-      <AIStatusIndicator 
-        status="success" 
-        confidence={87}
-        message="Data enrichment complete"
-      />
-      
-      {/* Custom styling */}
-      <AIStatusIndicator 
-        status="error"
-        message="Processing failed"
-        showConfidence={false}
-        className="border border-red-200"
-      />
-    </div>
-  )
-}
+import { AIStatusIndicator } from './AIStatusIndicator'
+
+// Loading state
+<AIStatusIndicator status="loading" />
+
+// Success with confidence score
+<AIStatusIndicator
+  status="success"
+  confidence={87}
+  showConfidence={true}
+/>
+
+// Success with custom message and no confidence badge
+<AIStatusIndicator
+  status="success"
+  confidence={52}
+  message="Analysis complete"
+  showConfidence={false}
+/>
+
+// Error with custom message
+<AIStatusIndicator
+  status="error"
+  message="Enrichment failed"
+  className="mt-2"
+/>
 ```
 
-The component automatically handles visual states including loading animations, confidence-based color coding, and responsive badge styling. It integrates with the ODS design system and includes accessibility considerations through semantic markup.
+## Notes
+
+- Confidence badge (bordered pill) only renders when `status === 'success'` and `showConfidence` is `true`
+- Color classes for icon and label defer to `getConfidenceTextClass` on success, otherwise fall back to `statusConfig[status].color`
+- The sparkles icon pulses via `animate-pulse` during `loading`
+- Styling relies on ODS design tokens (e.g., `text-ods-flamingo-cyan`, `bg-ods-success/10`) and the shared `cn` utility
+
+## Source
+
+[`AIStatusIndicator.tsx` on GitHub](https://github.com/flamingo-stack/openframe-oss-lib/blob/main/AIStatusIndicator.tsx)

package/src/components/features/ai-enrich/.AIWarningsSection.md

@@ -1,37 +1,40 @@
-<!-- source-hash: ed447a370135951f5c09122a781e6d22 -->
-A React component that displays AI-generated warnings in a styled warning box with yellow theme and warning icon. The component conditionally renders only when warnings are present.
+<!-- source-hash: 39b9cc086c5ad9f1907000e44428e838 -->
+A client-side React component that renders a styled warning panel for displaying AI-generated warnings, returning `null` when no warnings are present.
 
 ## Key Components
 
-- **AIWarningsSection**: Main functional component that renders a warning box
-- **AIWarningsSectionProps**: TypeScript interface defining component props
-  - `warnings`: Array of warning strings to display
-  - `title`: Optional title (defaults to "AI Warnings")
-  - `className`: Optional additional CSS classes
+- **`AIWarningsSectionProps`** — Interface defining component props:
+  - `warnings: string[]` — Array of warning messages to display
+  - `title?: string` — Optional panel title (defaults to `'AI Warnings'`)
+  - `className?: string` — Optional additional CSS classes
+- **`AIWarningsSection`** — React functional component that renders a warning-styled card with a triangle alert icon, a configurable title, and a bulleted list of warning messages
 
 ## Usage Example
 
 ```typescript
 import { AIWarningsSection } from './AIWarningsSection'
 
-// Basic usage with warnings
-<AIWarningsSection 
+// Basic usage
+<AIWarningsSection
   warnings={[
-    "AI generated content may contain inaccuracies",
-    "Please verify technical details before implementation",
-    "Code examples should be tested in your environment"
-  ]} 
+    'This ticket may have incomplete information.',
+    'Resolution confidence is below threshold.',
+  ]}
 />
 
-// Custom title and styling
+// With custom title and className
 <AIWarningsSection
-  warnings={["Custom warning message"]}
-  title="Important Notice"
-  className="mb-4"
+  title="Review Required"
+  warnings={['Duplicate ticket detected.']}
+  className="mt-4"
 />
 
-// Component returns null when no warnings
-<AIWarningsSection warnings={[]} /> // Renders nothing
+// Returns null — nothing rendered
+<AIWarningsSection warnings={[]} />
 ```
 
-The component features a yellow warning theme with a triangular warning icon, responsive design using Tailwind CSS, and automatic list formatting with bullet points. It uses the `cn` utility for conditional class name merging and includes proper TypeScript typing for all props.
+## Notes
+
+- Returns `null` for empty or undefined `warnings` arrays, making it safe to render unconditionally
+- Styling uses ODS (OpenFrame Design System) tokens (`ods-warning`) for consistent theming
+- Uses [`cn`](https://github.com/flamingo-stack/openframe-oss-lib/blob/main/utils/cn.ts) utility for conditional class merging

package/src/components/features/ai-enrich/.ConfidenceBadge.md

@@ -1,36 +1,51 @@
-<!-- source-hash: 10d2f0223ed1e2be95e5d01124a512c1 -->
-A React component that displays AI confidence scores as styled badges with customizable appearance and content options.
+<!-- source-hash: a4dc71136bc1de976302794283813d31 -->
+A React badge component that visually displays an AI confidence score with dynamic color coding based on confidence level thresholds.
 
 ## Key Components
 
-- **ConfidenceBadge**: Main component that renders confidence levels as visually distinct badges
-- **ConfidenceBadgeProps**: Interface defining component configuration options
-- **sizeStyles**: Object mapping size variants to Tailwind CSS classes
+### `ConfidenceBadgeProps`
+
+| Prop | Type | Default | Description |
+|---|---|---|---|
+| `confidence` | `number` | — | Confidence score (0–100) |
+| `showLabel` | `boolean` | `true` | Show text label (e.g., "High", "Low") |
+| `showPercentage` | `boolean` | `true` | Show numeric percentage |
+| `size` | `'sm' \| 'md' \| 'lg'` | `'sm'` | Controls padding/sizing |
+| `className` | `string` | — | Additional CSS classes |
+
+### Confidence Utilities Used
+
+- `getConfidenceLevel` — maps score to level (`'none'`, `'low'`, `'medium'`, `'high'`)
+- `getConfidenceLabel` — returns display label string
+- `getConfidenceBorderClass` / `getConfidenceTextClass` / `getConfidenceBgClass` — return Tailwind classes for theming
+
+> **Note:** Returns `null` when `confidence` is `undefined` or resolves to level `'none'`.
 
 ## Usage Example
 
 ```typescript
-import { ConfidenceBadge } from './ConfidenceBadge'
+import { ConfidenceBadge } from '@openframe/ui'
 
-// Basic usage with confidence score
-<ConfidenceBadge confidence={85} />
+// Full badge with label and percentage
+<ConfidenceBadge confidence={87} />
 
-// Customized display options
-<ConfidenceBadge 
-  confidence={92} 
+// Percentage only, large size
+<ConfidenceBadge
+  confidence={52}
+  showLabel={false}
+  showPercentage={true}
   size="lg"
-  showLabel={true}
+/>
+
+// Label only, custom class
+<ConfidenceBadge
+  confidence={30}
   showPercentage={false}
   className="ml-2"
 />
 
-// Different confidence levels
-<ConfidenceBadge confidence={45} /> // Low confidence
-<ConfidenceBadge confidence={75} /> // Medium confidence  
-<ConfidenceBadge confidence={95} /> // High confidence
-
-// No badge rendered for undefined/invalid confidence
-<ConfidenceBadge confidence={undefined} /> // Returns null
+// Renders nothing — confidence level is 'none'
+<ConfidenceBadge confidence={undefined} />
 ```
 
-The component automatically determines styling (colors, borders, backgrounds) based on confidence level using utility functions. It supports three sizes (sm/md/lg) and conditionally renders labels and percentages. Returns null for invalid confidence values to prevent rendering empty badges.
+**Source:** [`ConfidenceBadge.tsx`](https://github.com/flamingo-stack/openframe-oss-lib/blob/main/ConfidenceBadge.tsx)

package/src/components/features/auth/.auth-benefits-panel.md

@@ -0,0 +1,48 @@
+<!-- source-hash: d553ccb9cfde28519e82f8bede63fcc0 -->
+Presentational marketing panel displayed alongside authentication forms, showing platform benefits with icons, a title, description, and a "learn more" CTA button.
+
+## Key Components
+
+### Interfaces
+
+- **`AuthBenefit`** — Shape for a single benefit item: `icon` (React node) and `label` (string)
+- **`AuthBenefitsPanelProps`** — Props for the panel: `title`, `description`, `benefits`, `learnMoreLabel`, `learnMoreUrl`, `className`
+
+### Exports
+
+- **`AuthBenefitsPanel`** — Main component; fully presentational with all content overridable via props. Ships with four default benefits (no card required, cancel anytime, 14-day free trial, no contract) and links to `flamingo.run`.
+
+## Usage Example
+
+```typescript
+import {
+  AuthBenefitsPanel,
+  AuthBenefit,
+} from './auth-benefits-panel'
+import { ShieldIcon } from '../icons'
+
+const customBenefits: AuthBenefit[] = [
+  { icon: <ShieldIcon />, label: 'SOC 2 Compliant' },
+  { icon: <ShieldIcon />, label: 'GDPR Ready' },
+]
+
+// Default content
+<AuthBenefitsPanel />
+
+// Custom content
+<AuthBenefitsPanel
+  title="Enterprise-grade MSP Platform"
+  description="Streamline your ops with AI-powered automation."
+  benefits={customBenefits}
+  learnMoreLabel="Explore Features"
+  learnMoreUrl="https://openframe.ai"
+  className="my-custom-class"
+/>
+```
+
+## Notes
+
+- All props are optional; sensible defaults are provided for standalone use
+- The "learn more" button opens in a new tab and renders the `OpenFrameLogo` as a left icon
+- Styled with ODS design tokens (`ods-bg`, `ods-text-primary`, `ods-border`) for consistent theming
+- Source: [`flamingo-stack/openframe-oss-lib`](https://github.com/flamingo-stack/openframe-oss-lib)

package/src/components/features/auth/.auth-branding.md

@@ -0,0 +1,51 @@
+<!-- source-hash: 65ed4b47533c0df4f7708bf27477619f -->
+Renders branded UI elements for OpenFrame authentication screens: the OpenFrame logo + wordmark and a "Powered by Flamingo" footer mark.
+
+## Key Components
+
+### `OpenFrameWordmark`
+
+Displays the OpenFrame logo icon alongside the "OpenFrame" wordmark text. Uses CSS custom properties for theming (`--color-accent-primary`, `--color-text-primary`).
+
+### `PoweredByFlamingo`
+
+Renders a "Powered by Flamingo" attribution footer. Accepts a `compact` prop to control logo sizing across breakpoints.
+
+### `PoweredByFlamingoProps`
+
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| `compact` | `boolean` | `false` | Keeps logo at 56×16px at all breakpoints; when `false`, grows to 83×24px on tablet and above |
+
+## Usage Example
+
+```typescript
+import { OpenFrameWordmark, PoweredByFlamingo } from './auth-branding'
+
+// Auth screen header
+function AuthLayout() {
+  return (
+    <div className="flex flex-col min-h-screen">
+      <header>
+        <OpenFrameWordmark />
+      </header>
+
+      {/* ... auth form content ... */}
+
+      <footer>
+        {/* Responsive logo (default) */}
+        <PoweredByFlamingo />
+
+        {/* Fixed small logo for compact layouts */}
+        <PoweredByFlamingo compact />
+      </footer>
+    </div>
+  )
+}
+```
+
+## Notes
+
+- This is a `'use client'` component (Next.js App Router).
+- Logo colors are driven entirely by CSS custom properties — no hardcoded values.
+- The `FlamingoLogoIcon` source aspect ratio is 416×120 (~3.47:1); explicit `w`/`h` classes prevent the SVG from being rendered as a square.

package/src/components/features/auth/.auth-shell.md

@@ -0,0 +1,51 @@
+<!-- source-hash: a29fa0a658bd895353b19e3ef8d172c2 -->
+Responsive two-column layout shell for OpenFrame authentication pages, providing a split-panel design with a form column and a marketing/benefits column on desktop, collapsing to a single centered column on mobile and tablet.
+
+## Key Components
+
+- **`AuthShell`** — Main layout component that renders the responsive shell
+- **`AuthShellProps`** — Interface defining the component's configurable slots:
+  - `tabs` — Optional tab selector (e.g. Sign Up / Login) rendered above the form
+  - `children` — Required main form content
+  - `benefits` — Optional marketing panel; defaults to `<AuthBenefitsPanel />`
+  - `footer` — Optional desktop-only footer pinned to the bottom-left of the form column
+  - `className` — Optional additional CSS class names
+
+## Layout Behavior
+
+| Breakpoint | Layout |
+|---|---|
+| Mobile / Tablet | Single column: tabs → form → benefits → powered-by |
+| Desktop (`lg`) | Two-column split: form (left) · marketing + wordmark (right) |
+
+The `of-auth-shell` class on the root element serves as a stable CSS hook for shell-level overrides (e.g. native mobile top safe-area inset padding).
+
+## Usage Example
+
+```typescript
+import { AuthShell } from './auth-shell'
+import { AuthTabs } from './auth-tabs'
+
+export default function LoginPage() {
+  return (
+    <AuthShell
+      tabs={<AuthTabs active="login" />}
+      footer={<a href="/signup">Back to Sign Up</a>}
+    >
+      <LoginForm />
+    </AuthShell>
+  )
+}
+```
+
+```typescript
+// With a custom benefits panel
+<AuthShell
+  benefits={<CustomMarketingPanel />}
+  className="my-custom-shell"
+>
+  <CreateOrganizationForm />
+</AuthShell>
+```
+
+**Source:** [`auth-shell.tsx`](https://github.com/flamingo-stack/openframe-oss-lib/blob/main/auth-shell.tsx)

package/src/components/features/auth/.back-to-login-link.md

@@ -0,0 +1,48 @@
+<!-- source-hash: 5b60813cbd189cd03facf7d2af11352d -->
+A client-side React component that renders a styled "Back to Login" text link used across authentication screens.
+
+## Key Components
+
+### `BackToLoginLink`
+
+A button styled as an underlined text link, designed for auth flow navigation.
+
+**Props (`BackToLoginLinkProps`):**
+
+| Prop | Type | Default | Description |
+|---|---|---|---|
+| `onClick` | `() => void` | — | Callback fired when the link is clicked |
+| `label` | `string` | `'Back to Login'` | Customizable link text |
+| `className` | `string` | — | Optional class overrides via `cn` utility |
+
+## Usage Example
+
+```typescript
+import { BackToLoginLink } from './back-to-login-link'
+
+function ForgotPasswordScreen() {
+  const handleBack = () => {
+    router.push('/login')
+  }
+
+  return (
+    <div>
+      <h1>Forgot Password</h1>
+      <BackToLoginLink onClick={handleBack} />
+
+      {/* With custom label and class */}
+      <BackToLoginLink
+        onClick={handleBack}
+        label="Return to Sign In"
+        className="text-ods-brand-primary"
+      />
+    </div>
+  )
+}
+```
+
+## Notes
+
+- Rendered as a `<button type="button">` to avoid unintended form submissions.
+- Applies `text-h4` and `text-ods-text-secondary` design tokens by default; fully overridable via `className`.
+- Source: [`flamingo-stack/openframe-oss-lib`](https://github.com/flamingo-stack/openframe-oss-lib)