@usevyre/ai-context 1.1.0 → 1.2.1

package/dist/anti-patterns.json

@@ -1,5 +1,5 @@
 {
-  "version": "1.1.0",
+  "version": "1.2.0",
   "rules": [
     {
       "component": "Accordion",
@@ -101,9 +101,30 @@
     },
     {
       "component": "Calendar",
-      "pattern": "Using Calendar for time selection",
-      "reason": "Calendar handles date only, not time",
-      "fix": "Combine with a separate time Input if time selection is needed",
+      "pattern": "Calendar for an input field that opens a popover",
+      "reason": "Calendar renders an always-visible grid, not a trigger",
+      "fix": "Use <DatePicker /> (single date) or <DateRangePicker /> (range)",
+      "severity": "error"
+    },
+    {
+      "component": "Calendar",
+      "pattern": "value as tuple for mode=\"single\"",
+      "reason": "value type must match mode: Date for single, [Date,Date] for range, Date[] for multiple",
+      "fix": "Pass value matching mode; use mode=\"range\" for [start,end]",
+      "severity": "error"
+    },
+    {
+      "component": "DatePicker",
+      "pattern": "DatePicker mode=\"range\" for { from, to } object",
+      "reason": "DatePicker range mode emits a [Date, Date] tuple, not a { from, to } object",
+      "fix": "Use <DateRangePicker /> for the { from, to } object API + presets + dual month",
+      "severity": "error"
+    },
+    {
+      "component": "DatePicker",
+      "pattern": "DatePicker without value/onChange",
+      "reason": "DatePicker is controlled — it has no internal selected state",
+      "fix": "Provide value and onChange (e.g. from useState)",
       "severity": "error"
     },
     {
@@ -120,6 +141,48 @@
       "fix": "Use size=\"md\"",
       "severity": "error"
     },
+    {
+      "component": "RadioGroup",
+      "pattern": "<Radio> used outside a <RadioGroup>",
+      "reason": "Radio reads selection + name from RadioGroup context; it throws without a provider",
+      "fix": "Always wrap <Radio> in <RadioGroup>",
+      "severity": "error"
+    },
+    {
+      "component": "RadioGroup",
+      "pattern": "RadioGroup without value/onChange (React) or v-model (Vue)",
+      "reason": "RadioGroup is controlled; selection won't update",
+      "fix": "Bind value + onChange (React) or v-model (Vue); or defaultValue for uncontrolled in React",
+      "severity": "error"
+    },
+    {
+      "component": "RadioGroup",
+      "pattern": "Using Checkbox for mutually-exclusive choices",
+      "reason": "Radio expresses single-choice semantics + keyboard model",
+      "fix": "Use RadioGroup + Radio (or options) for one-of-many",
+      "severity": "error"
+    },
+    {
+      "component": "RichTextEditor",
+      "pattern": "RichTextEditor without value/onChange (React) or v-model (Vue)",
+      "reason": "It is fully controlled; edits won't persist",
+      "fix": "Keep the HTML string in state and update it in onChange / v-model",
+      "severity": "error"
+    },
+    {
+      "component": "RichTextEditor",
+      "pattern": "Rendering value as text or with dangerouslySetInnerHTML elsewhere without sanitising",
+      "reason": "value is raw HTML the user typed",
+      "fix": "Sanitise (e.g. DOMPurify) before re-rendering untrusted RTE output",
+      "severity": "error"
+    },
+    {
+      "component": "RichTextEditor",
+      "pattern": "toolbar=\"bold\" (string)",
+      "reason": "toolbar is an array of tool ids",
+      "fix": "Pass an array, e.g. toolbar={[\"bold\",\"italic\",\"link\"]}",
+      "severity": "error"
+    },
     {
       "component": "Command",
       "pattern": "Using Input type=\"search\" for search UI",
@@ -141,6 +204,13 @@
       "fix": "Wrap Input in <Field state=\"error\"> to apply validation styling",
       "severity": "error"
     },
+    {
+      "component": "Field",
+      "pattern": "Mixing props label/hint AND FieldLabel/FieldError for the same field",
+      "reason": "Duplicates the label / message",
+      "fix": "Pick one: either props-based (label/hint/state) OR composable parts",
+      "severity": "error"
+    },
     {
       "component": "Input",
       "pattern": "size=\"icon\"",
@@ -155,6 +225,13 @@
       "fix": "Import Command from @usevyre/react for search palettes",
       "severity": "error"
     },
+    {
+      "component": "Input",
+      "pattern": "Vue: binding Input/Textarea value without v-model",
+      "reason": "Vue Input & Textarea support v-model (modelValue); manual :value alone won't update",
+      "fix": "Use v-model on <Input>/<Textarea> in Vue; in React use value + onChange",
+      "severity": "error"
+    },
     {
       "component": "Modal",
       "pattern": "size=\"xl\"",
@@ -183,6 +260,13 @@
       "fix": "Pass options={[{ value: 'a', label: 'Option A' }]}",
       "severity": "error"
     },
+    {
+      "component": "Sidebar",
+      "pattern": "Vue: passing icon/collapsedIcon as props on SidebarTrigger",
+      "reason": "Vue SidebarTrigger customises icons via slots, not props (consistent with SidebarItem)",
+      "fix": "Use <template #icon> and <template #collapsed-icon>; React uses icon / collapsedIcon props",
+      "severity": "error"
+    },
     {
       "component": "Toast",
       "pattern": "Rendering <Toast> directly in JSX",
@@ -322,6 +406,104 @@
       "reason": "TagGroup is display-only",
       "fix": "Use TagsInput for an editable tag field",
       "severity": "error"
+    },
+    {
+      "component": "Item",
+      "pattern": "Card used for repeated list rows",
+      "reason": "Card is a content container; Item is the dense list-row primitive",
+      "fix": "Use <Item> (optionally inside <ItemGroup separated>) for list/settings rows",
+      "severity": "error"
+    },
+    {
+      "component": "Item",
+      "pattern": "Item variant=\"primary\"",
+      "reason": "Item has no 'primary' variant",
+      "fix": "Use variant=\"default\" | \"outlined\" | \"muted\"",
+      "severity": "error"
+    },
+    {
+      "component": "Item",
+      "pattern": "raw text directly inside Item",
+      "reason": "Item lays out media/content/actions columns; bare text breaks alignment",
+      "fix": "Wrap text in <ItemContent><ItemTitle>…</ItemTitle></ItemContent>",
+      "severity": "error"
+    },
+    {
+      "component": "Kanban",
+      "pattern": "Kanban without onChange (or ignoring it)",
+      "reason": "Kanban holds no internal data state; dropped cards won't move unless you apply onChange",
+      "fix": "Store columns in state and setColumns in onChange (v-model in Vue)",
+      "severity": "error"
+    },
+    {
+      "component": "Kanban",
+      "pattern": "Duplicate card ids across columns",
+      "reason": "Card moves are resolved by id; duplicates corrupt the move",
+      "fix": "Use globally-unique card ids across the entire board",
+      "severity": "error"
+    },
+    {
+      "component": "Kanban",
+      "pattern": "Mutating value in place then calling onChange",
+      "reason": "React/Vue need a new array reference to re-render reliably",
+      "fix": "Pass the new array Kanban gives you straight to setState / v-model",
+      "severity": "error"
+    },
+    {
+      "component": "Kanban",
+      "pattern": "color=\"blue\" (or any non-semantic value)",
+      "reason": "color is a fixed semantic set, not an arbitrary CSS color",
+      "fix": "Use one of: \"default\" | \"accent\" | \"teal\" | \"success\" | \"warning\" | \"danger\"",
+      "severity": "error"
+    },
+    {
+      "component": "Conversation",
+      "pattern": "Conversation without currentUserId",
+      "reason": "Alignment (incoming vs outgoing) is decided by authorId === currentUserId",
+      "fix": "Always pass currentUserId matching one of the message authorId values",
+      "severity": "error"
+    },
+    {
+      "component": "Conversation",
+      "pattern": "Expecting Conversation to store/append messages",
+      "reason": "Conversation is controlled & stateless for data, like Kanban/DataGrid",
+      "fix": "Append to your own state in onSend (or @send) and pass it back via value",
+      "severity": "error"
+    },
+    {
+      "component": "Conversation",
+      "pattern": "composer without onSend (React) / @send (Vue)",
+      "reason": "The built-in composer emits text; nothing happens unless you handle it",
+      "fix": "Provide onSend / @send to append the message to value",
+      "severity": "error"
+    },
+    {
+      "component": "Conversation",
+      "pattern": "Treating onSend as (text) only when using allowAttachments",
+      "reason": "With allowAttachments, staged files arrive as the 2nd arg; ignoring it drops attachments",
+      "fix": "Handle onSend(text, files) — map files to message attachments and append",
+      "severity": "error"
+    },
+    {
+      "component": "DateRangePicker",
+      "pattern": "value={[from, to]}",
+      "reason": "DateRangePicker uses a { from, to } object, not a [Date, Date] tuple like Calendar mode=range",
+      "fix": "Use value={{ from, to }} and read range.from / range.to",
+      "severity": "error"
+    },
+    {
+      "component": "DateRangePicker",
+      "pattern": "DateRangePicker for a single date",
+      "reason": "DateRangePicker always selects a start AND end",
+      "fix": "Use <DatePicker /> for a single date",
+      "severity": "error"
+    },
+    {
+      "component": "DateRangePicker",
+      "pattern": "presets=\"true\" (string)",
+      "reason": "presets is a boolean or an array, not a string",
+      "fix": "Use the bare prop: presets  (or presets={true})",
+      "severity": "error"
     }
   ]
 }

package/dist/cheat-sheets/calendar.md

@@ -1,7 +1,7 @@
 # Calendar — AI Cheat Sheet
 > Quick reference for Claude / Cursor / Copilot
 
-**Date picker calendar widget for selecting single dates or ranges.**
+**Inline date-grid widget (always visible, no input). mode: single | range | multiple, optional time picker. For an input + popover use DatePicker; for start/end ranges with presets use DateRangePicker.**
 
 ```ts
 import { Calendar } from "@usevyre/react"
@@ -15,8 +15,10 @@ import { Calendar } from "@usevyre/react"
 
 ## Common AI Mistakes
 
-- ❌ `Using Calendar for time selection`
-  → Combine with a separate time Input if time selection is needed
+- ❌ `Calendar for an input field that opens a popover`
+  → Use <DatePicker /> (single date) or <DateRangePicker /> (range)
+- ❌ `value as tuple for mode="single"`
+  → Pass value matching mode; use mode="range" for [start,end]
 
 ## Examples
 

package/dist/cheat-sheets/conversation.md

@@ -0,0 +1,63 @@
+# Conversation — AI Cheat Sheet
+> Quick reference for Claude / Cursor / Copilot
+
+**Chat / inbox message thread. CONTROLLED & data-driven like Kanban — you own `value` (messages array) and append in your own send handler; Conversation holds no message state. Consecutive messages from the same author are grouped (avatar + name shown once), day separators are inserted on date change, and outgoing messages (authorId === currentUserId) align right.**
+
+```ts
+import { Conversation } from "@usevyre/react"
+```
+
+## Valid Props
+
+| Prop | Values | Default |
+|------|--------|---------|
+| `composer` | `true` \| `false` | `false` |
+| `allowAttachments` | `true` \| `false` | `false` |
+
+## Common AI Mistakes
+
+- ❌ `Conversation without currentUserId`
+  → Always pass currentUserId matching one of the message authorId values
+- ❌ `Expecting Conversation to store/append messages`
+  → Append to your own state in onSend (or @send) and pass it back via value
+- ❌ `composer without onSend (React) / @send (Vue)`
+  → Provide onSend / @send to append the message to value
+- ❌ `Treating onSend as (text) only when using allowAttachments`
+  → Handle onSend(text, files) — map files to message attachments and append
+
+## Examples
+
+**Controlled thread with built-in composer**
+```tsx
+const [messages, setMessages] = useState([
+  { id: "1", authorId: "sam", authorName: "Sam", text: "Hey!" },
+  { id: "2", authorId: "me", text: "Hi \ud83d\udc4b", status: "read" },
+]);
+<Conversation
+  value={messages}
+  currentUserId="me"
+  composer
+  onSend={(t) => setMessages((m) => [...m, { id: crypto.randomUUID(), authorId: "me", text: t }])}
+/>
+```
+
+**Typing indicator + custom bubble**
+```tsx
+<Conversation
+  value={messages}
+  currentUserId="me"
+  typing="Sam is typing"
+  renderMessage={(m) => <strong>{m.text}</strong>}
+/>
+```
+
+**Message with image + file attachments**
+```tsx
+const messages = [
+  { id: "1", authorId: "sam", authorName: "Sam", text: "Moodboard \ud83d\udc47",
+    attachments: [{ kind: "image", url: "/board.png", name: "board.png" }] },
+  { id: "2", authorId: "me", text: "Specs:", status: "read",
+    attachments: [{ kind: "file", url: "/spec.pdf", name: "spec.pdf", size: "2.4 MB" }] },
+];
+<Conversation value={messages} currentUserId="me" />
+```

package/dist/cheat-sheets/datepicker.md

@@ -0,0 +1,36 @@
+# DatePicker — AI Cheat Sheet
+> Quick reference for Claude / Cursor / Copilot
+
+**Input trigger that opens a Calendar in a popover. Same modes as Calendar (single | range | multiple) plus a placeholder. Use this for a compact date field; use Calendar for an always-visible grid, or DateRangePicker for start/end ranges with presets.**
+
+```ts
+import { DatePicker } from "@usevyre/react"
+```
+
+## Valid Props
+
+| Prop | Values | Default |
+|------|--------|---------|
+| `mode` | `"single"` \| `"range"` \| `"multiple"` | `single` |
+| `weekStartsOn` | `"0"` \| `"1"` | `1` |
+| `showTime` | `true` \| `false` | `false` |
+
+## Common AI Mistakes
+
+- ❌ `DatePicker mode="range" for { from, to } object`
+  → Use <DateRangePicker /> for the { from, to } object API + presets + dual month
+- ❌ `DatePicker without value/onChange`
+  → Provide value and onChange (e.g. from useState)
+
+## Examples
+
+**Single date field**
+```tsx
+const [date, setDate] = useState(null);
+<DatePicker value={date} onChange={setDate} placeholder="Pick a date" />
+```
+
+**Date + time**
+```tsx
+<DatePicker value={date} onChange={setDate} showTime />
+```

package/dist/cheat-sheets/daterangepicker.md

@@ -0,0 +1,37 @@
+# DateRangePicker — AI Cheat Sheet
+> Quick reference for Claude / Cursor / Copilot
+
+**Start/end date range picker. Built on Calendar (mode=range) with a friendlier { from, to } object API, a two-month side-by-side view, and preset shortcuts. Use this for report/filter date ranges; use DatePicker for a single date.**
+
+```ts
+import { DateRangePicker } from "@usevyre/react"
+```
+
+## Valid Props
+
+| Prop | Values | Default |
+|------|--------|---------|
+| `numberOfMonths` | `"1"` \| `"2"` | `2` |
+| `weekStartsOn` | `"0"` \| `"1"` | `1` |
+
+## Common AI Mistakes
+
+- ❌ `value={[from, to]}`
+  → Use value={{ from, to }} and read range.from / range.to
+- ❌ `DateRangePicker for a single date`
+  → Use <DatePicker /> for a single date
+- ❌ `presets="true" (string)`
+  → Use the bare prop: presets  (or presets={true})
+
+## Examples
+
+**Range picker with built-in presets**
+```tsx
+const [range, setRange] = useState({ from: null, to: null });
+<DateRangePicker value={range} onChange={setRange} presets />
+```
+
+**Single month, no presets**
+```tsx
+<DateRangePicker value={range} onChange={setRange} numberOfMonths={1} />
+```

package/dist/cheat-sheets/field.md

@@ -1,7 +1,7 @@
 # Field — AI Cheat Sheet
 > Quick reference for Claude / Cursor / Copilot
 
-**Form field wrapper providing label, hint text, and validation state for Input or Textarea.**
+**Form field wrapper. Two ways to use it (both supported): (1) props-based — pass label/hint/state/required for the common case; (2) composable — use the parts FieldLabel, FieldDescription, FieldError, FieldGroup, FieldSet for richer layouts (multiple controls, custom error placement). The props-based API is unchanged and still works.**
 
 ```ts
 import { Field, Input, Textarea } from "@usevyre/react"
@@ -18,6 +18,8 @@ import { Field, Input, Textarea } from "@usevyre/react"
 
 - ❌ `Applying state prop directly to Input`
   → Wrap Input in <Field state="error"> to apply validation styling
+- ❌ `Mixing props label/hint AND FieldLabel/FieldError for the same field`
+  → Pick one: either props-based (label/hint/state) OR composable parts
 
 ## Examples
 
@@ -34,3 +36,19 @@ import { Field, Input, Textarea } from "@usevyre/react"
   <Input leftElement={<SearchIcon />} placeholder="Search..." />
 </Field>
 ```
+
+**Composable field with explicit parts**
+```tsx
+<Field>
+  <FieldLabel required htmlFor="email">Email</FieldLabel>
+  <Input id="email" type="email" />
+  <FieldDescription>We\u2019ll never share it.</FieldDescription>
+  <FieldError>{errors.email}</FieldError>
+</Field>
+
+// Two controls side by side
+<FieldGroup orientation="horizontal">
+  <Field label="First name"><Input /></Field>
+  <Field label="Last name"><Input /></Field>
+</FieldGroup>
+```

package/dist/cheat-sheets/index.md

@@ -8,12 +8,15 @@ Quick reference for AI agents — one file per component.
 - [Badge](badge.md) — Small label for status, category, or count. Use dot prop for live status indicator.
 - [Breadcrumb](breadcrumb.md) — Navigation trail showing current page location in hierarchy.
 - [Button](button.md) — Triggers actions and navigation. The most commonly used interactive element.
-- [Calendar](calendar.md) — Date picker calendar widget for selecting single dates or ranges.
+- [Calendar](calendar.md) — Inline date-grid widget (always visible, no input). mode: single | range | multiple, optional time picker. For an input + popover use DatePicker; for start/end ranges with presets use DateRangePicker.
+- [DatePicker](datepicker.md) — Input trigger that opens a Calendar in a popover. Same modes as Calendar (single | range | multiple) plus a placeholder. Use this for a compact date field; use Calendar for an always-visible grid, or DateRangePicker for start/end ranges with presets.
 - [Card](card.md) — Content container with optional header, body, and footer sections.
 - [Checkbox](checkbox.md) — Binary toggle for boolean form values.
+- [RadioGroup](radiogroup.md) — Controlled single-choice group. RadioGroup owns the selected value; render it data-driven via the options array OR with composable <Radio> children for custom content. role=radiogroup with proper labelling. For multi-select use Checkbox; for a compact dropdown use Select.
+- [RichTextEditor](richtexteditor.md) — Controlled WYSIWYG editor. value is an HTML string; you own it in state and set it in onChange (React) / v-model (Vue). Native contentEditable + execCommand — zero dependencies. Toolbar: bold, italic, underline, strike, h1-h3, ordered/unordered lists, quote, code block, link, clear formatting.
 - [Command](command.md) — Command palette / search dialog. Use for search-first navigation or quick actions.
 - [DropdownMenu](dropdownmenu.md) — Contextual menu triggered by a button. Supports items, separators, checkbox items, radio groups, and sub-menus.
-- [Field](field.md) — Form field wrapper providing label, hint text, and validation state for Input or Textarea.
+- [Field](field.md) — Form field wrapper. Two ways to use it (both supported): (1) props-based — pass label/hint/state/required for the common case; (2) composable — use the parts FieldLabel, FieldDescription, FieldError, FieldGroup, FieldSet for richer layouts (multiple controls, custom error placement). The props-based API is unchanged and still works.
 - [Input](input.md) — Text input field. Wrap in Field for labels and validation. Use leftElement/rightElement for icons.
 - [Label](label.md) — Accessible form label. Associate with input via htmlFor.
 - [Modal](modal.md) — Dialog overlay for confirmations, forms, or focused content.
@@ -38,3 +41,7 @@ Quick reference for AI agents — one file per component.
 - [DataGrid](datagrid.md) — Table with built-in column sorting, loading skeletons, and empty state. Filtering and pagination are out of scope — compose with the Pagination component.
 - [Tag](tag.md) — Standalone display tag/chip for categories, labels, or filter chips. NOT an input — for tag input use TagsInput. Group multiple with TagGroup.
 - [TagGroup](taggroup.md) — Read-only container that lays out multiple Tag elements with automatic wrapping and consistent spacing. For tag input use TagsInput.
+- [Item](item.md) — Layout primitive for list rows, settings rows, and notification rows. Denser than Card — use Item (not Card) for repeated list rows.
+- [Kanban](kanban.md) — Drag-and-drop board: cards move between columns (or reorder within a column). CONTROLLED & data-driven like DataGrid. While dragging, a placeholder shows the exact drop position. Each card is wrapped in a Card (variant="outlined"); renderCard (React) / #card slot (Vue) can render ANY content incl. complex components (Avatar/Badge/Progress). Columns and cards accept an optional semantic color tint. Native HTML5 DnD, zero deps.
+- [Conversation](conversation.md) — Chat / inbox message thread. CONTROLLED & data-driven like Kanban — you own `value` (messages array) and append in your own send handler; Conversation holds no message state. Consecutive messages from the same author are grouped (avatar + name shown once), day separators are inserted on date change, and outgoing messages (authorId === currentUserId) align right.
+- [DateRangePicker](daterangepicker.md) — Start/end date range picker. Built on Calendar (mode=range) with a friendlier { from, to } object API, a two-month side-by-side view, and preset shortcuts. Use this for report/filter date ranges; use DatePicker for a single date.

package/dist/cheat-sheets/input.md

@@ -19,6 +19,8 @@ import { Input } from "@usevyre/react"
   → Use size="sm" | "md" | "lg"
 - ❌ `type="search" for search UI`
   → Import Command from @usevyre/react for search palettes
+- ❌ `Vue: binding Input/Textarea value without v-model`
+  → Use v-model on <Input>/<Textarea> in Vue; in React use value + onChange
 
 ## Examples
 

package/dist/cheat-sheets/item.md

@@ -0,0 +1,53 @@
+# Item — AI Cheat Sheet
+> Quick reference for Claude / Cursor / Copilot
+
+**Layout primitive for list rows, settings rows, and notification rows. Denser than Card — use Item (not Card) for repeated list rows.**
+
+```ts
+import { Item, ItemMedia, ItemContent, ItemTitle, ItemDescription, ItemActions, ItemGroup } from "@usevyre/react"
+```
+
+## Valid Props
+
+| Prop | Values | Default |
+|------|--------|---------|
+| `variant` | `"default"` \| `"outlined"` \| `"muted"` \| `"plain"` | `default` |
+| `size` | `"sm"` \| `"md"` \| `"lg"` | `md` |
+| `clickable` | `true` \| `false` | `false` |
+
+## Common AI Mistakes
+
+- ❌ `Card used for repeated list rows`
+  → Use <Item> (optionally inside <ItemGroup separated>) for list/settings rows
+- ❌ `Item variant="primary"`
+  → Use variant="default" | "outlined" | "muted"
+- ❌ `raw text directly inside Item`
+  → Wrap text in <ItemContent><ItemTitle>…</ItemTitle></ItemContent>
+
+## Examples
+
+**Settings row with media, content and a trailing switch**
+```tsx
+<Item>
+  <ItemMedia><BellIcon /></ItemMedia>
+  <ItemContent>
+    <ItemTitle>Notifications</ItemTitle>
+    <ItemDescription>Receive an email when someone mentions you.</ItemDescription>
+  </ItemContent>
+  <ItemActions>
+    <Switch defaultChecked />
+  </ItemActions>
+</Item>
+```
+
+**Grouped clickable list with dividers**
+```tsx
+<ItemGroup separated>
+  <Item clickable>
+    <ItemContent><ItemTitle>Profile</ItemTitle></ItemContent>
+  </Item>
+  <Item clickable>
+    <ItemContent><ItemTitle>Billing</ItemTitle></ItemContent>
+  </Item>
+</ItemGroup>
+```

package/dist/cheat-sheets/kanban.md

@@ -0,0 +1,59 @@
+# Kanban — AI Cheat Sheet
+> Quick reference for Claude / Cursor / Copilot
+
+**Drag-and-drop board: cards move between columns (or reorder within a column). CONTROLLED & data-driven like DataGrid. While dragging, a placeholder shows the exact drop position. Each card is wrapped in a Card (variant="outlined"); renderCard (React) / #card slot (Vue) can render ANY content incl. complex components (Avatar/Badge/Progress). Columns and cards accept an optional semantic color tint. Native HTML5 DnD, zero deps.**
+
+```ts
+import { Kanban } from "@usevyre/react"
+```
+
+## Common AI Mistakes
+
+- ❌ `Kanban without onChange (or ignoring it)`
+  → Store columns in state and setColumns in onChange (v-model in Vue)
+- ❌ `Duplicate card ids across columns`
+  → Use globally-unique card ids across the entire board
+- ❌ `Mutating value in place then calling onChange`
+  → Pass the new array Kanban gives you straight to setState / v-model
+- ❌ `color="blue" (or any non-semantic value)`
+  → Use one of: "default" | "accent" | "teal" | "success" | "warning" | "danger"
+
+## Examples
+
+**Controlled board**
+```tsx
+const [columns, setColumns] = useState([
+  { id: "todo",  title: "To Do",       cards: [{ id: "1", title: "Spec API" }] },
+  { id: "doing", title: "In Progress", cards: [] },
+  { id: "done",  title: "Done",        cards: [{ id: "2", title: "Kickoff" }] },
+]);
+<Kanban value={columns} onChange={setColumns} />
+```
+
+**Custom card body + click handler**
+```tsx
+<Kanban
+  value={columns}
+  onChange={setColumns}
+  onCardClick={(card) => openDetail(card.id)}
+  renderCard={(card) => (
+    <><strong>{card.title}</strong><Badge>{card.id}</Badge></>
+  )}
+/>
+```
+
+**Tinted columns/cards + complex card content**
+```tsx
+const [cols, setCols] = useState([
+  { id: "doing", title: "In Progress", color: "teal", cards: [
+    { id: "t1", title: "OAuth", assignee: "AK", progress: 60, color: "warning" },
+  ]},
+]);
+<Kanban
+  value={cols}
+  onChange={setCols}
+  renderCard={(card) => (
+    <><strong>{card.title}</strong><Progress value={card.progress} /></>
+  )}
+/>
+```

package/dist/cheat-sheets/radiogroup.md

@@ -0,0 +1,47 @@
+# RadioGroup — AI Cheat Sheet
+> Quick reference for Claude / Cursor / Copilot
+
+**Controlled single-choice group. RadioGroup owns the selected value; render it data-driven via the options array OR with composable <Radio> children for custom content. role=radiogroup with proper labelling. For multi-select use Checkbox; for a compact dropdown use Select.**
+
+```ts
+import { RadioGroup, Radio } from "@usevyre/react"
+```
+
+## Valid Props
+
+| Prop | Values | Default |
+|------|--------|---------|
+| `size` | `"sm"` \| `"md"` | `md` |
+| `orientation` | `"vertical"` \| `"horizontal"` | `vertical` |
+| `disabled` | `true` \| `false` | `false` |
+
+## Common AI Mistakes
+
+- ❌ `<Radio> used outside a <RadioGroup>`
+  → Always wrap <Radio> in <RadioGroup>
+- ❌ `RadioGroup without value/onChange (React) or v-model (Vue)`
+  → Bind value + onChange (React) or v-model (Vue); or defaultValue for uncontrolled in React
+- ❌ `Using Checkbox for mutually-exclusive choices`
+  → Use RadioGroup + Radio (or options) for one-of-many
+
+## Examples
+
+**Data-driven**
+```tsx
+<RadioGroup
+  value={plan}
+  onChange={setPlan}
+  options={[
+    { value: "free", label: "Free", description: "For hobby projects" },
+    { value: "pro",  label: "Pro",  description: "For teams" },
+  ]}
+/>
+```
+
+**Composable children**
+```tsx
+<RadioGroup value={plan} onChange={setPlan} orientation="horizontal">
+  <Radio value="free" label="Free" />
+  <Radio value="pro"  label="Pro" />
+</RadioGroup>
+```