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

package/src/stories/__fixtures__/.chat-card-decorator.md

@@ -0,0 +1,39 @@
+<!-- source-hash: 2dd85c4676b5b84547c130a41316a737 -->
+Shared Storybook utilities for rendering chat entity-card stories in an isolated, realistic chat-column context.
+
+## Key Components
+
+- **`ChatColumnDecorator`** — React wrapper component that reproduces the assistant message column layout (constrained `max-w-[420px]`, ODS background, padding) so entity-card stories render at their real dimensions without the full chat runtime.
+- **`makeAnchorProps`** — Factory that returns a `{ href, onClick }` pair satisfying card `*AnchorProps` interfaces. The `onClick` calls `preventDefault` to prevent iframe navigation in Storybook while preserving anchor semantics (hover, copy-link).
+
+## Usage Example
+
+```typescript
+import { ChatColumnDecorator, makeAnchorProps } from './chat-card-decorator'
+import type { Meta, StoryObj } from '@storybook/react'
+import { TicketCard } from './ticket-card'
+
+const meta: Meta<typeof TicketCard> = {
+  component: TicketCard,
+  decorators: [
+    (Story) => (
+      <ChatColumnDecorator>
+        <Story />
+      </ChatColumnDecorator>
+    ),
+  ],
+}
+export default meta
+
+export const Default: StoryObj<typeof TicketCard> = {
+  args: {
+    title: 'Printer not working',
+    anchorProps: makeAnchorProps('https://app.example.com/tickets/42'),
+  },
+}
+```
+
+## Notes
+
+- `ChatColumnDecorator` is a layout-only wrapper; it carries no runtime dependencies, making it safe to import in any `.stories.tsx` file.
+- `makeAnchorProps` is intentionally router-agnostic — swap `href` for any valid URL; the `onClick` stub is Storybook-only and should not be used in production card components.

package/src/stories/__fixtures__/.chat-cards.md

@@ -0,0 +1,57 @@
+<!-- source-hash: 3e21cadfb28786c642e3ad430a4c2445 -->
+Shared Storybook fixtures that supply realistic mock data for every chat entity-card docType in `CHAT_CARD_REGISTRY`, enabling designers to preview cards without running the chat runtime.
+
+## Key Components
+
+### Constants & Helpers
+
+- **`NOW` / `DAY`** — Fixed timestamp anchor (`2026-05-28`) and millisecond day unit used to compute relative dates
+- **`isoDaysAgo(days)`** — Utility that returns an ISO 8601 string N days before the anchor
+- **`SAMPLE_AUTHOR`** — Reusable author object with name, avatar, and job title
+
+### Exported Fixtures
+
+| Export | Type | Description |
+|---|---|---|
+| `githubCommitItem` | `GitHubActivityItem` | Commit activity card fixture |
+| `githubPullRequestItem` | `GitHubActivityItem` | Pull request card fixture |
+| `githubPrReviewItem` | `GitHubActivityItem` | PR review card fixture |
+| `slackMessageItem` | `SlackMessageItem` | Slack channel message fixture |
+| `hubspotTicketItem` | `HubspotTicketItem` | High-priority HubSpot ticket fixture |
+| `dataRoomDocItem` | `DataRoomDocCardItem` | Investor relations document fixture |
+| `openframeDocsMarkdownItem` | `DataRoomDocCardItem` | Knowledge base article fixture |
+| `financialKpiItem` | `GenericEntityCardItem` | ARR KPI card with badge and facts |
+| `capTableItem` | `GenericEntityCardItem` | SAFE note cap table entry |
+| `profitLossItem` | `GenericEntityCardItem` | Consolidated P&L card |
+| `balanceSheetItem` | `GenericEntityCardItem` | Month-end balance sheet card |
+| `cashFlowItem` | `GenericEntityCardItem` | Operating cash flow card |
+| `blogPostSummary` | `BlogPostSummary` | Featured engineering blog post |
+| `caseStudy` | `CaseStudy` | MSP customer success story with relations |
+| `customerInterview` | `CustomerInterview` | Video interview with transcript fields |
+
+## Usage Example
+
+```typescript
+import {
+  githubCommitItem,
+  hubspotTicketItem,
+  financialKpiItem,
+} from '@/stories/fixtures/chat-cards'
+
+// Use directly in a Storybook story
+export const HubSpotTicket: Story = {
+  args: {
+    item: hubspotTicketItem,
+    href: hubspotTicketItem.url,
+  },
+}
+
+// Or compose multiple fixtures into a feed story
+export const MixedFeed: Story = {
+  args: {
+    items: [githubCommitItem, hubspotTicketItem, financialKpiItem],
+  },
+}
+```
+
+> **Note:** Server-only fields (status timestamps, AI processing flags, view counts) are populated with type-correct placeholder values. The card components do not read these at render time, but the wire types require them for TypeScript compliance.

package/src/stories/auth/.CompleteAccount.stories.md

@@ -0,0 +1,36 @@
+<!-- source-hash: b6a4a529a05f32c27061254e5b7c0498 -->
+Storybook stories for the `CompleteAccountForm` component, covering two authentication flows — Sign Up and Accept Invitation — in both empty and pre-filled states.
+
+## Key Components
+
+- **`useAccountFields`** — Shared controlled-input hook managing `firstName`, `lastName`, `password`, and `confirmPassword` state, with built-in validation (min 8-char password, fields match and non-empty).
+- **`SignUpPage`** — Renders `CompleteAccountForm` inside `AuthShell` with a `TabSelector` (Sign Up / Login tabs) and a back action.
+- **`InvitationPage`** — Renders `CompleteAccountForm` inside `AuthShell` with a `BackToLoginLink` footer, custom title/subtitle, and no tab navigation.
+- **Exported Stories** — `SignUpEmpty`, `SignUpFilled`, `InvitationEmpty`, `InvitationFilled`.
+
+## Usage Example
+
+```typescript
+// Render the Sign Up variant with pre-filled fields
+export const SignUpFilled: Story = {
+  render: () => <SignUpPage filled />,
+}
+
+// Render the Invitation variant with empty fields
+export const InvitationEmpty: Story = {
+  render: () => <InvitationPage />,
+}
+```
+
+## Story Variants
+
+| Story | Flow | State |
+|---|---|---|
+| `SignUpEmpty` | Sign Up (with tabs) | Empty fields |
+| `SignUpFilled` | Sign Up (with tabs) | Pre-filled (Ada Lovelace) |
+| `InvitationEmpty` | Accept Invitation | Empty fields |
+| `InvitationFilled` | Accept Invitation | Pre-filled |
+
+Both flows share the `SSO_PROVIDERS` constant (`['google', 'microsoft']`) and the `useAccountFields` hook. `submitDisabled` is derived automatically — enabled only when all fields are valid.
+
+**Source:** [`CompleteAccount.stories.tsx`](https://github.com/flamingo-stack/openframe-oss-lib/blob/main/CompleteAccount.stories.tsx)

package/src/stories/auth/.CreateOrganization.stories.md

@@ -0,0 +1,52 @@
+<!-- source-hash: bbc2c85f9c89b1adef88e9610f8e5f3b -->
+Storybook stories for the `CreateOrganizationForm` auth component, covering empty, filled, error, and SSO states within a full-page `AuthShell` layout.
+
+## Key Components
+
+| Export | Type | Description |
+|---|---|---|
+| `Empty` | `Story` | Default state with empty fields, terms unchecked, and submit disabled |
+| `Filled` | `Story` | Pre-filled valid input with terms accepted and submit enabled |
+| `ErrorState` | `Story` | Validation error messages on email and organization name fields |
+| `SSO` | `Story` | SSO provider buttons replace standard submit; fields are disabled |
+| `CreateOrganizationPage` | Internal helper | Controlled wrapper composing `AuthShell`, `TabSelector`, and `CreateOrganizationForm` |
+
+## Usage Example
+
+```typescript
+// Render the Filled story directly in another Storybook file
+import { Filled } from './CreateOrganization.stories'
+
+export const MyStory = {
+  render: () => <Filled.render />,
+}
+```
+
+```typescript
+// Replicate the SSO story setup in a test or custom harness
+import { CreateOrganizationForm, AuthShell } from '../../components/features/auth'
+import type { AuthSsoProvider } from '../../components/features/auth'
+
+const providers: AuthSsoProvider[] = ['openframe', 'google', 'microsoft']
+
+<AuthShell tabs={<TabSelector ... />}>
+  <CreateOrganizationForm
+    email="user@example.com"
+    organizationName="Acme"
+    domain="acme"
+    domainSuffix=".openframe.ai"
+    ssoProviders={providers}
+    termsUrl="/terms"
+    privacyPolicyUrl="/privacy"
+    onSubmit={() => {}}
+  />
+</AuthShell>
+```
+
+## Notes
+
+- Stories are rendered inside `AuthShell` with `layout: 'fullscreen'` to accurately reflect the two-column desktop / stacked mobile responsive layout. Use the Storybook viewport toolbar to verify breakpoints.
+- Submit is gated on all three fields being non-empty **and** `agreedToTerms` being `true` — reflected in the `Empty` vs `Filled` stories.
+- The `Login` tab renders a placeholder panel; its implementation is deferred to a later step.
+
+**Source:** [`CreateOrganization.stories.tsx`](https://github.com/flamingo-stack/openframe-oss-lib/blob/main/CreateOrganization.stories.tsx)

package/src/stories/auth/.InviteLinkInvalid.stories.md

@@ -0,0 +1,21 @@
+<!-- source-hash: 5d2ca564a870738800ac02bcfae3e056 -->
+Storybook stories file for the `InviteLinkInvalidModal` component, rendering the UI state displayed when an invitation link is expired or invalid.
+
+## Key Components
+
+- **`meta`** — Storybook metadata configuring the story under the `Auth/Invite Link Invalid` title with fullscreen layout and autodocs enabled
+- **`Default`** — Single story rendering `InviteLinkInvalidModal` with a no-op `onBackToLogin` callback
+
+## Usage Example
+
+```typescript
+// Render the modal in isolation with a real navigation handler
+import { InviteLinkInvalidModal } from '../../components/features/auth'
+
+<InviteLinkInvalidModal onBackToLogin={() => router.push('/login')} />
+```
+
+## Notes
+
+- Both the close (`X`) button and the primary action button invoke `onBackToLogin`, redirecting users back to the login screen
+- Source: [`InviteLinkInvalid.stories.tsx`](https://github.com/flamingo-stack/openframe-oss-lib/blob/main/InviteLinkInvalid.stories.tsx)

package/src/stories/auth/.Login.stories.md

@@ -0,0 +1,32 @@
+<!-- source-hash: 14bde4c0074b074c3e3b634f7daf4229 -->
+Storybook stories for the `LoginForm` authentication component, demonstrating three states — empty, filled, and SSO — rendered inside a full-page `AuthShell` with tab navigation.
+
+## Key Components
+
+| Export | Type | Description |
+|--------|------|-------------|
+| `Empty` | `Story` | Login form with no email input; submit button disabled |
+| `Filled` | `Story` | Login form with a valid email; Continue button enabled |
+| `SSO` | `Story` | Login form with SSO provider buttons replacing the submit action |
+| `LoginPage` | Helper component | Wraps `LoginForm` in `AuthShell` with `TabSelector` (Sign Up / Login tabs), managing local email and tab state |
+
+## Usage Example
+
+```typescript
+// Render the Filled story manually in a test or custom harness
+import { Filled } from './Login.stories'
+
+// All three stories accept no args; state is managed internally
+<Filled.render />
+
+// Configure SSO providers directly via LoginPage internals
+const SSO_PROVIDERS: AuthSsoProvider[] = ['openframe', 'google', 'microsoft']
+// Passed as ssoProviders prop — replaces submit button with provider buttons
+```
+
+## Notes
+
+- Stories are `fullscreen` layout — use the Storybook **viewport toolbar** to verify responsive breakpoints (desktop two-column, tablet/mobile stacked).
+- `LoginPage` is a controlled wrapper: `email` and `tab` state live locally via `useState`; `onSubmit` and `onForgotPassword` are no-ops.
+- The Sign Up tab renders a placeholder directing users to the `Auth/Create Organization` story group.
+- Source: [`Login.stories.tsx`](https://github.com/flamingo-stack/openframe-oss-lib/blob/main/Login.stories.tsx)

package/src/stories/auth/.OpenFrameSso.stories.md

@@ -0,0 +1,58 @@
+<!-- source-hash: 2f6693db66b0dc2f845ae8bdd0016e75 -->
+Storybook stories for the OpenFrame SSO authentication screens, showcasing both Login and Sign Up flows within the `SsoAuthShell` layout using controlled, interactive form components.
+
+## Key Components
+
+| Export | Type | Description |
+|---|---|---|
+| `LoginEmpty` | `Story` | Login form with empty fields; submit disabled |
+| `LoginFilled` | `Story` | Login form pre-filled with email and password; submit enabled |
+| `SignUpEmpty` | `Story` | Sign Up form with empty fields; submit disabled |
+| `SignUpFilled` | `Story` | Sign Up form pre-filled with all valid fields; submit enabled |
+| `SsoLoginPage` | Helper component | Controlled wrapper for `OpenFrameSsoLoginForm` inside `SsoAuthShell` |
+| `SsoSignUpPage` | Helper component | Controlled wrapper for `OpenFrameSsoSignUpForm` inside `SsoAuthShell` |
+
+## Usage Example
+
+```typescript
+// Render the filled login story directly in Storybook
+import { LoginFilled } from './OpenFrameSso.stories'
+
+// Or compose the controlled helper in your own tests/previews
+import { useState } from 'react'
+import { OpenFrameSsoLoginForm, SsoAuthShell } from '../../components/features/auth'
+
+function MyLoginPreview() {
+  const [email, setEmail] = useState('')
+  const [password, setPassword] = useState('')
+
+  return (
+    <SsoAuthShell>
+      <OpenFrameSsoLoginForm
+        email={email}
+        password={password}
+        onEmailChange={setEmail}
+        onPasswordChange={setPassword}
+        onSubmit={() => {}}
+        onForgotPassword={() => {}}
+        submitDisabled={!email.trim() || !password}
+      />
+    </SsoAuthShell>
+  )
+}
+```
+
+## Story Validation Logic
+
+Both helper components derive `submitDisabled` locally — no external state management required:
+
+- **Login:** enabled when `email` is non-empty and `password.length > 0`
+- **Sign Up:** enabled when all five fields are filled, `password.length >= 8`, and `password === confirmPassword`
+
+## Notes
+
+- All `onSubmit` and `onForgotPassword` handlers are no-ops (`() => {}`) — stories are purely presentational
+- `SsoAuthShell` provides the full-screen centered layout: logo top, card centered, "Powered by Flamingo" footer
+- Stories are tagged `autodocs` for automatic Storybook documentation generation
+
+**Source:** [`OpenFrameSso.stories.tsx`](https://github.com/flamingo-stack/openframe-oss-lib/blob/main/OpenFrameSso.stories.tsx)

package/src/stories/auth/.PasswordReset.stories.md

@@ -0,0 +1,49 @@
+<!-- source-hash: dc8f807b21dfb0fd1ce3b5c2fc8184f5 -->
+Storybook stories for the `PasswordResetForm` component, demonstrating the full-page password reset flow inside `AuthShell` with two controlled states: empty fields and pre-filled matching passwords.
+
+## Key Components
+
+- **`PasswordResetPage`** — Internal render helper that wires up controlled state (`password`, `confirmPassword`) and derives `isValid` / inline error logic for the stories
+- **`Empty`** — Story showing the form with empty fields and submit disabled
+- **`Filled`** — Story showing the form with matching passwords pre-populated and submit enabled
+
+## Usage Example
+
+```typescript
+// Minimal controlled usage matching the story pattern
+import { AuthShell, BackToLoginLink, PasswordResetForm } from '../../components/features/auth'
+import { useState } from 'react'
+
+function PasswordResetPage() {
+  const [password, setPassword] = useState('')
+  const [confirmPassword, setConfirmPassword] = useState('')
+  const isValid = password.length >= 8 && password === confirmPassword
+
+  return (
+    <AuthShell footer={<BackToLoginLink onClick={() => {}} />}>
+      <PasswordResetForm
+        password={password}
+        confirmPassword={confirmPassword}
+        onPasswordChange={setPassword}
+        onConfirmPasswordChange={setConfirmPassword}
+        onSubmit={() => {}}
+        onCancel={() => {}}
+        onBackToLogin={() => {}}
+        submitDisabled={!isValid}
+        errors={{
+          confirmPassword:
+            confirmPassword && password !== confirmPassword
+              ? 'Passwords do not match'
+              : undefined,
+        }}
+      />
+    </AuthShell>
+  )
+}
+```
+
+**Validation logic:**
+- Submit is enabled only when `password.length >= 8` and both fields match
+- `confirmPassword` error is shown only after the user has typed in the confirm field and it diverges from `password`
+
+**Source:** [`PasswordReset.stories.tsx`](https://github.com/flamingo-stack/openframe-oss-lib/blob/main/PasswordReset.stories.tsx)

package/src/styles/ods-interaction-states.css

@@ -1,5 +1,37 @@
 /* Open Design System – Interaction Animations */
 
+/* ---------------------------------------------------------------------------
+   Pointer affordance (SSOT)
+
+   A native <button> resolves to `cursor: default`, and Tailwind's preflight
+   does not override it. Every clickable surface in the system was therefore
+   relying on an ad-hoc `cursor-pointer` class, which drifted: DS Buttons had
+   it, raw <button> cards/chips/marquee cells did not — so identical-looking
+   cards felt dead while <a>-based ones (browser default: pointer) did not.
+
+   One base rule instead of N call sites. Applies to every marquee, chip, card
+   hit layer and any future control, including ones not yet written.
+
+   Wrapped in :where() so the rule carries ZERO specificity — an element-level
+   selector would otherwise beat any single Tailwind `cursor-*` utility and
+   silently break intentional ones (`cursor-grab` drag handles, `cursor-default`
+   on an active tab) across all 9 platforms.
+   --------------------------------------------------------------------------- */
+:where(button:not(:disabled):not([aria-disabled='true'])),
+:where([role='button']:not([aria-disabled='true'])),
+:where(summary) {
+  cursor: pointer;
+}
+
+/* Deliberately NOT `label[for]`: most labels point at text inputs, where a
+   pointer cursor promises a click target that isn't one. Checkbox/radio labels
+   opt in explicitly at their call site. */
+
+:where(button:disabled),
+:where([aria-disabled='true']) {
+  cursor: not-allowed;
+}
+
 /* Typing indicator cursor pulse */
 @keyframes pulse-cursor {
   0%, 100% { opacity: 1; }

package/src/types/.announcement.md

@@ -1,51 +1,83 @@
-<!-- source-hash: 0b0425ffde370482e2a418e941619761 -->
-TypeScript type definitions for the announcement system, providing comprehensive interfaces for managing platform-wide announcements with rich customization options including icons, call-to-action buttons, and asset management.
+<!-- source-hash: fc87f22902c4f5a3379665b2e552d3b3 -->
+Defines TypeScript types, interfaces, and constants for the OpenFrame announcement system, covering database models, API request/response shapes, form data, component props, and utility types.
 
 ## Key Components
 
-### Core Database Models
-- **`Announcement`** - Main announcement entity; platform targeting via hydrated `announcement_platforms?: EntityPlatformAssoc[]` (no singular platform_id/platform)
-- **`AnnouncementAsset`** - File attachments linked to announcements (images, documents, etc.)
+### Core Interfaces
 
-### API Types
-- **`CreateAnnouncementData`** / **`UpdateAnnouncementData`** - Request payloads for CRUD operations
-- **`AnnouncementListResponse`** / **`AnnouncementResponse`** - Standardized API response formats with pagination
-- **`GetAnnouncementsOptions`** - Query parameters for filtering and sorting announcements
+| Interface | Purpose |
+|---|---|
+| `Announcement` | Full database model including CTA fields, icon props, and hydrated platform associations |
+| `AnnouncementAsset` | File attachment metadata linked to an announcement |
+| `AnnouncementResponse` | Wire shape for `GET /api/announcements/active` — nullable envelope |
+| `AnnouncementListResponse` | Paginated list response with optional platform/active filters |
 
-### Form & UI Types
-- **`AnnouncementFormData`** - Form-specific data structure with file uploads and JSON string fields
-- **`AnnouncementBarProps`** / **`AnnouncementFormProps`** / **`AnnouncementListProps`** - React component prop interfaces
+### CRUD Data Shapes
 
-### Configuration Types
-- **`AvailableSvgIcon`** / **`SvgIcon`** - Icon management for announcement branding
-- **`AVAILABLE_SVG_ICONS`** - Predefined icon library including OpenFrame, OpenMSP, Flamingo logos and Lucide icons
+| Interface | Purpose |
+|---|---|
+| `CreateAnnouncementData` | Payload for creating a new announcement |
+| `UpdateAnnouncementData` | Partial payload for updating an existing announcement |
+| `AnnouncementFormData` | Form state, including `icon_props` and `cta_icon_props` as JSON strings |
+| `GetAnnouncementsOptions` | Query parameters for listing announcements |
+
+### Component Props
+
+| Interface | Purpose |
+|---|---|
+| `AnnouncementBarProps` | Controls SSR seeding, preview mode, dismissibility, and CSS class |
+| `AnnouncementFormProps` | Admin create/edit form callbacks and available icon list |
+| `AnnouncementListProps` | List view with edit, delete, and toggle-active handlers |
+
+### Constants
+
+- **`ANNOUNCEMENT_CTA_DEFAULTS`** — Default CTA button colors (`#1A1A1A` background, `#FAFAFA` text), shared between the DAL and admin form.
+- **`AVAILABLE_SVG_ICONS`** — Registry of supported icon names (OpenFrame/platform logos + Lucide icons); `component` is resolved at runtime.
 
 ## Usage Example
 
 ```typescript
-// Creating a new announcement
+import type {
+  Announcement,
+  CreateAnnouncementData,
+  AnnouncementBarProps,
+  AnnouncementResponse,
+} from './announcement';
+import { ANNOUNCEMENT_CTA_DEFAULTS } from './announcement';
+
+// Creating an announcement payload
 const newAnnouncement: CreateAnnouncementData = {
-  title: "New Feature Release",
-  description: "Check out our latest OpenFrame capabilities",
-  background_color: "#FFC008",
-  icon_type: "svg",
-  icon_svg_name: "rocket",
-  platforms: ["openframe-platform-id"],
+  title: 'New Feature Released',
+  description: 'Check out the latest OpenFrame update.',
+  background_color: '#1A1A1A',
+  icon_name: 'rocket',
+  platforms: ['platform-uuid-1', 'platform-uuid-2'],
   is_active: true,
   cta_enabled: true,
-  cta_text: "Learn More",
-  cta_url: "https://openframe.ai/features",
-  cta_target: "_blank",
-  created_by: "admin-user-id"
+  cta_text: 'Learn More',
+  cta_url: 'https://openframe.ai/changelog',
+  cta_target: '_blank',
+  cta_button_background_color: ANNOUNCEMENT_CTA_DEFAULTS.background,
+  cta_button_text_color: ANNOUNCEMENT_CTA_DEFAULTS.text,
+  created_by: 'user-uuid',
 };
 
-// Querying announcements with filters
-const options: GetAnnouncementsOptions = {
-  platform: "openframe",
-  is_active: true,
-  page: 1,
-  pageSize: 10,
-  sortBy: "created_at",
-  sortOrder: "desc"
+// Consuming the active announcement API response
+const response: AnnouncementResponse = await fetch('/api/announcements/active')
+  .then(r => r.json());
+
+if (response.announcement) {
+  console.log(response.announcement.title);
+}
+
+// AnnouncementBar in SSR mode — null signals "nothing to show"
+const barProps: AnnouncementBarProps = {
+  initialAnnouncement: response.announcement,
+  dismissible: true,
+  previewMode: false,
 };
-```
+```
+
+## Source
+
+[`announcement.ts`](https://github.com/flamingo-stack/openframe-oss-lib/blob/main/announcement.ts)

package/src/types/.blog.md

@@ -1,21 +1,36 @@
-<!-- source-hash: 8148802670f3c4122204649c0bccdbcd -->
-Type definitions for the Flamingo blog system, covering database models, form data, query options, SEO analysis, and filtering structures used across the blog feature.
+<!-- source-hash: bdd6fb9c095ed663f507ab9051e3c82b -->
+Type definitions for the blog domain, covering database models, API contracts, form data, query options, SEO analysis, and UI filtering structures for blog posts.
 
 ## Key Components
 
-| Export | Type | Description |
-|--------|------|-------------|
-| `BlogPost` | Interface | Core database model with SEO fields, relationships, and raw API response structure |
-| `BlogStatus` | Union Type | Post lifecycle states: `draft`, `ai_drafted`, `published`, `ai_published`, `scheduled`, `archived` |
-| `Platform` | Type | String alias for platform identifiers (fetched dynamically from DB) |
-| `CreateBlogPostData` | Interface | Payload shape for creating new posts including platforms, categories, and tags |
-| `UpdateBlogPostData` | Interface | Partial update payload for existing posts |
-| `GetBlogPostsOptions` | Interface | Query filters including pagination, sorting, platform, and search |
-| `BlogPostStats` | Interface | Dashboard aggregates with per-platform post counts |
-| `SEOAnalysisResult` | Interface | Scored SEO breakdown with keyword density, suggestions, errors, and warnings |
-| `BlogPagination` | Interface | Paginated response wrapping `BlogPostSummary` records |
-| `BlogPostSummary` | Interface | Lightweight post projection for listing pages |
-| `BlogFilters` | Interface | Filter options (categories + tags) for sidebar filtering UI |
+### Core Types
+- **`BlogStatus`** — Union literal type for post lifecycle states: `'draft'`, `'ai_drafted'`, `'published'`, `'ai_published'`, `'scheduled'`, `'archived'`
+- **`Platform`** — String alias for platform identifiers (fetched dynamically from the database)
+
+### Database Models
+- **`BlogPost`** — Full post shape including raw API response fields (`profiles`, `blog_post_platforms`, `blog_post_tags`) and normalized client-side relationships (`author`, `categories`, `tags`)
+- **`BlogAuthor`** — Author shape for blog posts; distinct from shared `EntityAuthor`; includes optional `slug` and `linkedinUrl` for SEO/schema usage
+- **`BlogPostPlatform`** — Aliased to `EntityPlatformAssoc` from `entity-platform.ts`; replaces the legacy flat junction shape
+- **`TagAssoc`** — Flat unified tag association shape; replaces the legacy nested `{ blog_tags: {...} }` pattern
+- **`BlogMediaAsset`**, **`BlogCategory`**, **`BlogTag`** — Supporting entity models
+
+### Form & Mutation Types
+- **`CreateBlogPostData`** — Required fields for creating a post, including `platforms`, `categories`, and `tags` arrays
+- **`UpdateBlogPostData`** — Partial version of create data for PATCH-style updates
+
+### Query & Stats
+- **`GetBlogPostsOptions`** — Filtering, pagination, and sorting parameters for list queries
+- **`BlogPostStats`** — Dashboard aggregate counts and `posts_by_platform` breakdown
+- **`BlogPagination`** / **`BlogPostSummary`** — Public-facing list and summary shapes
+
+### SEO
+- **`SEOAnalysisResult`** — Scored analysis output with `suggestions`, `errors`, and `warnings`
+- **`SEOAnalysisOptions`** — Optional keywords and flags for analysis configuration
+- **`BlogSEOAnalytics`** — Database row shape for persisted SEO analysis results
+
+### UI / Filtering
+- **`BlogFilterSidebarProps`**, **`BlogFilters`**, **`BlogFilterOption`** — Props and data shapes for the filter sidebar component
+- **`BlogCategoryForSidebar`** — Adapter type bridging `BlogCategory` to the `CategorySidebar` interface
 
 ## Usage Example
 
@@ -24,42 +39,30 @@ import type {
   BlogPost,
   CreateBlogPostData,
   GetBlogPostsOptions,
-  SEOAnalysisResult
-} from './blog'
+  BlogStatus,
+} from './blog';
 
-// Fetch options with filtering and pagination
+// Querying posts with filters
 const options: GetBlogPostsOptions = {
-  platform: 'flamingo',
+  platform: 'openframe',
   status: 'published',
   page: 1,
   pageSize: 10,
   sortBy: 'published_at',
   sortOrder: 'desc',
-  search: 'automation'
-}
+};
 
-// Create post payload
+// Creating a new post
 const newPost: CreateBlogPostData = {
   title: 'Getting Started with OpenFrame',
   slug: 'getting-started-openframe',
   content: '...',
-  author_id: 'user-123',
-  status: 'draft',
-  platforms: ['flamingo', 'openframe'],
-  categories: [1, 3],
-  tags: [5]
-}
+  author_id: 'user-uuid',
+  status: 'draft' as BlogStatus,
+  platforms: ['platform-uuid-1'],
+  categories: [3],
+  tags: [7, 12],
+};
+```
 
-// SEO result from analysis service
-const seo: SEOAnalysisResult = {
-  overall_score: 82,
-  title_score: 90,
-  meta_description_score: 75,
-  content_score: 85,
-  readability_score: 78,
-  keyword_density: { 'openframe': 0.03 },
-  suggestions: ['Add more internal links'],
-  errors: [],
-  warnings: ['Meta description slightly short']
-}
-```
+> **Source:** [`blog.ts`](https://github.com/flamingo-stack/openframe-oss-lib/blob/main/blog.ts)