@devalok/shilp-sutra-karm 0.18.0 → 0.18.1

package/docs/components/chat/chat-panel.md

@@ -0,0 +1,58 @@
+# ChatPanel
+
+- Import: @devalok/shilp-sutra-karm/chat
+- Server-safe: No
+- Category: chat
+
+## Props
+    isOpen: boolean (REQUIRED)
+    onOpenChange: (open: boolean) => void (REQUIRED)
+    messages: ChatMessage[] (REQUIRED)
+    conversations: Conversation[] (REQUIRED)
+    agents: Agent[] (default: DEFAULT_AGENTS — Devadoot, Prahari, Sutradhar, Sahayak, Vidwan, Sanchalak, Dwar-Palak)
+    selectedAgentId: string (default: "devadoot")
+    activeConversationId: string | null
+    isStreaming: boolean (default: false)
+    streamingText: string (default: "")
+    isLoadingMessages: boolean (default: false)
+    isLoadingConversations: boolean (default: false)
+    onSendMessage: (message: string) => void (REQUIRED)
+    onCancelStream: () => void
+    onSelectAgent: (agentId: string) => void
+    onStartNewChat: () => void
+    onSelectConversation: (id: string) => void
+    onArchiveConversation: (id: string) => void
+    onDeleteConversation: (id: string) => void
+    className: string
+
+## Related Types
+    Agent: { id: string; name: string; desc: string }
+    ChatMessage: { id: string; role: "USER" | "ASSISTANT" | "SYSTEM"; content: string }
+    Conversation: { id: string; title: string | null; updatedAt: string }
+
+## Defaults
+    agents=DEFAULT_AGENTS, selectedAgentId="devadoot", isStreaming=false, streamingText="", isLoadingMessages=false, isLoadingConversations=false
+
+## Example
+```jsx
+<ChatPanel
+  isOpen={chatOpen}
+  onOpenChange={setChatOpen}
+  messages={messages}
+  conversations={conversations}
+  selectedAgentId="devadoot"
+  onSendMessage={(msg) => sendMessage(msg)}
+  onSelectConversation={(id) => loadConversation(id)}
+/>
+```
+
+## Gotchas
+- Renders inside a Sheet (right side panel), capped at 480px max-width
+- Toggles between MessageList (chat view) and ConversationList (history view) internally
+- The Agent type is exported from this module — use it for custom agent arrays
+- ChatMessage and Conversation types are re-exported from message-list and conversation-list respectively
+- Extends Omit<React.HTMLAttributes<HTMLDivElement>, 'children'> — children are not accepted
+
+## Changes
+### v0.18.0
+- **Added** Initial release

package/docs/components/chat/conversation-list.md

@@ -0,0 +1,47 @@
+# ConversationList
+
+- Import: @devalok/shilp-sutra-karm/chat
+- Server-safe: No
+- Category: chat
+
+## Props
+    conversations: Conversation[] (REQUIRED)
+    activeConversationId: string | null
+    isLoading: boolean (default: false)
+    onSelect: (id: string) => void (REQUIRED)
+    onNewChat: () => void (REQUIRED)
+    onArchive: (id: string) => void
+    onDelete: (id: string) => void
+    className: string
+
+## Related Types
+    Conversation: { id: string; title: string | null; updatedAt: string }
+
+## Defaults
+    isLoading=false
+
+## Example
+```jsx
+<ConversationList
+  conversations={conversations}
+  activeConversationId={currentConvoId}
+  onSelect={(id) => loadConversation(id)}
+  onNewChat={() => startNewChat()}
+  onArchive={(id) => archiveConversation(id)}
+  onDelete={(id) => deleteConversation(id)}
+/>
+```
+
+## Gotchas
+- Extends Omit<React.HTMLAttributes<HTMLDivElement>, 'onSelect'> — the native onSelect is replaced
+- Archive and delete buttons appear on hover for each conversation row
+- If onArchive or onDelete are not provided, the corresponding action buttons are hidden
+- Conversations with null title display as "Untitled conversation"
+- updatedAt is formatted using formatRelativeTime (e.g., "2 hours ago")
+- The active conversation is highlighted with bg-surface-2
+- Shows a loading spinner when isLoading=true
+- Shows "No conversations yet" empty state when the array is empty
+
+## Changes
+### v0.18.0
+- **Added** Initial release

package/docs/components/chat/message-list.md

@@ -0,0 +1,44 @@
+# MessageList
+
+- Import: @devalok/shilp-sutra-karm/chat
+- Server-safe: No
+- Category: chat
+
+## Props
+    messages: ChatMessage[] (REQUIRED)
+    isStreaming: boolean (default: false)
+    streamingText: string (default: "")
+    isLoadingMessages: boolean (default: false)
+    emptyTitle: string (default: "Karm AI")
+    emptyDescription: string (default: "Ask me about tasks, projects, attendance, or anything else.")
+    className: string
+
+## Related Types
+    ChatMessage: { id: string; role: "USER" | "ASSISTANT" | "SYSTEM"; content: string }
+
+## Defaults
+    isStreaming=false, streamingText="", isLoadingMessages=false, emptyTitle="Karm AI", emptyDescription="Ask me about tasks, projects, attendance, or anything else."
+
+## Example
+```jsx
+<MessageList
+  messages={messages}
+  isStreaming={isStreaming}
+  streamingText={currentStreamText}
+  isLoadingMessages={loading}
+/>
+```
+
+## Gotchas
+- Auto-scrolls to bottom when messages or streamingText change
+- Three message roles render differently: USER (right-aligned, accent bubble), ASSISTANT (left-aligned, markdown-rendered), SYSTEM (centered, error-styled)
+- When isStreaming=true and streamingText is non-empty, renders a StreamingText component below the message list
+- When isStreaming=true and streamingText is empty, shows animated bouncing dots
+- ASSISTANT messages are rendered with ReactMarkdown — supports markdown formatting
+- Shows a loading spinner when isLoadingMessages=true
+- Shows an empty state with robot icon when no messages and not streaming
+- Uses framer-motion AnimatePresence for enter/exit animations
+
+## Changes
+### v0.18.0
+- **Added** Initial release

package/docs/components/chat/streaming-text.md

@@ -0,0 +1,29 @@
+# StreamingText
+
+- Import: @devalok/shilp-sutra-karm/chat
+- Server-safe: No
+- Category: chat
+
+## Props
+    text: string (REQUIRED)
+    isComplete: boolean (default: false)
+    className: string
+
+## Defaults
+    isComplete=false
+
+## Example
+```jsx
+<StreamingText text={partialResponse} isComplete={!isStreaming} />
+```
+
+## Gotchas
+- Shows a pulsing cursor block after the text while isComplete=false
+- When isComplete=true, the cursor disappears and the full text is announced to screen readers via aria-live="polite"
+- While streaming (isComplete=false), aria-live is set to "off" to avoid flooding screen readers
+- Text is rendered with ReactMarkdown — supports markdown formatting
+- Extends React.HTMLAttributes<HTMLDivElement>
+
+## Changes
+### v0.18.0
+- **Added** Initial release

package/docs/components/client/accent-provider.md

@@ -0,0 +1,29 @@
+# AccentProvider
+
+- Import: @devalok/shilp-sutra-karm/client
+- Server-safe: No
+- Category: client
+
+## Props
+    accentCss: string | null (default: undefined)
+
+## Defaults
+    (no visual defaults — renders nothing)
+
+## Example
+```jsx
+<AccentProvider accentCss="--color-accent: #d33163; --color-accent-light: #f7e9e9;" />
+```
+
+## Gotchas
+- Renders null — this is a headless component with no visual output
+- Does NOT accept children — it is not a wrapper/provider component in the React context sense
+- Injects CSS custom properties directly onto document.documentElement via useEffect
+- Properties are cleaned up (removed) when the component unmounts or when accentCss changes
+- Pass a semicolon-separated CSS custom property string (e.g., "--color-accent: #d33163; --color-accent-light: #f7e9e9;")
+- If accentCss is null or undefined, no properties are applied
+- Does NOT extend React.HTMLAttributes — only accepts the accentCss prop
+
+## Changes
+### v0.18.0
+- **Added** Initial release

package/docs/components/client/client-portal-header.md

@@ -0,0 +1,40 @@
+# ClientPortalHeader
+
+- Import: @devalok/shilp-sutra-karm/client
+- Server-safe: No
+- Category: client
+
+## Props
+    orgName: string (REQUIRED)
+    orgLogo: string | null
+    userName: string (REQUIRED)
+    userAvatar: string | null
+    children: ReactNode
+    className: string
+
+## Defaults
+    (no prop defaults)
+
+## Example
+```jsx
+<ClientPortalHeader
+  orgName="Acme Corp"
+  orgLogo="/logos/acme.png"
+  userName="Jane Doe"
+  userAvatar="/avatars/jane.jpg"
+>
+  <Button variant="ghost" size="sm">Settings</Button>
+</ClientPortalHeader>
+```
+
+## Gotchas
+- Renders a <header> element — extends React.HTMLAttributes<HTMLElement>
+- If orgLogo is null/undefined, shows a fallback with the first two initials of orgName on an accent background
+- If userAvatar is null/undefined, shows an Avatar fallback with the first two initials of userName
+- children are rendered between the org branding (left) and user avatar (right) — use this slot for action buttons or navigation
+- The user's full name is hidden on small screens (shown only on sm: and above)
+- Fixed height of h-ds-lg with bottom border
+
+## Changes
+### v0.18.0
+- **Added** Initial release

package/docs/components/client/project-card.md

@@ -0,0 +1,39 @@
+# ProjectCard
+
+- Import: @devalok/shilp-sutra-karm/client
+- Server-safe: No
+- Category: client
+
+## Props
+    name: string (REQUIRED)
+    description: string | null
+    status: "active" | "completed" | "paused" (REQUIRED)
+    taskCount: number (default: 0)
+    completedTasks: number (default: 0)
+    className: string
+
+## Defaults
+    taskCount=0, completedTasks=0
+
+## Example
+```jsx
+<ProjectCard
+  name="Website Redesign"
+  description="Complete overhaul of the marketing site"
+  status="active"
+  taskCount={24}
+  completedTasks={18}
+/>
+```
+
+## Gotchas
+- Status maps to Badge colors: active=success, completed=info, paused=warning
+- Progress bar shows completedTasks/taskCount as a percentage (rounded)
+- If taskCount is 0, progress is 0% regardless of completedTasks
+- Description is clamped to 2 lines with line-clamp-2
+- Has cursor-pointer and hover shadow — attach onClick via spread props for navigation
+- Extends React.HTMLAttributes<HTMLDivElement>
+
+## Changes
+### v0.18.0
+- **Added** Initial release

package/docs/components/dashboard/attendance-cta.md

@@ -0,0 +1,47 @@
+# AttendanceCTA
+
+- Import: @devalok/shilp-sutra-karm/dashboard
+- Server-safe: No
+- Category: dashboard
+
+## Props
+    userName: string (REQUIRED)
+    attendance: AttendanceData | null (REQUIRED)
+    canMarkAttendance: boolean (REQUIRED)
+    onMarkAttendance: () => void
+    isSubmitting: boolean (default: false)
+    formatTime: (timeStr: string) => string (default: IST toLocaleTimeString)
+    className: string
+
+## Related Types
+    AttendanceData: { attendance: { id: string; status: string; timeIn: string | null; timeOut: string | null }; breakReason: string | null }
+
+## Defaults
+    isSubmitting=false, formatTime=defaultFormatTime (IST, 12-hour)
+
+## Example
+```jsx
+<AttendanceCTA
+  userName="Mudit Sharma"
+  attendance={attendanceData}
+  canMarkAttendance={true}
+  onMarkAttendance={() => markAttendance()}
+  isSubmitting={isMarking}
+/>
+```
+
+## Gotchas
+- Renders four different states based on attendance data:
+  1. **Unmarked + canMark**: Large greeting card with gradient background and "Mark Attendance" button
+  2. **Marked (PRESENT)**: Compact strip showing check-in time in a success badge
+  3. **On Break (BREAK)**: Compact strip with warning badge showing break reason
+  4. **Unmarked + cannot mark**: Compact strip with "Attendance window closed" message
+- Greeting is time-based: "Good morning" (before 12), "Good afternoon" (12-17), "Good evening" (after 17)
+- Only the first name (split on space) is displayed in the greeting
+- Date is formatted in en-IN locale with IST timezone
+- The default formatTime uses en-IN locale with IST timezone and 12-hour format
+- Extends React.HTMLAttributes<HTMLDivElement>
+
+## Changes
+### v0.18.0
+- **Added** Initial release

package/docs/components/dashboard/daily-brief.md

@@ -0,0 +1,45 @@
+# DailyBrief
+
+- Import: @devalok/shilp-sutra-karm/dashboard
+- Server-safe: No
+- Category: dashboard
+
+## Props
+    data: BriefData | null (REQUIRED)
+    loading: boolean (default: false)
+    onRefresh: () => void
+    unavailable: boolean (default: false)
+    collapsible: boolean (default: true)
+    defaultCollapsed: boolean (default: false)
+    title: string (default: "Morning Brief")
+    className: string
+
+## Related Types
+    BriefData: { brief: string[]; generatedAt: string }
+
+## Defaults
+    loading=false, unavailable=false, collapsible=true, defaultCollapsed=false, title="Morning Brief"
+
+## Example
+```jsx
+<DailyBrief
+  data={{ brief: ["3 tasks due today", "Team standup at 10am"], generatedAt: new Date().toISOString() }}
+  onRefresh={() => refetchBrief()}
+  loading={isRefreshing}
+/>
+```
+
+## Gotchas
+- Returns null if data is null or data.brief is empty (and not loading/unavailable)
+- When loading=true and data is null, shows a shimmer skeleton placeholder
+- When unavailable=true, shows a minimal "AI brief unavailable" strip
+- Each brief item is rendered with ReactMarkdown — supports inline markdown (bold, code, links)
+- Brief items get rotating colored dots (amber, teal, cyan, accent)
+- Shows "Generated X ago" timestamp using formatRelativeTime
+- The refresh button only appears when onRefresh is provided; it spins while loading=true
+- Collapse/expand uses framer-motion AnimatePresence for smooth height animation
+- Extends React.HTMLAttributes<HTMLDivElement>
+
+## Changes
+### v0.18.0
+- **Added** Initial release

package/docs/components/dashboard/scratchpad-widget.md

@@ -0,0 +1,52 @@
+# ScratchpadWidget
+
+- Import: @devalok/shilp-sutra-karm/dashboard
+- Server-safe: No
+- Category: dashboard
+
+## Props
+    items: ScratchpadItem[] (REQUIRED)
+    maxItems: number (default: 5)
+    onToggle: (id: string, done: boolean) => void (REQUIRED)
+    onAdd: (text: string) => void (REQUIRED)
+    onDelete: (id: string) => void (REQUIRED)
+    title: string (default: "My Scratchpad")
+    resetLabel: string
+    emptyText: string (default: "Nothing here yet. Add a task!")
+    emptyIcon: React.ComponentType<{ className?: string }>
+    loading: boolean (default: false)
+    className: string
+
+## Related Types
+    ScratchpadItem: { id: string; text: string; done: boolean }
+
+## Defaults
+    maxItems=5, title="My Scratchpad", emptyText="Nothing here yet. Add a task!", loading=false
+
+## Example
+```jsx
+<ScratchpadWidget
+  items={scratchpadItems}
+  onToggle={(id, done) => toggleItem(id, done)}
+  onAdd={(text) => addItem(text)}
+  onDelete={(id) => deleteItem(id)}
+  maxItems={5}
+/>
+```
+
+## Gotchas
+- Extends Omit<React.HTMLAttributes<HTMLDivElement>, 'title'> — the native title attribute is replaced by the title prop
+- The "Add a task" input appears only when items.length < maxItems
+- After adding an item, the input stays open for rapid entry; press Escape to close
+- Enter submits the new item; Escape cancels the add flow
+- Blurring the input with empty text closes the add flow
+- Shows a progress ring in the header displaying items.length / maxItems with accent/success color
+- When all items are done, the progress ring pulses with a scale animation
+- Each item has a delete button that appears on hover
+- resetLabel renders as footer text below the item list (e.g., "Resets daily at midnight")
+- When loading=true, shows a shimmer skeleton placeholder
+- Uses framer-motion AnimatePresence for item enter/exit animations
+
+## Changes
+### v0.18.0
+- **Added** Initial release

package/docs/components/dashboard/sidebar-scratchpad.md

@@ -0,0 +1,39 @@
+# SidebarScratchpad
+
+- Import: @devalok/shilp-sutra-karm/dashboard
+- Server-safe: No
+- Category: dashboard
+
+## Props
+    items: ScratchpadItem[] (REQUIRED)
+    onToggle: (id: string, done: boolean) => void (REQUIRED)
+    defaultOpen: boolean (default: true)
+    badgeCount: number
+    className: string
+
+## Related Types
+    ScratchpadItem: { id: string; text: string; done: boolean } (imported from scratchpad-widget)
+
+## Defaults
+    defaultOpen=true
+
+## Example
+```jsx
+<SidebarScratchpad
+  items={scratchpadItems}
+  onToggle={(id, done) => toggleItem(id, done)}
+  badgeCount={scratchpadItems.filter(i => !i.done).length}
+/>
+```
+
+## Gotchas
+- This is a compact, read-only version of ScratchpadWidget designed for the app sidebar
+- Does NOT support adding or deleting items — use ScratchpadWidget for full CRUD
+- Only supports toggling done state via checkboxes
+- Collapsible header with chevron; uses CSS grid-rows transition for smooth collapse
+- badgeCount shows a pill badge in the header; hidden when badgeCount is undefined, null, or 0
+- Extends React.HTMLAttributes<HTMLDivElement>
+
+## Changes
+### v0.18.0
+- **Added** Initial release

package/docs/components/other/karm-command-registry.md

@@ -0,0 +1,61 @@
+# karmCommandRegistry
+
+- Import: @devalok/shilp-sutra-karm (top-level export)
+- Server-safe: No
+- Category: shell
+
+Pre-configured command registry for the Karm app's AppCommandPalette. Contains all page routes and admin routes.
+
+Exports: karmCommandRegistry
+
+## Type
+```ts
+const karmCommandRegistry: CommandRegistry
+```
+
+Where `CommandRegistry` is `{ pages: CommandPageItem[], adminPages: CommandPageItem[] }` from `@devalok/shilp-sutra/shell/command-registry`.
+
+## Pages
+| id | label | path | keywords |
+|----|-------|------|----------|
+| nav-dashboard | Dashboard | / | home |
+| nav-attendance | Attendance | /attendance | clock, time |
+| nav-breaks | Breaks | /breaks | leave, vacation |
+| nav-projects | Projects | /projects | board, kanban |
+| nav-my-tasks | My Tasks | /my-tasks | todo |
+| nav-devsabha | Devsabha | /devsabha | standup, meeting |
+| nav-adjustments | Adjustments | /adjustments | corrections |
+| nav-profile | Profile | /profile | account, settings |
+
+## Admin Pages
+| id | label | path | keywords |
+|----|-------|------|----------|
+| nav-admin-dashboard | Admin Dashboard | /admin | admin, overview |
+| nav-admin-breaks | Manage Breaks | /admin/breaks | admin, leave |
+| nav-admin-attendance | Manage Attendance | /admin/attendance | admin, time |
+| nav-admin-lokwasi | Lokwasi | /admin/lokwasi | admin, onboarding |
+| nav-admin-onboarding | Onboarding | /admin/onboarding | admin, new hire |
+| nav-admin-config | System Config | /admin/system-config | admin, settings, configuration |
+
+## Example
+```jsx
+import { CommandRegistryProvider } from '@devalok/shilp-sutra/shell/command-registry'
+import { karmCommandRegistry } from '@devalok/shilp-sutra-karm'
+
+<CommandRegistryProvider registry={karmCommandRegistry}>
+  <AppCommandPalette
+    user={user}
+    onNavigate={(path) => router.push(path)}
+  />
+</CommandRegistryProvider>
+```
+
+## Gotchas
+- Each entry includes a Tabler icon (e.g. `IconLayoutDashboard`, `IconUmbrella`) — these are bundled, not tree-shaken
+- The registry is a plain object, not a React component — pass it to `CommandRegistryProvider`
+- Admin pages are only shown in the command palette when the user has admin role (handled by AppCommandPalette)
+- To add new routes, extend the registry object in your app rather than modifying this export
+
+## Changes
+### v0.9.0
+- **Added** Initial release with 8 pages and 6 admin pages

package/docs/components/other/page-skeletons.md

@@ -0,0 +1,52 @@
+# Page Skeletons (Karm)
+
+- Import: @devalok/shilp-sutra-karm
+- Server-safe: No
+- Category: other
+
+Domain-specific loading skeleton components for Karm pages.
+
+Exports: DevsabhaSkeleton, BandwidthSkeleton
+
+## Props
+
+### DevsabhaSkeleton
+    ...HTMLDivElement attributes (className, etc.)
+
+Renders a 5-section skeleton grid mimicking the Devsabha (standup) page layout:
+1. Main large card (lg:col-span-2) with 4 rows
+2. Side card with 3 avatar rows
+3. Full-width card (lg:col-span-3) with 3 sub-cards
+4. Stats row (lg:col-span-2) with 4 stat blocks
+5. Timeline card with 3 entries
+
+### BandwidthSkeleton
+    ...HTMLDivElement attributes (className, etc.)
+
+Renders a skeleton mimicking the Bandwidth page layout:
+1. 3 summary cards (sm:grid-cols-3) with progress bars
+2. Table with 5-column header and 6 rows with avatar + name
+
+## Defaults
+    None
+
+## Example
+```jsx
+import { DevsabhaSkeleton, BandwidthSkeleton } from '@devalok/shilp-sutra-karm'
+
+// Use while data loads
+if (isLoading) return <DevsabhaSkeleton />
+
+// Bandwidth page loading
+if (isLoading) return <BandwidthSkeleton className="p-6" />
+```
+
+## Gotchas
+- These are top-level exports from the karm package, not from the admin sub-path
+- Both use the core `Skeleton` component internally
+- Layout uses `gap-ds-06` spacing and `rounded-ds-xl` border radius
+- Pass `className` to customize outer container styles
+
+## Changes
+### v0.9.0
+- **Added** Initial release

package/docs/components/tasks/activity-tab.md

@@ -0,0 +1,41 @@
+# ActivityTab
+
+- Import: @devalok/shilp-sutra-karm/tasks
+- Server-safe: No
+- Category: tasks
+
+## Props
+    activities: AuditLogEntry[] (REQUIRED)
+    ...HTMLAttributes<HTMLDivElement>
+
+## AuditLogEntry Shape
+    id: string
+    timestamp: string
+    actorType: 'USER' | 'CLIENT' | 'SYSTEM' | 'AGENT'
+    actorId: string | null
+    action: string
+    entityType: string
+    entityId: string
+    projectId: string | null
+    metadata: Record<string, unknown> | null
+
+## Supported Actions
+    task.created, task.updated, task.moved, task.assigned, task.unassigned,
+    task.commented, task.file_uploaded, task.review_requested, task.review_completed,
+    task.visibility_changed, task.priority_changed, task.labels_changed, task.due_date_changed
+
+## Example
+```jsx
+<ActivityTab activities={auditLogEntries} />
+```
+
+## Gotchas
+- Renders a vertical timeline with colored dots and icons per action type.
+- Unknown actions fall back to a generic icon and use entry.action as the description.
+- Actor name is derived from metadata.actorName, falling back to "System", "AI Agent", or "Someone".
+- Empty state uses EmptyState component: "No activity yet".
+- Forwards ref to outer div.
+
+## Changes
+### v0.18.0
+- **Added** Initial release

package/docs/components/tasks/conversation-tab.md

@@ -0,0 +1,52 @@
+# ConversationTab
+
+- Import: @devalok/shilp-sutra-karm/tasks
+- Server-safe: No
+- Category: tasks
+
+## Props
+    comments: Comment[] (REQUIRED)
+    taskVisibility: 'INTERNAL' | 'EVERYONE' (REQUIRED)
+    onPostComment: (content: string, authorType: 'INTERNAL' | 'CLIENT') => void (REQUIRED)
+    clientMode: boolean (default: false)
+    richText: boolean (default: true) — enable built-in RichTextEditor/Viewer
+    renderEditor: (props: { content: string; onChange: (content: string) => void; placeholder: string }) => ReactNode
+    renderViewer: (props: { content: string; className?: string }) => ReactNode
+    ...HTMLAttributes<HTMLDivElement>
+
+## Comment Shape
+    id: string
+    taskId: string
+    authorType: 'INTERNAL' | 'CLIENT'
+    authorId: string
+    content: string
+    createdAt: string
+    updatedAt: string
+    internalAuthor: { id: string; name: string; email?: string; image?: string | null } | null (optional)
+    clientAuthor: { id: string; name: string; email: string } | null (optional)
+
+## Defaults
+    clientMode=false, richText=true
+
+## Example
+```jsx
+<ConversationTab
+  comments={task.comments}
+  taskVisibility={task.visibility}
+  onPostComment={(content, type) => postComment(content, type)}
+/>
+```
+
+## Gotchas
+- In clientMode, comments are posted with authorType='CLIENT'. In staff mode, authorType='INTERNAL'.
+- When taskVisibility='EVERYONE' and not clientMode, a warning is shown: "Comments may be seen by external users."
+- In clientMode, staff comments show a "Team" badge. In staff mode, client comments show a "Client" badge.
+- Editor resolution priority: renderEditor prop > built-in RichTextEditor (when richText=true) > plain textarea fallback.
+- Viewer resolution priority: renderViewer prop > built-in RichTextViewer (when richText=true) > plain text with HTML stripped.
+- Auto-scrolls to bottom when new comments arrive.
+- Empty state: "No comments yet".
+- Forwards ref to outer div.
+
+## Changes
+### v0.18.0
+- **Added** Initial release