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

package/src/types/.navigation.md

@@ -1,22 +1,26 @@
-<!-- source-hash: 4697d9aedf1aceab0cdd55dfb68dfa62 -->
-Defines shared TypeScript interfaces for all navigation-related components, providing a unified type contract for headers, sidebars, and mobile navigation panels.
+<!-- source-hash: 44e96f85909c48bc32bf34ccffcd283c -->
+Defines shared TypeScript interfaces for all navigation-related components in the OpenFrame UI library, providing a consistent contract for headers, sidebars, and mobile navigation panels.
 
 ## Key Components
 
 | Interface | Purpose |
-|-----------|---------|
+|---|---|
 | `NavigationItem` | Base interface for any nav item — supports links, dropdowns, badges, icons, and custom elements |
-| `HeaderConfig` | Full configuration for the top header including logo, nav items, actions, and mobile behavior |
-| `MobileNavConfig` | Configuration for grouped mobile navigation panels with optional footer |
-| `SlidingSidebarConfig` | Configuration for animated slide-in sidebars (left or right) |
-| `NavigationSidebarConfig` | Configuration for collapsible vertical sidebars with minimize support |
-| `NavigationSidebarItem` | Sidebar-specific nav item with section placement (`primary` / `secondary`) |
-| `UnifiedSidebarUser` | User identity shape (name, email, avatar, role) consumed by unified sidebar components |
+| `HeaderConfig` | Full configuration for the top header bar, including logo, nav items, actions, mobile menu, and Mingo AI integration |
+| `MobileNavConfig` | Sectioned navigation panel for mobile viewports |
+| `SlidingSidebarConfig` | Slide-in sidebar overlay with left/right positioning |
+| `NavigationSidebarConfig` | Collapsible vertical sidebar with minimized state support |
+| `NavigationSidebarItem` | Sidebar-specific nav item with unread counts and primary/secondary section grouping |
+| `UnifiedSidebarUser` | User identity data (name, email, avatar, role) surfaced in sidebar footers |
 
 ## Usage Example
 
 ```typescript
-import { NavigationItem, HeaderConfig } from './navigation'
+import {
+  NavigationItem,
+  HeaderConfig,
+  NavigationSidebarItem,
+} from '@openframe/oss-lib'
 
 const navItems: NavigationItem[] = [
   {
@@ -38,15 +42,23 @@ const navItems: NavigationItem[] = [
 ]
 
 const headerConfig: HeaderConfig = {
-  logo: {
-    element: <FlamingoLogo />,
-    href: '/',
-  },
-  navigation: {
-    items: navItems,
-    position: 'center',
-  },
+  logo: { element: <MyLogo />, href: '/' },
+  navigation: { items: navItems, position: 'center' },
+  mingo: { enabled: true, label: 'Mingo AI' },
   autoHide: true,
   backgroundColor: 'bg-ods-card',
 }
-```
+
+const sidebarItem: NavigationSidebarItem = {
+  id: 'inbox',
+  label: 'Inbox',
+  icon: <InboxIcon />,
+  path: '/inbox',
+  unreadCount: 5,
+  section: 'primary',
+}
+```
+
+## Source
+
+[`navigation.ts`](https://github.com/flamingo-stack/openframe-oss-lib/blob/main/navigation.ts)

package/src/types/.os.types.md

@@ -1,43 +1,42 @@
-<!-- source-hash: 6581d93b3edee981ded786a177e99959 -->
-Defines the centralized source of truth for operating system type metadata across the Flamingo platform, normalizing OS values from Fleet MDM and GraphQL into a unified structure.
+<!-- source-hash: 0d282217e56761b5e78fc0aa495cd0b1 -->
+Defines the centralized source of truth for operating system type metadata across the platform, normalizing OS values from Fleet MDM, OpenFrame RMM, and GraphQL sources into a unified structure.
 
 ## Key Components
 
-- **`OSTypeValues`** — Const enum-like object with `WINDOWS`, `MACOS`, and `LINUX` string literals
-- **`OSType`** — Union type derived from `OSTypeValues`
-- **`OSTypeDefinition`** — Interface describing a full OS entry: `id`, `label`, `value`, `icon`, `platformId`, and `aliases`
-- **`OS_TYPES`** — Primary export; array of `OSTypeDefinition` objects for all three platforms, including brand icons and alias lists for fuzzy matching
-- **`osLabels`** — Convenience record mapping each `OSType` to its display label
+| Export | Type | Description |
+|---|---|---|
+| `OSTypeValues` | `const` | Enum-like object with `WINDOWS`, `MACOS`, `LINUX` string constants |
+| `OSType` | `type` | Union type derived from `OSTypeValues` keys |
+| `OSTypeDefinition` | `interface` | Full OS metadata shape including id, label, icon, platformId, and aliases |
+| `OS_TYPES` | `OSTypeDefinition[]` | Master array of all OS definitions — primary source of truth |
+| `osLabels` | `Record<OSType, string>` | Simple lookup map from OS type to display label |
 
 ## Usage Example
 
 ```typescript
 import { OS_TYPES, OSTypeValues, osLabels } from './os.types'
 
-// Resolve an OS from an arbitrary string (e.g. from Fleet MDM)
-function resolveOS(raw: string) {
-  const normalized = raw.toLowerCase()
-  return OS_TYPES.find(os =>
-    os.aliases.includes(normalized)
-  )
-}
-
-const match = resolveOS('darwin')
-// match.id    → 'MACOS'
-// match.label → 'macOS'
-// match.platformId → 'darwin'
-
-// Render display label from known type
-const label = osLabels[OSTypeValues.WINDOWS]
-// → 'Windows'
-
-// Render the OS icon in a React component
-const OsIcon = match?.icon
-// <OsIcon className="w-4 h-4" />
+// Render OS list with icons
+OS_TYPES.forEach(({ label, icon: Icon, platformId }) => {
+  console.log(label, platformId) // 'macOS', 'darwin'
+  // <Icon /> → renders Apple/Windows/Linux logo
+})
+
+// Normalize an incoming OS string via aliases
+const raw = 'darwin'
+const matched = OS_TYPES.find(os =>
+  os.aliases.includes(raw.toLowerCase())
+)
+console.log(matched?.id) // 'MACOS'
+
+// Display label lookup
+console.log(osLabels[OSTypeValues.LINUX]) // 'Linux'
 ```
 
-## Notes
+## Alias Ordering
 
-- Aliases are **order-sensitive** — more specific strings (e.g. `'darwin'`) precede shorter ones (e.g. `'mac'`) to prevent false-positive matches
-- Linux aliases cover major distros (`ubuntu`, `debian`, `centos`, `fedora`, `arch`, etc.)
-- Icons are pulled from the internal `icons-v2-generated` brand logo set
+Aliases within each OS entry are ordered from most-specific to least-specific (e.g., `'darwin'` before `'mac'`, `'win32'` before `'win'`) to prevent false-positive matches during normalization lookups.
+
+## Source
+
+[`os.types.ts`](https://github.com/flamingo-stack/openframe-oss-lib/blob/main/os.types.ts)

package/src/types/.permissions.md

@@ -1,47 +1,61 @@
-<!-- source-hash: af20d3b479cf2b0ee00a77653fda6605 -->
-Defines TypeScript interfaces and types for managing AI tool permissions and approval workflows in the Flamingo MSP platform.
+<!-- source-hash: 4713ee3804f82217d5018f7251970e2d -->
+Defines TypeScript types and interfaces for the permission policy configuration system used in OpenFrame's AI tool authorization layer.
 
 ## Key Components
 
-- **ApprovalLevel**: Union type defining permission levels (`ALLOW`, `ASK_USER`, `ASK_TECHNICIAN`, `DENY`)
-- **PermissionPolicy**: Interface for individual tool command permission policies with approval levels
-- **PermissionCategory**: Interface for grouping related policies with expandable UI state
-- **PolicyConfigurationPanelProps**: Props interface for the permission configuration UI component
+| Export | Kind | Description |
+|--------|------|-------------|
+| `ApprovalLevel` | Type | Union of four authorization levels: `'ALLOW'`, `'ASK_USER'`, `'ASK_TECHNICIAN'`, `'DENY'` |
+| `PermissionPolicy` | Interface | A single policy rule binding a command pattern and tool to an approval level |
+| `PermissionCategory` | Interface | Logical grouping of related `PermissionPolicy` entries, optionally with a React icon node |
+| `PolicyConfigurationPanelProps` | Interface | Props contract for the panel component that renders and edits permission categories |
 
 ## Usage Example
 
 ```typescript
-import { ApprovalLevel, PermissionPolicy, PermissionCategory } from './permissions';
-
-// Define a permission policy for a specific tool command
-const sshPolicy: PermissionPolicy = {
-  id: 'ssh-001',
-  name: 'SSH Connection',
-  naturalKey: 'ssh_connect',
-  commandPattern: 'ssh *',
-  toolName: 'terminal',
-  approvalLevel: 'ASK_TECHNICIAN'
+import {
+  ApprovalLevel,
+  PermissionCategory,
+  PolicyConfigurationPanelProps,
+} from "./permissions";
+
+const category: PermissionCategory = {
+  id: "file-ops",
+  name: "File Operations",
+  policies: [
+    {
+      id: "policy-delete",
+      name: "Delete Files",
+      naturalKey: "file.delete",
+      commandPattern: "rm *",
+      toolName: "shell",
+      approvalLevel: "ASK_TECHNICIAN",
+    },
+    {
+      id: "policy-read",
+      name: "Read Files",
+      naturalKey: "file.read",
+      commandPattern: "cat *",
+      toolName: "shell",
+      approvalLevel: "ALLOW",
+    },
+  ],
 };
 
-// Group policies into categories
-const networkCategory: PermissionCategory = {
-  id: 'network',
-  name: 'Network Operations',
-  icon: <NetworkIcon />,
-  configurationsCount: 5,
-  globalPermission: 'ASK_USER',
-  isExpanded: false,
-  policies: [sshPolicy]
-};
-
-// Handle permission level changes
-const handlePermissionChange = (
-  categoryId: string, 
-  policyId: string, 
-  level: ApprovalLevel
-) => {
-  console.log(`Updated ${policyId} to ${level}`);
+const panelProps: PolicyConfigurationPanelProps = {
+  categories: [category],
+  editMode: true,
+  onPolicyPermissionChange: (categoryId, policyId, level: ApprovalLevel) => {
+    console.log(`Policy ${policyId} in ${categoryId} → ${level}`);
+  },
+  onCategoryPermissionChange: (categoryId, level: ApprovalLevel) => {
+    console.log(`All policies in ${categoryId} → ${level}`);
+  },
 };
 ```
 
-This permission system enables granular control over AI tool capabilities, ensuring appropriate approval workflows for different security levels and operational contexts.
+## Notes
+
+- `PermissionCategory` is **pure data** — expansion and bulk-selection UI state belongs to the consuming panel component.
+- The optional `icon` field accepts a `React.ReactNode`; the panel falls back to a shield icon when omitted.
+- `PermissionPolicy.toolName` is typed as `ToolType` (imported from [`tool.types`](https://github.com/flamingo-stack/openframe-oss-lib/blob/main/tool.types.ts)), ensuring only known tool identifiers are accepted.

package/src/types/.platform.md

@@ -1,42 +1,58 @@
-<!-- source-hash: a990391bb43e6e44b547ca32debddb41 -->
-Defines unified platform types used across announcements, blog posts, and platform configuration throughout the Flamingo/OpenFrame stack.
+<!-- source-hash: 6fe91cd4e4ecc57d7e54f4b5392577c6 -->
+Defines unified platform types used across announcements, blog posts, and platform configuration throughout the Flamingo Stack ecosystem.
 
 ## Key Components
 
 | Export | Type | Description |
 |--------|------|-------------|
 | `PlatformName` | `type` | Union of all valid platform identifiers (e.g. `'flamingo'`, `'openframe'`, `'openmsp'`) |
-| `PlatformRecord` | `interface` | Full database model from the `platforms` table, including chat/RAG wiring fields |
-| `PlatformConfig` | `interface` | API-facing configuration shape with display metadata (color, icon, description) |
-| `PlatformOption` | `interface` | Minimal `value`/`label` pair for dropdowns and filter UIs |
-| `PlatformFilter` | `type` | Extends `PlatformName` with an `'all'` wildcard for filter contexts |
-| `LegacyPlatform` | `type` | Backward-compatible alias scoped to the original three platforms |
-| `PlatformStats` | `interface` | Aggregate counts of announcements and blog posts per platform |
+| `PlatformRecord` | `interface` | Full database model from the `platforms` table, including chat wiring, activity tracking, and content scoping flags |
+| `PlatformConfig` | `interface` | API-facing configuration shape with display metadata (color, icon, label) |
+| `PlatformOption` | `interface` | Lightweight `{ value, label }` shape for dropdowns and filter UIs |
+| `PlatformFilter` | `type` | Extends `PlatformName` with `'all'` for filter contexts |
+| `LegacyPlatform` | `type` | Backward-compatible alias for the original three platforms |
+| `PlatformStats` | `interface` | Aggregated content counts per platform for reporting |
 
 ## Usage Example
 
 ```typescript
-import type { PlatformName, PlatformRecord, PlatformFilter } from './platform';
-
-// Type-safe platform reference
+import type {
+  PlatformName,
+  PlatformRecord,
+  PlatformFilter,
+  PlatformOption,
+} from './platform';
+
+// Narrow to a valid platform
 const platform: PlatformName = 'openframe';
 
-// Filter selection (includes 'all' wildcard)
-const filter: PlatformFilter = 'all';
-
-// Working with a database record
-const record: PlatformRecord = {
-  id: 'uuid-123',
-  name: 'flamingo',
-  display_name: 'Flamingo',
-  is_active: true,
-  is_internal: false,
-  chat_source_id: 'src-abc',
-  chat_source_rag_tables_version: 3,
-  chat_enabled: true,
-  created_at: '2024-01-01T00:00:00Z',
-  updated_at: '2024-01-01T00:00:00Z',
-};
+// Filter UI options
+const options: PlatformOption[] = [
+  { value: 'all', label: 'All Platforms' },
+  { value: 'flamingo', label: 'Flamingo' },
+  { value: 'openframe', label: 'OpenFrame' },
+];
+
+// Type-safe filter handler
+function handleFilter(filter: PlatformFilter) {
+  if (filter === 'all') {
+    // return all records
+  } else {
+    // return records for `filter` platform
+  }
+}
+
+// Check platform content scoping from a DB record
+function isUniversalViewer(record: PlatformRecord): boolean {
+  return record.serves_all_content;
+}
 ```
 
-> `chat_source_rag_tables_version` is bumped by the `replace_chat_source_rag_tables` RPC and drives cross-Lambda cache invalidation — do not modify this field manually.
+> **Note on `PlatformRecord` flags:**
+> - `serves_all_content` — when `true`, content DALs return rows for all platforms (read by `getPlatformContentScopeMode`)
+> - `tracks_activity` — when `false`, skips activity tracking and HubSpot sync for that platform's principals
+> - `chat_enabled` — platform-wide kill switch for the Ask AI / chat surface
+
+## Source
+
+[`platform.ts`](https://github.com/flamingo-stack/openframe-oss-lib/blob/main/platform.ts)

package/src/types/.product-release.md

@@ -1,36 +1,35 @@
-<!-- source-hash: 5a845a31a46ea7c6d1945d44c5a712fa -->
-Defines the complete TypeScript type system for the Flamingo product release module, including data shapes for releases, changelog entries, media assets, and external integrations (GitHub, ClickUp, Knowledge Base).
+<!-- source-hash: 40ff0cd4ec6612169d678f41eda8a533 -->
+Defines TypeScript types, interfaces, and constants for the product release domain, covering the full lifecycle of a release record from creation to publishing with support for changelogs, media, external integrations, and AI-generated content.
 
 ## Key Components
 
 ### Core Interfaces
 
 | Interface | Purpose |
-|-----------|---------|
-| `ProductRelease` | Primary entity — full release record with video, SEO, AI, analytics, and relation fields |
-| `ChangelogEntry` | Single changelog item with optional per-entry `visibility` (supports investor update use case) |
-| `ReleaseMedia` | Attached media assets (`image`, `video`, `screenshot`, `demo`) |
-| `CreateProductReleaseData` | Input shape for creating a new release |
-| `UpdateProductReleaseData` | Partial version of create data for updates |
-| `ProductReleaseFilters` | Query filter bag for list endpoints (pagination, tags, type, status, search) |
-| `ProductReleaseListResponse` | Paginated list response wrapper |
+|---|---|
+| `ProductRelease` | Primary record shape with all release fields including changelog arrays, video processing, SEO, HubSpot email, and populated relations |
+| `ChangelogEntry` | Single changelog item with optional per-entry visibility (`public` \| `internal`) for compatibility with investor-update flows |
+| `ReleaseMedia` | Attached media asset (image, video, screenshot, demo) with ordering metadata |
+| `CreateProductReleaseData` | Input shape for creating a release; platform IDs and tag IDs passed as flat arrays |
+| `UpdateProductReleaseData` | Partial of `CreateProductReleaseData` for PATCH operations |
+| `ProductReleaseFilters` | Query filter bag used by list endpoints (platform, tags, version, type, status, pagination) |
+| `ProductReleaseListResponse` | Paginated list envelope: `data` array + total `count` |
 
 ### External Link Interfaces
 
-| Interface | Links To |
-|-----------|---------|
-| `ProductReleaseGitHubLink` | GitHub release URLs |
-| `KnowledgeBaseLink` | Internal KB article paths |
-| `ClickUpRoadmapTask` | ClickUp roadmap task IDs |
-| `ClickUpDeliveryTask` | ClickUp delivery list task IDs |
-| `GitHubRelease` | GitHub API release shape (wizard import) |
+- **`ProductReleaseGitHubLink`** — full GitHub release URL with ordering
+- **`KnowledgeBaseLink`** — relative KB article path
+- **`ClickUpRoadmapTask`** / **`ClickUpDeliveryTask`** — ClickUp task IDs for roadmap and delivery lists
+- **`GitHubRelease`** — GitHub API release shape used in the creation wizard
 
-### Constants & Utilities
+### Constants
 
-- `releaseTypeOptions` — dropdown metadata for `major`, `minor`, `patch`, `beta`, `alpha`
-- `releaseStatusOptions` — dropdown metadata for `alpha`, `beta`, `stable`, `deprecated`
-- `changelogLabels` — human-readable labels for changelog categories
-- `SEMVER_REGEX` — validates semantic versioning strings including pre-release and build metadata
+| Export | Purpose |
+|---|---|
+| `releaseTypeOptions` | Dropdown options for `major`, `minor`, `patch`, `beta`, `alpha` with colors |
+| `releaseStatusOptions` | Dropdown options for `alpha`, `beta`, `stable`, `deprecated` with colors |
+| `changelogLabels` | Human-readable labels for the four changelog JSONB categories |
+| `SEMVER_REGEX` | Validates semantic version strings including pre-release and build metadata |
 
 ## Usage Example
 
@@ -38,45 +37,63 @@ Defines the complete TypeScript type system for the Flamingo product release mod
 import type {
   ProductRelease,
   CreateProductReleaseData,
-  ProductReleaseFilters,
   ChangelogEntry,
+  ProductReleaseFilters,
 } from './product-release'
 import { releaseTypeOptions, SEMVER_REGEX } from './product-release'
 
-// Validate version before submission
+// Validate a version string before submitting
 const version = '2.1.0-beta.1'
 if (!SEMVER_REGEX.test(version)) {
   throw new Error(`Invalid semver: ${version}`)
 }
 
-// Build a new release payload
-const newRelease: CreateProductReleaseData = {
-  title: 'OpenFrame 2.1 Beta',
-  slug: 'openframe-2-1-beta',
+// Build a changelog entry with visibility control
+const entry: ChangelogEntry = {
+  title: 'New AI-powered ticket routing',
+  description: 'Mingo AI now auto-assigns tickets based on technician skill sets.',
+  visibility: 'public',
+}
+
+// Compose a create payload
+const payload: CreateProductReleaseData = {
+  title: 'OpenFrame 2.1.0 Beta',
+  slug: 'openframe-2-1-0-beta',
   version,
   release_type: 'beta',
   release_status: 'beta',
-  release_date: '2025-07-01',
+  release_date: '2025-08-01',
+  features_added: [entry],
+  bugs_fixed: [],
+  improvements: [],
+  breaking_changes: [],
   status: 'draft',
-  author_id: 'user-uuid',
+  author_id: 'usr_abc123',
   platforms: ['platform-uuid-1'],
-  tags: [1, 4],
-  features_added: [
-    { title: 'Mingo AI ticket routing', visibility: 'public' },
-    { title: 'Internal billing dashboard', visibility: 'internal' },
-  ] satisfies ChangelogEntry[],
+  tags: [4, 12],
 }
 
-// Filter releases for a public changelog page
+// Filter releases for the public changelog page
 const filters: ProductReleaseFilters = {
-  release_status: ['stable', 'beta'],
+  release_status: ['stable'],
+  release_type: ['major', 'minor'],
   has_breaking_changes: false,
-  status: 'published',
   limit: 20,
   offset: 0,
 }
 
-// Access dropdown labels for a form
-const typeLabel = releaseTypeOptions.find(o => o.value === 'beta')?.label
-// → 'Beta Release'
-```
+// Use dropdown metadata for a release type selector
+const options = releaseTypeOptions.map(({ value, label, color }) => ({
+  id: value,
+  display: label,
+  badge: color,
+}))
+```
+
+## Related Types
+
+This file imports from and composes with:
+- [`platform.ts`](https://github.com/flamingo-stack/openframe-oss-lib/blob/main/platform.ts) — `PlatformRecord`
+- [`entity-author.ts`](https://github.com/flamingo-stack/openframe-oss-lib/blob/main/entity-author.ts) — `EntityAuthor`
+- [`blog.ts`](https://github.com/flamingo-stack/openframe-oss-lib/blob/main/blog.ts) — `BlogTag`, `TagAssoc`
+- [`video-processing.ts`](https://github.com/flamingo-stack/openframe-oss-lib/blob/main/video-processing.ts) — `VideoTeaser`, `TranscriptWord`, `SpeakerMapping`

package/src/types/.shell.types.md

@@ -1,39 +1,55 @@
-<!-- source-hash: b8477e619839e162b7edcfaaf835462d -->
-Centralized type definitions for shell/script types supported across the Flamingo platform. Provides a single source of truth for shell metadata, icons, and labels based on OpenFrame RMM supported types.
+<!-- source-hash: 01d8857ba44e5ce450e2b860e0ac2552 -->
+Centralized type definitions and metadata registry for all supported shell/script types used across the OpenFrame platform.
 
 ## Key Components
 
-- **ShellTypeValues** - Const object defining all supported shell type constants (POWERSHELL, CMD, BASH, etc.)
-- **ShellType** - Union type derived from ShellTypeValues for type safety
-- **ShellTypeDefinition** - Interface defining shell metadata structure with id, label, value, and icon
-- **SHELL_TYPES** - Complete array of all shell definitions with associated React icons
-- **shellLabels** - Record mapping shell types to display-friendly labels
+| Export | Kind | Description |
+|---|---|---|
+| `ShellTypeValues` | `const` | Enum-like object of all supported shell type identifiers |
+| `ShellType` | `type` | Union type derived from `ShellTypeValues` values |
+| `ShellTypeDefinition` | `interface` | Full metadata shape for a shell type (id, label, value, icon) |
+| `SHELL_TYPES` | `ShellTypeDefinition[]` | **Single source of truth** — ordered list of all shell types with icons and labels |
+| `shellLabels` | `Record<ShellType, string>` | Convenience map from shell type key to display label |
+
+**Supported shells:** PowerShell, Batch (CMD), Bash, Python, Nu (Nushell), Deno, Shell
 
 ## Usage Example
 
 ```typescript
-import { SHELL_TYPES, ShellType, ShellTypeValues, shellLabels } from './shell.types'
-
-// Type-safe shell type usage
-const shellType: ShellType = ShellTypeValues.POWERSHELL
-
-// Get shell definition with icon
-const powershellDef = SHELL_TYPES.find(s => s.id === ShellTypeValues.POWERSHELL)
-const PowershellIcon = powershellDef?.icon
-
-// Render shell selector
-function ShellSelector() {
-  return (
-    <select>
-      {SHELL_TYPES.map(shell => (
-        <option key={shell.id} value={shell.value}>
-          {shell.label}
-        </option>
-      ))}
-    </select>
-  )
+import {
+  SHELL_TYPES,
+  ShellTypeValues,
+  shellLabels,
+  type ShellType,
+  type ShellTypeDefinition
+} from '@/types/shell.types'
+
+// Render a dropdown of all supported shells
+const options = SHELL_TYPES.map(({ id, label, icon: Icon }) => (
+  <option key={id} value={id}>
+    <Icon size={16} /> {label}
+  </option>
+))
+
+// Resolve a display label from a stored shell type
+const stored: ShellType = ShellTypeValues.POWERSHELL
+console.log(shellLabels[stored]) // → "PowerShell"
+
+// Type-safe shell type check
+function runScript(shell: ShellType, script: string) {
+  if (shell === ShellTypeValues.PYTHON) {
+    // handle Python-specific execution
+  }
 }
 
-// Get display label
-const label = shellLabels[ShellTypeValues.BASH] // "Bash"
-```
+// Look up a full definition by id
+const def: ShellTypeDefinition | undefined = SHELL_TYPES.find(
+  (s) => s.id === ShellTypeValues.BASH
+)
+```
+
+## Notes
+
+- Always import from this file rather than defining local shell constants — `SHELL_TYPES` is the designated single source of truth across the platform.
+- The `value` field (e.g. `'powershell'`, `'bash'`) is intended for RMM API payloads; `id` is for internal logic; `label` is for UI display.
+- Icons are React components typed via `IconProps` from `./icons`.