@devalok/shilp-sutra-karm 0.18.0 → 0.19.0

package/docs/components/board/kanban-board.md

@@ -0,0 +1,53 @@
+# KanbanBoard
+
+- Import: @devalok/shilp-sutra-karm/board
+- Server-safe: No
+- Category: board
+
+## Props
+    initialData: BoardData (REQUIRED)
+    currentUserId: string | null (default: null)
+    members: BoardMember[] (explicit member list; falls back to deriving from task assignees)
+    onTaskMove: (taskId: string, toColumnId: string, newOrder: number) => void
+    onTaskAdd: (columnId: string, options: NewTaskOptions) => void
+    onBulkAction: (action: BulkAction) => void
+    onColumnReorder: (columnId: string, newIndex: number) => void
+    onColumnRename: (columnId: string, name: string) => void
+    onColumnDelete: (columnId: string) => void
+    onColumnToggleVisibility: (columnId: string, visible: boolean) => void
+    onColumnWipLimitChange: (columnId: string, limit: number | null) => void
+    onClickTask: (taskId: string) => void
+    onAddColumn: () => void
+    onQuickPriorityChange: (taskId: string, priority: string) => void
+    onQuickAssign: (taskId: string, userId: string) => void
+    onQuickDueDateChange: (taskId: string, date: string | null) => void
+    onQuickLabelAdd: (taskId: string, label: string) => void
+    onQuickVisibilityChange: (taskId: string, visibility: string) => void
+    onQuickDelete: (taskId: string) => void
+    className: string
+
+## Defaults
+    currentUserId=null
+
+## Example
+```jsx
+<KanbanBoard
+  initialData={{ columns: [...] }}
+  currentUserId="user-1"
+  members={teamMembers}
+  onTaskMove={(taskId, toCol, order) => moveTask(taskId, toCol, order)}
+  onClickTask={(taskId) => openDetail(taskId)}
+  onAddColumn={() => createColumn()}
+/>
+```
+
+## Gotchas
+- This is the top-level orchestrator. It composes BoardProvider, BoardToolbar, BulkActionBar, and BoardColumn internally.
+- All callback props are optional and default to no-op. Wire them up to persist changes.
+- Extends Omit<BoardProviderProps, 'children'> plus className. Forwards ref to outer div.
+- Drag-and-drop uses @dnd-kit (PointerSensor, TouchSensor, KeyboardSensor).
+- The "Add column" button is always rendered at the end of the horizontal scroll area.
+
+## Changes
+### v0.18.0
+- **Added** Initial release

package/docs/components/board/task-card.md

@@ -0,0 +1,62 @@
+# TaskCard / TaskCardCompact / TaskCardOverlay / TaskCardCompactOverlay
+
+- Import: @devalok/shilp-sutra-karm/board
+- Server-safe: No
+- Category: board
+
+## TaskCard Props
+    task: BoardTask (REQUIRED)
+    ...HTMLAttributes<HTMLDivElement>
+
+## TaskCardCompact Props
+    task: BoardTask (REQUIRED)
+    ...HTMLAttributes<HTMLDivElement>
+
+## TaskCardOverlay Props
+    task: BoardTask (REQUIRED)
+    ...HTMLAttributes<HTMLDivElement>
+
+## TaskCardCompactOverlay Props
+    task: BoardTask (REQUIRED)
+    ...HTMLAttributes<HTMLDivElement>
+
+## Card Variants (CVA)
+    state: "default" | "dragging" | "overlay" (default: "default")
+    blocked: boolean (default: false) — adds left error border
+    selected: boolean (default: false) — adds accent ring
+    dimmed: boolean (default: false) — reduces opacity
+
+> **Note:** These are INTERNAL visual states derived from board context (selectedTaskIds, focusedTaskId, highlightMyTasks, drag state, task.isBlocked). Consumers only pass `task: BoardTask` and standard HTML attributes — the component resolves variant values internally.
+
+## Compact Card Variants (CVA)
+    selected: boolean (default: false)
+    dimmed: boolean (default: false)
+
+> **Note:** Same as above — these are INTERNAL visual states. Consumers only pass `task: BoardTask` and standard HTML attributes.
+
+## Example
+```jsx
+{/* Used automatically by BoardColumn based on viewMode */}
+<TaskCard task={task} />
+<TaskCardCompact task={task} />
+
+{/* Overlay variants used inside DragOverlay */}
+<TaskCardOverlay task={task} />
+<TaskCardCompactOverlay task={task} />
+```
+
+## Visual Elements
+- Default card: taskId, priority icon, drag handle, title (2-line clamp), due date, subtask count, visibility/blocked badges, avatar stack (owner with glow + up to 3 assignees)
+- Compact card: single row with priority icon, taskId, title (1-line clamp), subtask count, lead avatar
+
+## Gotchas
+- Must be rendered inside a BoardProvider context (reads selectedTaskIds, focusedTaskId, currentUserId, highlightMyTasks, onClickTask).
+- TaskCard and TaskCardCompact use @dnd-kit useSortable hooks internally for drag-and-drop.
+- TaskCardOverlay and TaskCardCompactOverlay have NO sortable hooks — they are for DragOverlay only.
+- Selection checkbox appears on hover or when any tasks are selected.
+- highlightMyTasks dims cards where the current user is not owner or assignee.
+- All four variants forward ref.
+
+## Changes
+### v0.18.0
+- **Added** Initial release

package/docs/components/board/task-context-menu.md

@@ -0,0 +1,36 @@
+# TaskContextMenu
+
+- Import: @devalok/shilp-sutra-karm/board
+- Server-safe: No
+- Category: board
+
+## Props
+    taskId: string (REQUIRED)
+    children: ReactNode (REQUIRED)
+    className: string
+
+## Menu Items
+- Set Priority (submenu: Low, Medium, High, Urgent with icons)
+- Assign (submenu: member list, only shown when members exist)
+- Add Label (submenu: labels derived from board data)
+- Set Due Date (opens native date picker)
+- Visibility (submenu: Internal only, Visible to all)
+- Delete (destructive, separated by divider)
+
+## Example
+```jsx
+<TaskContextMenu taskId={task.id}>
+  <TaskCard task={task} />
+</TaskContextMenu>
+```
+
+## Gotchas
+- Must be rendered inside a BoardProvider context.
+- Right-click triggers the context menu via Radix ContextMenu.
+- Callbacks come from context: onQuickPriorityChange, onQuickAssign, onQuickLabelAdd, onQuickDueDateChange, onQuickVisibilityChange, onQuickDelete.
+- Due date uses a hidden native date input with showPicker().
+- Forwards ref to ContextMenuTrigger (HTMLSpanElement).
+
+## Changes
+### v0.18.0
+- **Added** Initial release

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

@@ -0,0 +1,37 @@
+# ChatInput
+
+- Import: @devalok/shilp-sutra-karm/chat
+- Server-safe: No
+- Category: chat
+
+## Props
+    onSubmit: (message: string) => void (REQUIRED)
+    onCancel: () => void
+    isStreaming: boolean (default: false)
+    placeholder: string (default: "Ask Karm AI...")
+    disclaimer: string (default: "AI responses may be inaccurate. Verify important information.")
+    className: string
+
+## Defaults
+    isStreaming=false, placeholder="Ask Karm AI...", disclaimer="AI responses may be inaccurate. Verify important information."
+
+## Example
+```jsx
+<ChatInput
+  onSubmit={(msg) => sendMessage(msg)}
+  onCancel={() => cancelStream()}
+  isStreaming={isStreaming}
+/>
+```
+
+## Gotchas
+- Enter sends the message; Shift+Enter inserts a newline
+- When isStreaming=true, the send button becomes a red stop button that calls onCancel
+- The textarea auto-resizes up to 160px max height
+- Trims whitespace before submitting — empty/whitespace-only messages are blocked
+- Extends Omit<React.HTMLAttributes<HTMLDivElement>, 'onSubmit'> — the native onSubmit is replaced
+- Set disclaimer="" (empty string) to hide the disclaimer text
+
+## Changes
+### v0.18.0
+- **Added** Initial release

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), the sr-only announcement span outputs an empty string — aria-live='polite' is always present on the inner span but announces nothing until isComplete=true. The outer container always carries aria-live='off'.
+- 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)**: Greeting card with success badge showing check-in time
+  3. **On Break (BREAK)**: Greeting card with warning badge showing break reason
+  4. **Unmarked + cannot mark**: Greeting card with "Attendance window closed" info badge (no Mark button)
+- 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