@devalok/shilp-sutra 0.48.0 → 0.49.1

package/mcp-manifest.json

@@ -1,8 +1,8 @@
 {
   "$schema": "./mcp-manifest.schema.json",
-  "manifestVersion": "1.1.0",
+  "manifestVersion": "1.2.0",
   "package": "@devalok/shilp-sutra",
-  "packageVersion": "0.48.0",
+  "packageVersion": "0.49.1",
   "components": {
     "accordion": {
       "displayName": "Accordion",
@@ -1106,7 +1106,7 @@
       "displayName": "Breadcrumb",
       "tier": "ui",
       "import": "@devalok/shilp-sutra/ui/breadcrumb",
-      "serverSafe": false,
+      "serverSafe": true,
       "description": "",
       "props": {},
       "composition": {
@@ -1617,28 +1617,6 @@
           },
           "required": false,
           "description": "enables hover shadow lift + pointer cursor"
-        },
-        "placement": {
-          "type": {
-            "name": "union",
-            "raw": "\"top-right\" (default) | \"top-left\" | \"bottom-right\" | \"bottom-left\""
-          },
-          "required": false
-        },
-        "tuck": {
-          "type": {
-            "name": "boolean"
-          },
-          "required": false,
-          "description": "pull a step toward the corner so an icon button's glyph aligns to the content edge"
-        },
-        "side": {
-          "type": {
-            "name": "union",
-            "raw": "\"x\" (default) | \"top\" | \"bottom\" | \"y\" | \"all\""
-          },
-          "required": false,
-          "description": "which card padding to negate; top/bottom/y for direct children — inherit the card radius; x/all for content inside a slot"
         }
       },
       "composition": {
@@ -1702,6 +1680,38 @@
         "size": "md",
         "orientation": "vertical"
       },
+      "subComponents": {
+        "CardAction": {
+          "props": {
+            "placement": {
+              "type": {
+                "name": "union",
+                "raw": "\"top-right\" (default) | \"top-left\" | \"bottom-right\" | \"bottom-left\""
+              },
+              "required": false
+            },
+            "tuck": {
+              "type": {
+                "name": "boolean"
+              },
+              "required": false,
+              "description": "pull a step toward the corner so an icon button's glyph aligns to the content edge"
+            }
+          }
+        },
+        "CardBleed": {
+          "props": {
+            "side": {
+              "type": {
+                "name": "union",
+                "raw": "\"x\" (default) | \"top\" | \"bottom\" | \"y\" | \"all\""
+              },
+              "required": false,
+              "description": "which card padding to negate; top/bottom/y for direct children — inherit the card radius; x/all for content inside a slot"
+            }
+          }
+        }
+      },
       "examples": [
         "<Card variant=\"elevated\" interactive onClick={() => navigate(url)}>\n  <CardHeader>\n    <CardTitle>Project</CardTitle>\n    <CardDescription>Last updated 2h ago</CardDescription>\n  </CardHeader>\n  <CardContent><p>Content here</p></CardContent>\n</Card>"
       ],
@@ -1857,12 +1867,18 @@
           "required": false,
           "defaultValue": "md"
         },
-        "error": {
+        "state": {
           "type": {
-            "name": "boolean"
+            "name": "enum",
+            "value": [
+              "default",
+              "error",
+              "warning",
+              "success"
+            ]
           },
           "required": false,
-          "description": "shows red border"
+          "description": "validation border/bg tint; error sets aria-invalid. Inherited from FormField when omitted"
         },
         "indeterminate": {
           "type": {
@@ -1898,6 +1914,10 @@
         "WCAG 2.5.8 minimum target size met at md (24px); sm (20px) may fail if not paired with enough label hit area"
       ],
       "changes": [
+        {
+          "version": "0.49.0",
+          "summary": "**BREAKING** Removed the `error: boolean` prop; use `state` (`FieldState = \"default\" | \"error\" | \"warning\" | \"success\"`). Migrate `<Checkbox error />` → `<Checkbox state=\"error\" />`. Gains `warning`/`success` tints and now inherits state from `FormField`."
+        },
         {
           "version": "0.22.0",
           "summary": "**Changed** Check indicator animation from scale-bounce to path-draw (stroke draws progressively). Indeterminate dash also draws in."
@@ -2273,6 +2293,19 @@
           "description": "trigger height",
           "defaultValue": "md"
         },
+        "state": {
+          "type": {
+            "name": "enum",
+            "value": [
+              "default",
+              "error",
+              "warning",
+              "success"
+            ]
+          },
+          "required": false,
+          "description": "validation border tint; error sets aria-invalid. Inherited from FormField when omitted"
+        },
         "Multiple": {
           "type": {
             "name": "function",
@@ -2372,6 +2405,10 @@
         "Dropdown content is portalled to document.body — parent styles like `overflow: hidden` don't clip it, and container-scoped test queries won't find it"
       ],
       "changes": [
+        {
+          "version": "0.49.0",
+          "summary": "**Added** `state` prop (`FieldState = \"default\" | \"error\" | \"warning\" | \"success\"`) — unified field-state API. Renders a validation border tint + sets `aria-invalid`; inherits from `FormField` when omitted. (Additive — Combobox had no prior validation prop.)"
+        },
         {
           "version": "0.18.0",
           "summary": "**Added** `accessibleLabel` prop — custom aria-label for trigger, falls back to placeholder"
@@ -3171,6 +3208,130 @@
         }
       ]
     },
+    "dot": {
+      "displayName": "Dot",
+      "tier": "ui",
+      "import": "@devalok/shilp-sutra/ui/dot",
+      "serverSafe": false,
+      "description": "A small semantic status/indicator dot — the low-level primitive behind status pills, presence indicators, legend swatches, and `StatusDot`. Intent-coloured, sized, optionally pulsing, filled or ring.",
+      "props": {
+        "color": {
+          "type": {
+            "name": "enum",
+            "value": [
+              "accent",
+              "success",
+              "warning",
+              "error",
+              "info",
+              "neutral",
+              "current"
+            ]
+          },
+          "required": false,
+          "description": "intent colour; `current` inherits text colour"
+        },
+        "size": {
+          "type": {
+            "name": "enum",
+            "value": [
+              "xs",
+              "sm",
+              "md",
+              "lg"
+            ]
+          },
+          "required": false
+        },
+        "variant": {
+          "type": {
+            "name": "enum",
+            "value": [
+              "filled",
+              "ring",
+              "off"
+            ]
+          },
+          "required": false,
+          "description": "`off` = faint fill + light border, i.e. inactive"
+        },
+        "withBorder": {
+          "type": {
+            "name": "boolean"
+          },
+          "required": false,
+          "description": "contrast ring so the dot stays visible on busy/coloured backgrounds"
+        },
+        "pulse": {
+          "type": {
+            "name": "boolean"
+          },
+          "required": false,
+          "description": "animate a pulsing ripple; ignored for `off`"
+        },
+        "pulseSpeed": {
+          "type": {
+            "name": "enum",
+            "value": [
+              "slow",
+              "normal",
+              "fast"
+            ]
+          },
+          "required": false,
+          "description": "pulse tempo"
+        },
+        "label": {
+          "type": {
+            "name": "ReactNode"
+          },
+          "required": false,
+          "description": "inline text; makes the dot an announced status"
+        },
+        "labelPosition": {
+          "type": {
+            "name": "enum",
+            "value": [
+              "start",
+              "end"
+            ]
+          },
+          "required": false,
+          "description": "which side the label sits on"
+        },
+        "labelClassName": {
+          "type": {
+            "name": "string"
+          },
+          "required": false
+        }
+      },
+      "composition": {
+        "notes": [
+          "**Decorative vs announced.** A bare `<Dot>` is `aria-hidden` (the surrounding element carries meaning — e.g. a Badge's text). Pass a `label` (or `aria-label`) to make it a `role=\"status\"` announced indicator.",
+          "**Intent colour, shared vocabulary.** `color` uses the same intent names as the rest of the system (`accent/success/warning/error/info/neutral`), so a Dot next to a Badge/Button of the same intent matches.",
+          "**`pulse` = \"live\".** Off by default (static status). Turn it on for active/attention states (recording, live, connecting) — a pulsing dot reads as \"happening now\", so leave it off for settled statuses.",
+          "**Powers the higher-level pieces.** `StatusBadge` composes `<Badge>` + `<Dot>`; use `Dot` directly anywhere you need a coloured indicator without a pill.",
+          "**Three treatments:** `filled` (active), `ring` (hollow outline), `off` (faint same-tone fill + light border — present but inactive/disabled).",
+          "**`withBorder`** adds a contrast ring (`ring-2 ring-surface-raised`) so the dot reads on avatars, images, or coloured fills — the pattern Avatar's status dot uses.",
+          "**`pulseSpeed`** (slow/normal/fast) tunes the pulse tempo — fast for urgent (recording), slow for ambient (syncing)."
+        ]
+      },
+      "docPath": "docs/components/ui/dot.md",
+      "examples": [
+        "<Dot color=\"success\" />                                 {/* bare, decorative */}\n<Dot color=\"error\" pulse pulseSpeed=\"fast\" label=\"Recording\" />  {/* pulsing + announced */}\n<Dot color=\"neutral\" variant=\"off\" label=\"Offline\" />  {/* inactive: faint fill + light border */}\n<Dot color=\"success\" withBorder />                      {/* contrast ring for busy backgrounds */}\n<Dot color=\"accent\" label=\"3 online\" labelPosition=\"start\" />  {/* label before the dot */}\n<Dot color=\"neutral\" variant=\"ring\" size=\"lg\" />        {/* hollow ring */}\n\n// As leading content in a pill:\n<Badge variant=\"soft\" color=\"warning\" startIcon={<Dot color=\"warning\" size=\"sm\" />}>\n  Pending\n</Badge>"
+      ],
+      "gotchas": [
+        "A bare dot is decorative by design — if a dot is the *only* signal (no adjacent text), give it a `label` or `aria-label` so it's announced.",
+        "`pulse` respects `prefers-reduced-motion` (the ripple is disabled)."
+      ],
+      "changes": [
+        {
+          "version": "0.49.0",
+          "summary": "**Added** Initial release. Extracted as the shared primitive behind `StatusDot`, `StatusBadge`, and `Badge`'s dot. Colours `accent/success/warning/error/info/neutral/current`; sizes `xs–lg`; variants `filled/ring/off`; `withBorder` contrast ring; `pulse` + `pulseSpeed`; `label` + `labelPosition`."
+        }
+      ]
+    },
     "dropdown-menu": {
       "displayName": "DropdownMenu",
       "tier": "ui",
@@ -3372,7 +3533,7 @@
             ]
           },
           "required": false,
-          "description": "inherits from FormField context"
+          "defaultValue": "helper"
         },
         "helperTextId": {
           "type": {
@@ -3396,6 +3557,25 @@
         ]
       },
       "docPath": "docs/components/ui/form.md",
+      "subComponents": {
+        "FormHelperText": {
+          "props": {
+            "state": {
+              "type": {
+                "name": "enum",
+                "value": [
+                  "helper",
+                  "error",
+                  "warning",
+                  "success"
+                ]
+              },
+              "required": false,
+              "description": "inherits from FormField context"
+            }
+          }
+        }
+      },
       "examples": [
         "<FormField state=\"error\">\n  <Label htmlFor=\"email\">Email</Label>\n  <Input id=\"email\" state=\"error\" />\n  <FormHelperText>Please enter a valid email.</FormHelperText>\n</FormField>"
       ],
@@ -3991,13 +4171,6 @@
           },
           "required": false,
           "description": "on the outer group container — separate from inner input's className"
-        },
-        "index": {
-          "type": {
-            "name": "object",
-            "raw": "number (REQUIRED, 0-based) — which position this slot renders"
-          },
-          "required": false
         }
       },
       "composition": {
@@ -4030,6 +4203,19 @@
         "size": "md",
         "state": "default"
       },
+      "subComponents": {
+        "InputOTPSlot": {
+          "props": {
+            "index": {
+              "type": {
+                "name": "object",
+                "raw": "number (REQUIRED, 0-based) — which position this slot renders"
+              },
+              "required": false
+            }
+          }
+        }
+      },
       "examples": [
         "<InputOTP maxLength={6} onComplete={verifyCode}>\n  <InputOTPGroup>\n    <InputOTPSlot index={0} />\n    <InputOTPSlot index={1} />\n    <InputOTPSlot index={2} />\n  </InputOTPGroup>\n  <InputOTPSeparator />\n  <InputOTPGroup>\n    <InputOTPSlot index={3} />\n    <InputOTPSlot index={4} />\n    <InputOTPSlot index={5} />\n  </InputOTPGroup>\n</InputOTP>"
       ],
@@ -4555,15 +4741,22 @@
       "tier": "ui",
       "import": "@devalok/shilp-sutra/ui/progress",
       "serverSafe": false,
-      "description": "",
+      "description": "A linear progress bar. Use the smart all-in-one `<Progress value={70} />` for the common cases, or the compound parts (`Progress.Root` / `Track` / `Indicator` / `Segment` / `Label` / `Value`) for full layout control and multi-segment bars.",
       "props": {
         "value": {
           "type": {
-            "name": "object",
-            "raw": "number (0-100) — omit for indeterminate"
+            "name": "union",
+            "raw": "number | null (0–max) — omit or null for an indeterminate bar"
           },
           "required": false
         },
+        "max": {
+          "type": {
+            "name": "number"
+          },
+          "required": false,
+          "description": "scale maximum, default 100"
+        },
         "size": {
           "type": {
             "name": "enum",
@@ -4580,7 +4773,7 @@
           "type": {
             "name": "enum",
             "value": [
-              "default",
+              "accent",
               "success",
               "warning",
               "error"
@@ -4594,43 +4787,103 @@
             "name": "boolean"
           },
           "required": false,
-          "description": "auto-shifts color by value: 0-59=default, 60-84=warning, 85-100=success, >100=error"
+          "description": "auto-shift color by value: 0-59=accent, 60-84=warning, 85-100=success, >100=error"
+        },
+        "label": {
+          "type": {
+            "name": "ReactNode"
+          },
+          "required": false,
+          "description": "descriptive label rendered before the bar; names the bar for a11y"
         },
-        "showLabel": {
+        "showValue": {
           "type": {
             "name": "boolean"
           },
           "required": false,
-          "description": "shows percentage text"
+          "description": "shows the \"{n}%\" readout after the bar"
+        },
+        "segments": {
+          "type": {
+            "name": "union",
+            "raw": "{ value: number; color?: \"accent\" | \"success\" | \"warning\" | \"error\" }[]"
+          },
+          "required": false,
+          "description": "multi-segment bar; overrides the single indicator"
+        },
+        "trackClassName": {
+          "type": {
+            "name": "string"
+          },
+          "required": false,
+          "description": "class for the Track element"
         },
         "indicatorClassName": {
           "type": {
             "name": "string"
           },
-          "required": false
+          "required": false,
+          "description": "class for the single Indicator; ignored when segments set"
         }
       },
       "composition": {
         "notes": [
-          "**Radix Progress** underneath — `value` (determinate) or absent (indeterminate). Standard ARIA: role=progressbar, aria-valuenow/min/max.",
-          "**autoColor semantic signal:** Maps value thresholds to color so consumers don't have to manually compute: 0–59=default, 60–84=warning, 85–100=success, >100=error. Useful for storage meters, budget trackers, goal progress.",
-          "**Indeterminate:** Omit `value` to get a continuous animated indeterminate bar. Use for unknown-duration loads.",
-          "**Progress vs ProgressRing:** Progress is a linear bar (horizontal). ProgressRing is circular. ProgressRing offers multi-ring stacked variants; Progress doesn't.",
-          "**Inside Card/StatCard:** StatCard has a `progress` prop that renders a thin inline version — use that inside StatCards instead of a separate Progress."
+          "**Two APIs, one component.** The smart `<Progress>` composes the parts for you; reach for the compound parts when you need a custom layout (label above the bar, value inside, multiple bars) or multi-segment fills. Structure follows Ark UI / Chakra; `Progress.Segment` follows Mantine.",
+          "**`Progress.Track` is the accessible progressbar** (role=progressbar, aria-valuenow/min/max from `Root`'s value). Give it a name via `aria-label`, or a `Progress.Label` + matching `aria-labelledby`. The smart form wires this from the `label` prop / a passed `aria-label` automatically.",
+          "**autoColor semantic signal:** maps value thresholds to color (0–59 accent · 60–84 warning · 85–100 success · >100 error) — storage meters, budget trackers, goal progress. Pass an explicit `color` to opt out.",
+          "**Segments** render side-by-side, each `value` as a % of `max`; the Track's aria value still reflects `Root`'s `value`.",
+          "**Indeterminate:** omit `value` (or pass `null`) for the continuous sweep. Motion-reduced users get a static bar.",
+          "**Progress vs ProgressRing:** Progress is linear; `ProgressRing` is circular (with multi-ring stacked variants)."
+        ],
+        "parts": [
+          {
+            "name": "Progress",
+            "description": "smart all-in-one — value/size/color/label/showValue/autoColor/segments"
+          },
+          {
+            "name": "Progress.Root",
+            "description": "layout container + context; owns value/max/size"
+          },
+          {
+            "name": "Progress.Label",
+            "description": "descriptive label; give it id + point Track's aria-labelledby at it"
+          },
+          {
+            "name": "Progress.Track",
+            "description": "the aria progressbar + track visual; holds Indicator or Segments"
+          },
+          {
+            "name": "Progress.Indicator",
+            "description": "single fill; color, or auto-color by value"
+          },
+          {
+            "name": "Progress.Segment",
+            "description": "one slice of a multi-segment bar — value + color"
+          },
+          {
+            "name": "Progress.Value",
+            "description": "the \"{n}%\" readout; custom via children or a `format` fn"
+          }
         ]
       },
       "docPath": "docs/components/ui/progress.md",
       "examples": [
-        "<Progress value={75} color=\"success\" showLabel />\n<Progress size=\"sm\" />  {/* indeterminate */}"
+        "// Simple:\n<Progress value={75} color=\"success\" showValue />\n<Progress size=\"sm\" />                                 {/* indeterminate */}\n<Progress value={80} autoColor showValue />            {/* color follows value */}\n\n// Multi-segment (Mantine-style):\n<Progress segments={[{ value: 40, color: 'success' }, { value: 30, color: 'warning' }]} />\n\n// Compound — full control:\n<Progress.Root value={62} size=\"lg\">\n  <Progress.Label id=\"storage-lbl\">Storage</Progress.Label>\n  <Progress.Track aria-labelledby=\"storage-lbl\">\n    <Progress.Indicator color=\"warning\" />\n  </Progress.Track>\n  <Progress.Value format={(pct) => `${pct}% of 50 GB`} />\n</Progress.Root>"
       ],
       "gotchas": [
-        "Omit value (or pass undefined) for indeterminate animation",
-        "`autoColor` overrides `color` when `value` is set — do not pass both unless you want autoColor to win"
+        "Omit `value` (or pass `null`) for indeterminate.",
+        "Pass an explicit `color` to override `autoColor`.",
+        "Compound `Progress.Track` needs a name — an `aria-label`, or a `Progress.Label` whose `id` the Track's `aria-labelledby` points to. A Track with neither is an unnamed progressbar (axe will flag it).",
+        "`Progress.Indicator` / `Segment` / `Value` throw if rendered outside `Progress.Root`."
       ],
       "changes": [
+        {
+          "version": "0.49.0",
+          "summary": "**BREAKING** Progress redesigned as a compound component. Renamed `showLabel` → `showValue`. The `color` neutral value `\"default\"` → `\"accent\"` (the type is now `\"accent\" | \"success\" | \"warning\" | \"error\"`). Added compound parts (`Progress.Root/Track/Indicator/Segment/Label/Value`), a `label` prop, a `max` prop, a `segments` prop (multi-segment bars), and `trackClassName`. Migrate `showLabel` → `showValue` and `color=\"default\"` → `color=\"accent\"` (or drop it — accent is the default)."
+        },
         {
           "version": "0.29.0",
-          "summary": "**Added** `autoColor` prop — automatically shifts indicator color based on value thresholds (0-59 default, 60-84 warning, 85-100 success, >100 error)"
+          "summary": "**Added** `autoColor` prop — automatically shifts indicator color based on value thresholds"
         },
         {
           "version": "0.1.0",
@@ -4700,13 +4953,6 @@
           },
           "required": false,
           "description": "accessible label — falls back to \"{n}% progress\""
-        },
-        "rings": {
-          "type": {
-            "name": "union",
-            "raw": "Array<{ value: number; max?: number; color?: \"default\" | \"success\" | \"warning\" | \"error\" | \"info\"; label?: string }>"
-          },
-          "required": false
         }
       },
       "composition": {
@@ -4725,6 +4971,30 @@
         "color": "default",
         "showValue": "{false}"
       },
+      "subComponents": {
+        "MultiProgressRing": {
+          "props": {
+            "rings": {
+              "type": {
+                "name": "union",
+                "raw": "Array<{ value: number; max?: number; color?: \"default\" | \"success\" | \"warning\" | \"error\" | \"info\"; label?: string }>"
+              },
+              "required": false
+            },
+            "size": {
+              "type": {
+                "name": "enum",
+                "value": [
+                  "sm",
+                  "md",
+                  "lg"
+                ]
+              },
+              "required": false
+            }
+          }
+        }
+      },
       "examples": [
         "<ProgressRing value={75} />\n<ProgressRing value={3} max={12} size=\"lg\" color=\"warning\" showValue />\n\n<MultiProgressRing\n  rings={[\n    { value: 80, color: 'error', label: 'Move' },\n    { value: 60, color: 'success', label: 'Exercise' },\n  ]}\n  size=\"lg\"\n/>"
       ],
@@ -4746,7 +5016,7 @@
             "name": "string"
           },
           "required": false,
-          "description": "REQUIRED — what's selected when this item is checked"
+          "description": "controlled"
         },
         "onValueChange": {
           "type": {
@@ -4766,7 +5036,7 @@
             "name": "boolean"
           },
           "required": false,
-          "description": "item-level override"
+          "description": "propagates to all items"
         },
         "orientation": {
           "type": {
@@ -4785,17 +5055,18 @@
           "required": false,
           "description": "form name for all items"
         },
-        "size": {
+        "state": {
           "type": {
             "name": "enum",
             "value": [
-              "sm",
-              "md",
-              "lg"
+              "default",
+              "error",
+              "warning",
+              "success"
             ]
           },
           "required": false,
-          "defaultValue": "md"
+          "description": "validation; sets aria-invalid on the group + tints item borders. Inherited from FormField when omitted"
         }
       },
       "composition": {
@@ -4804,7 +5075,7 @@
           "**RadioGroup propagates** `disabled` to every RadioGroupItem; items can opt back in with `disabled={false}` for granular control (rare).",
           "**Labels:** RadioGroupItem has no intrinsic label — pair each with `<Label htmlFor=\"x\" />` + `<RadioGroupItem id=\"x\" value=\"...\" />`. Screen readers announce the group label (from FormField or aria-labelledby on RadioGroup) plus each item's label.",
           "**Form libraries:** RadioGroup works with react-hook-form via Controller (onValueChange maps to field.onChange). The `name` prop puts a hidden form input per item for native form serialization.",
-          "**FormField integration:** RadioGroup does NOT auto-consume FormField error state. For error visuals, style the RadioGroup surround (e.g. via aria-invalid on a wrapping fieldset) — individual radios don't show red borders the way Inputs do."
+          "**FormField integration:** RadioGroup now consumes FormField state (or set `state` explicitly). It sets `aria-invalid` on the group and tints each item's border to match — unified with the other form controls via the shared `FieldState` type. An explicit `state` prop wins over FormField context."
         ],
         "parts": [
           {
@@ -4821,15 +5092,50 @@
       "defaults": {
         "size": "md"
       },
+      "subComponents": {
+        "RadioGroupItem": {
+          "props": {
+            "value": {
+              "type": {
+                "name": "string"
+              },
+              "required": false,
+              "description": "REQUIRED — what's selected when this item is checked"
+            },
+            "size": {
+              "type": {
+                "name": "enum",
+                "value": [
+                  "sm",
+                  "md",
+                  "lg"
+                ]
+              },
+              "required": false
+            },
+            "disabled": {
+              "type": {
+                "name": "boolean"
+              },
+              "required": false,
+              "description": "item-level override"
+            }
+          }
+        }
+      },
       "examples": [
         "<RadioGroup defaultValue=\"option-1\" onValueChange={setValue}>\n  <div className=\"flex items-center gap-2\">\n    <RadioGroupItem value=\"option-1\" id=\"r1\" />\n    <Label htmlFor=\"r1\">Option 1</Label>\n  </div>\n  <div className=\"flex items-center gap-2\">\n    <RadioGroupItem value=\"option-2\" id=\"r2\" />\n    <Label htmlFor=\"r2\">Option 2</Label>\n  </div>\n</RadioGroup>"
       ],
       "gotchas": [
         "Each RadioGroupItem needs a unique `value` prop",
         "Pair each item with a Label for accessibility",
-        "RadioGroup does NOT auto-inherit FormField error state — handle error styling at the group level"
+        "RadioGroup inherits FormField state; pass `state` explicitly to override"
       ],
       "changes": [
+        {
+          "version": "0.49.0",
+          "summary": "**Added** `state` prop on RadioGroup (`FieldState = \"default\" | \"error\" | \"warning\" | \"success\"`) — unified field-state API. Sets `aria-invalid` + tints item borders, and now inherits from `FormField` context."
+        },
         {
           "version": "0.4.2",
           "summary": "**Added** `RadioGroupProps`, `RadioGroupItemProps` type exports"
@@ -5024,65 +5330,25 @@
       "import": "@devalok/shilp-sutra/ui/select",
       "serverSafe": false,
       "description": "",
-      "props": {
-        "variant": {
-          "type": {
-            "name": "enum",
-            "value": [
-              "default",
-              "outline",
-              "ghost"
-            ]
-          },
-          "required": false,
-          "defaultValue": "default"
-        },
-        "color": {
-          "type": {
-            "name": "enum",
-            "value": [
-              "default",
-              "error",
-              "success",
-              "warning"
-            ]
-          },
-          "required": false,
-          "description": "sets aria-invalid when error",
-          "defaultValue": "default"
-        },
-        "size": {
-          "type": {
-            "name": "enum",
-            "value": [
-              "xs",
-              "sm",
-              "md",
-              "lg"
-            ]
-          },
-          "required": false,
-          "defaultValue": "md"
-        }
-      },
-      "composition": {
-        "notes": [
-          "**Radix Select** underneath — `value`/`onValueChange`/`defaultValue`/`open`/`onOpenChange` standard state.",
-          "**Styling props live on SelectTrigger, not Select root.** The Select root owns value/state; the Trigger owns appearance (variant/color/size). Setting `<Select size=\"lg\">` silently does nothing — TypeScript won't catch it.",
-          "**SelectItem requires `value`** — unique within the Select. Labels are the children of SelectItem.",
-          "**SelectGroup + SelectLabel:** Organize options into sections with a non-interactive section heading.",
-          "**FormField integration:** Set `color=\"error\"` on SelectTrigger for error visuals. Not auto-consumed from FormField (same as Checkbox/Radio — form-library convention for select controls).",
-          "**Portal + z-popover (1400):** content portals to body, stacks above Dialog/Sheet/other overlays.",
-          "**Select vs Combobox vs Autocomplete:** Select = short fixed list, click-to-open, no typeahead. Combobox = searchable, forced selection. Autocomplete = searchable, free text. Pick by list size and search need."
-        ],
-        "parts": [
-          {
-            "name": "Select",
-            "description": "root — value, onValueChange, defaultValue"
+      "props": {},
+      "composition": {
+        "notes": [
+          "**Radix Select** underneath — `value`/`onValueChange`/`defaultValue`/`open`/`onOpenChange` standard state.",
+          "**Styling props live on SelectTrigger, not Select root.** The Select root owns value/state; the Trigger owns appearance (variant/state/size). Setting `<Select size=\"lg\">` silently does nothing — TypeScript won't catch it.",
+          "**SelectItem requires `value`** — unique within the Select. Labels are the children of SelectItem.",
+          "**SelectGroup + SelectLabel:** Organize options into sections with a non-interactive section heading.",
+          "**FormField integration:** Set `state=\"error\"` on SelectTrigger for error visuals, or omit it inside a `<FormField state=\"error\">` — SelectTrigger now inherits the field state from context (explicit `state` prop wins). Unified with Input/Textarea/Checkbox/Radio/Switch/Combobox via the shared `FieldState` type.",
+          "**Portal + z-popover (1400):** content portals to body, stacks above Dialog/Sheet/other overlays.",
+          "**Select vs Combobox vs Autocomplete:** Select = short fixed list, click-to-open, no typeahead. Combobox = searchable, forced selection. Autocomplete = searchable, free text. Pick by list size and search need."
+        ],
+        "parts": [
+          {
+            "name": "Select",
+            "description": "root — value, onValueChange, defaultValue"
           },
           {
             "name": "SelectTrigger",
-            "description": "variant/color/size go HERE, not on Select root"
+            "description": "variant/state/size go HERE, not on Select root"
           },
           {
             "name": "SelectValue",
@@ -5111,9 +5377,51 @@
       "docPath": "docs/components/ui/select.md",
       "defaults": {
         "variant": "default",
-        "color": "default",
+        "state": "default",
         "size": "md"
       },
+      "subComponents": {
+        "SelectTrigger": {
+          "props": {
+            "variant": {
+              "type": {
+                "name": "enum",
+                "value": [
+                  "default",
+                  "outline",
+                  "ghost"
+                ]
+              },
+              "required": false
+            },
+            "state": {
+              "type": {
+                "name": "enum",
+                "value": [
+                  "default",
+                  "error",
+                  "warning",
+                  "success"
+                ]
+              },
+              "required": false,
+              "description": "validation; sets aria-invalid when error. Inherited from FormField when omitted"
+            },
+            "size": {
+              "type": {
+                "name": "enum",
+                "value": [
+                  "xs",
+                  "sm",
+                  "md",
+                  "lg"
+                ]
+              },
+              "required": false
+            }
+          }
+        }
+      },
       "examples": [
         "<Select onValueChange={setValue}>\n  <SelectTrigger size=\"lg\">\n    <SelectValue placeholder=\"Choose...\" />\n  </SelectTrigger>\n  <SelectContent>\n    <SelectItem value=\"a\">Option A</SelectItem>\n    <SelectItem value=\"b\">Option B</SelectItem>\n  </SelectContent>\n</Select>"
       ],
@@ -5122,6 +5430,10 @@
         "`<Select size=\"lg\">` is silently ignored (no TypeScript error)"
       ],
       "changes": [
+        {
+          "version": "0.49.0",
+          "summary": "**BREAKING** Renamed the SelectTrigger `color` prop → `state` (unified field-state API across all form controls; type `FieldState = \"default\" | \"error\" | \"warning\" | \"success\"`). Migrate `<SelectTrigger color=\"error\">` → `<SelectTrigger state=\"error\">`."
+        },
         {
           "version": "0.31.0",
           "summary": "**Added** `variant` prop on SelectTrigger: `default | outline | ghost`"
@@ -5204,21 +5516,7 @@
       "import": "@devalok/shilp-sutra/ui/sheet",
       "serverSafe": false,
       "description": "",
-      "props": {
-        "side": {
-          "type": {
-            "name": "enum",
-            "value": [
-              "top",
-              "bottom",
-              "left",
-              "right"
-            ]
-          },
-          "required": false,
-          "defaultValue": "right"
-        }
-      },
+      "props": {},
       "composition": {
         "notes": [
           "Same primitives as Dialog — open/onOpenChange/defaultOpen, trigger asChild, portal rendering, focus trap.",
@@ -5259,6 +5557,24 @@
       "defaults": {
         "side": "right"
       },
+      "subComponents": {
+        "SheetContent": {
+          "props": {
+            "side": {
+              "type": {
+                "name": "enum",
+                "value": [
+                  "top",
+                  "bottom",
+                  "left",
+                  "right"
+                ]
+              },
+              "required": false
+            }
+          }
+        }
+      },
       "examples": [
         "<Sheet>\n  <SheetTrigger asChild><Button>Open</Button></SheetTrigger>\n  <SheetContent side=\"right\">\n    <SheetHeader>\n      <SheetTitle>Settings</SheetTitle>\n    </SheetHeader>\n    <div>Content</div>\n  </SheetContent>\n</Sheet>"
       ],
@@ -5451,77 +5767,6 @@
           },
           "required": false,
           "defaultValue": "pulse"
-        },
-        "size": {
-          "type": {
-            "name": "enum",
-            "value": [
-              "sm",
-              "md",
-              "lg"
-            ]
-          },
-          "required": false,
-          "defaultValue": "md"
-        },
-        "lines": {
-          "type": {
-            "name": "number"
-          },
-          "required": false,
-          "defaultValue": 3
-        },
-        "lastLineWidth": {
-          "type": {
-            "name": "enum",
-            "value": [
-              "full",
-              "three-quarter",
-              "half"
-            ]
-          },
-          "required": false,
-          "defaultValue": "three-quarter"
-        },
-        "spacing": {
-          "type": {
-            "name": "enum",
-            "value": [
-              "sm",
-              "md"
-            ]
-          },
-          "required": false,
-          "defaultValue": "md"
-        },
-        "width": {
-          "type": {
-            "name": "string"
-          },
-          "required": false,
-          "defaultValue": "w-full"
-        },
-        "bars": {
-          "type": {
-            "name": "number"
-          },
-          "required": false,
-          "defaultValue": 7
-        },
-        "height": {
-          "type": {
-            "name": "string"
-          },
-          "required": false,
-          "defaultValue": "h-40"
-        },
-        "label": {
-          "type": {
-            "name": "object",
-            "raw": "string (default: \"Loading\") — accessible label for the loading state"
-          },
-          "required": false,
-          "defaultValue": "Loading"
         }
       },
       "composition": {
@@ -5546,6 +5791,212 @@
         "height": "h-40",
         "label": "Loading"
       },
+      "subComponents": {
+        "SkeletonAvatar": {
+          "props": {
+            "size": {
+              "type": {
+                "name": "enum",
+                "value": [
+                  "sm",
+                  "md",
+                  "lg",
+                  "xl"
+                ]
+              },
+              "required": false
+            },
+            "animation": {
+              "type": {
+                "name": "enum",
+                "value": [
+                  "pulse",
+                  "shimmer",
+                  "none"
+                ]
+              },
+              "required": false
+            }
+          }
+        },
+        "SkeletonText": {
+          "props": {
+            "lines": {
+              "type": {
+                "name": "number"
+              },
+              "required": false,
+              "defaultValue": 3
+            },
+            "lastLineWidth": {
+              "type": {
+                "name": "enum",
+                "value": [
+                  "full",
+                  "three-quarter",
+                  "half"
+                ]
+              },
+              "required": false,
+              "defaultValue": "three-quarter"
+            },
+            "spacing": {
+              "type": {
+                "name": "enum",
+                "value": [
+                  "sm",
+                  "md"
+                ]
+              },
+              "required": false,
+              "defaultValue": "md"
+            },
+            "animation": {
+              "type": {
+                "name": "enum",
+                "value": [
+                  "pulse",
+                  "shimmer",
+                  "none"
+                ]
+              },
+              "required": false
+            }
+          }
+        },
+        "SkeletonButton": {
+          "props": {
+            "size": {
+              "type": {
+                "name": "enum",
+                "value": [
+                  "sm",
+                  "md",
+                  "lg"
+                ]
+              },
+              "required": false
+            },
+            "width": {
+              "type": {
+                "name": "enum",
+                "value": [
+                  "auto",
+                  "full",
+                  "icon"
+                ]
+              },
+              "required": false
+            },
+            "animation": {
+              "type": {
+                "name": "enum",
+                "value": [
+                  "pulse",
+                  "shimmer",
+                  "none"
+                ]
+              },
+              "required": false
+            }
+          }
+        },
+        "SkeletonInput": {
+          "props": {
+            "size": {
+              "type": {
+                "name": "enum",
+                "value": [
+                  "sm",
+                  "md",
+                  "lg"
+                ]
+              },
+              "required": false
+            },
+            "animation": {
+              "type": {
+                "name": "enum",
+                "value": [
+                  "pulse",
+                  "shimmer",
+                  "none"
+                ]
+              },
+              "required": false
+            }
+          }
+        },
+        "SkeletonChart": {
+          "props": {
+            "bars": {
+              "type": {
+                "name": "number"
+              },
+              "required": false,
+              "defaultValue": 7
+            },
+            "height": {
+              "type": {
+                "name": "string"
+              },
+              "required": false,
+              "defaultValue": "h-40"
+            },
+            "animation": {
+              "type": {
+                "name": "enum",
+                "value": [
+                  "pulse",
+                  "shimmer",
+                  "none"
+                ]
+              },
+              "required": false
+            }
+          }
+        },
+        "SkeletonImage": {
+          "props": {
+            "width": {
+              "type": {
+                "name": "string"
+              },
+              "required": false,
+              "defaultValue": "w-full"
+            },
+            "height": {
+              "type": {
+                "name": "string"
+              },
+              "required": false,
+              "defaultValue": "h-40"
+            },
+            "animation": {
+              "type": {
+                "name": "enum",
+                "value": [
+                  "pulse",
+                  "shimmer",
+                  "none"
+                ]
+              },
+              "required": false
+            }
+          }
+        },
+        "SkeletonGroup": {
+          "props": {
+            "label": {
+              "type": {
+                "name": "object",
+                "raw": "string (default: \"Loading\") — accessible label for the loading state"
+              },
+              "required": false
+            }
+          }
+        }
+      },
       "examples": [
         "<Skeleton variant=\"text\" className=\"w-3/4\" />\n<Skeleton variant=\"circle\" className=\"h-12 w-12\" />\n<Skeleton variant=\"rectangle\" animation=\"shimmer\" className=\"h-48 w-full\" />\n\n<SkeletonGroup label=\"Loading user profile\">\n  <SkeletonAvatar size=\"lg\" />\n  <SkeletonText lines={2} />\n  <SkeletonButton />\n</SkeletonGroup>\n\n<SkeletonChart bars={5} height=\"h-32\" />\n<SkeletonImage height=\"h-64\" />"
       ],
@@ -6217,82 +6668,6 @@
         }
       ]
     },
-    "status-dot": {
-      "displayName": "StatusDot",
-      "tier": "ui",
-      "import": "@devalok/shilp-sutra/ui/status-dot",
-      "serverSafe": true,
-      "description": "",
-      "props": {
-        "status": {
-          "type": {
-            "name": "enum",
-            "value": [
-              "healthy",
-              "warning",
-              "critical",
-              "neutral",
-              "inactive"
-            ]
-          },
-          "required": false
-        },
-        "size": {
-          "type": {
-            "name": "enum",
-            "value": [
-              "sm",
-              "md",
-              "lg"
-            ]
-          },
-          "required": false,
-          "defaultValue": "md"
-        },
-        "pulse": {
-          "type": {
-            "name": "boolean"
-          },
-          "required": false,
-          "description": "ping animation; defaults to true for \"healthy\", false for others",
-          "defaultValue": "{status ==="
-        },
-        "label": {
-          "type": {
-            "name": "string"
-          },
-          "required": false,
-          "description": "inline text rendered after the dot"
-        },
-        "labelClassName": {
-          "type": {
-            "name": "string"
-          },
-          "required": false,
-          "description": "extra classes on the label span"
-        }
-      },
-      "composition": {
-        "notes": [
-          "**Server-safe presentational dot** — simple status indicator, pairs with inline text.",
-          "**Status semantics map to color:** healthy=success, warning=warning, critical=error, neutral=muted surface, inactive=dimmed. The pulse animation calls attention to \"healthy\" by default (active presence); you can flip it for other statuses by setting pulse explicitly.",
-          "**StatusDot vs BadgeIndicator vs StatusBadge:** - StatusDot = tiny presence/status indicator with optional inline label (e.g. \"Service online\") - BadgeIndicator = overlay on another element (notification dot on a bell icon) - StatusBadge (composed) = full pill-style badge with colored bg and label text (e.g. ticket status)",
-          "**Label composability:** If you pass `label`, it renders inline after the dot. Use `labelClassName` for custom typography (e.g. font-mono for status codes)."
-        ]
-      },
-      "docPath": "docs/components/ui/status-dot.md",
-      "defaults": {
-        "size": "md",
-        "pulse": "{status ==="
-      },
-      "examples": [
-        "<StatusDot status=\"healthy\" />\n<StatusDot status=\"critical\" label=\"Service down\" pulse />\n<StatusDot status=\"warning\" size=\"lg\" label=\"Elevated load\" />"
-      ],
-      "gotchas": [
-        "The `pulse` prop auto-enables for \"healthy\" status — pass `pulse={false}` to suppress",
-        "Status type is exported as `StatusDotStatus` if you need it in consumer code"
-      ]
-    },
     "stepper": {
       "displayName": "Stepper / Step",
       "tier": "ui",
@@ -6323,25 +6698,6 @@
             "raw": "<Step> elements"
           },
           "required": false
-        },
-        "label": {
-          "type": {
-            "name": "string"
-          },
-          "required": true
-        },
-        "description": {
-          "type": {
-            "name": "string"
-          },
-          "required": false
-        },
-        "icon": {
-          "type": {
-            "name": "ReactNode"
-          },
-          "required": false,
-          "description": "overrides default number/checkmark"
         }
       },
       "composition": {
@@ -6368,6 +6724,31 @@
         ]
       },
       "docPath": "docs/components/ui/stepper.md",
+      "subComponents": {
+        "Step": {
+          "props": {
+            "label": {
+              "type": {
+                "name": "string"
+              },
+              "required": true
+            },
+            "description": {
+              "type": {
+                "name": "string"
+              },
+              "required": false
+            },
+            "icon": {
+              "type": {
+                "name": "ReactNode"
+              },
+              "required": false,
+              "description": "overrides default number/checkmark"
+            }
+          }
+        }
+      },
       "examples": [
         "<Stepper activeStep={1}>\n  <Step label=\"Account\" description=\"Create credentials\" />\n  <Step label=\"Profile\" description=\"Add details\" />\n  <Step label=\"Review\" />\n</Stepper>"
       ],
@@ -6495,12 +6876,18 @@
           },
           "required": false
         },
-        "error": {
+        "state": {
           "type": {
-            "name": "boolean"
+            "name": "enum",
+            "value": [
+              "default",
+              "error",
+              "warning",
+              "success"
+            ]
           },
           "required": false,
-          "description": "shows red border/bg"
+          "description": "validation border/checked-track tint; error sets aria-invalid. Inherited from FormField when omitted. Distinct from `color`, the ON-track tint"
         },
         "disabled": {
           "type": {
@@ -6563,6 +6950,10 @@
         "Switch does NOT auto-consume FormField — pass `error` explicitly inside a FormField"
       ],
       "changes": [
+        {
+          "version": "0.49.0",
+          "summary": "**BREAKING** Removed the `error: boolean` prop; use `state` (`FieldState = \"default\" | \"error\" | \"warning\" | \"success\"`). Migrate `<Switch error />` → `<Switch state=\"error\" />`. Gains `warning`/`success` and inherits from `FormField`. (`color` is unchanged — it's the ON-track tint, not validation.)"
+        },
         {
           "version": "0.29.0",
           "summary": "**Added** `size` prop: `\"sm\"` (18px track) | `\"md\"` (24px, default) | `\"lg\"` (28px track)"
@@ -6605,28 +6996,6 @@
           },
           "required": false,
           "description": "opt-in zebra — even body rows get the faintest surface step; hairline separators remain the default row cue"
-        },
-        "numeric": {
-          "type": {
-            "name": "boolean"
-          },
-          "required": false,
-          "description": "right-align + tabular figures; header follows the column. Identifier-numbers — dates, phones, IDs — stay left"
-        },
-        "persist": {
-          "type": {
-            "name": "boolean"
-          },
-          "required": false,
-          "description": "always show instead of hover/focus reveal"
-        },
-        "href": {
-          "type": {
-            "name": "object",
-            "raw": "string (required); stretch: boolean"
-          },
-          "required": false,
-          "description": "default true"
         }
       },
       "composition": {
@@ -6677,6 +7046,59 @@
         ]
       },
       "docPath": "docs/components/ui/table.md",
+      "subComponents": {
+        "TableCell": {
+          "props": {
+            "numeric": {
+              "type": {
+                "name": "boolean"
+              },
+              "required": false,
+              "description": "right-align + tabular figures; header follows the column. Identifier-numbers — dates, phones, IDs — stay left"
+            }
+          }
+        },
+        "TableHead": {
+          "props": {
+            "numeric": {
+              "type": {
+                "name": "boolean"
+              },
+              "required": false,
+              "description": "right-align + tabular figures; header follows the column. Identifier-numbers — dates, phones, IDs — stay left"
+            }
+          }
+        },
+        "TableRowActions": {
+          "props": {
+            "persist": {
+              "type": {
+                "name": "boolean"
+              },
+              "required": false,
+              "description": "always show instead of hover/focus reveal"
+            }
+          }
+        },
+        "TableRowLink": {
+          "props": {
+            "href": {
+              "type": {
+                "name": "string"
+              },
+              "required": true
+            },
+            "stretch": {
+              "type": {
+                "name": "boolean"
+              },
+              "required": false,
+              "defaultValue": true
+            }
+          },
+          "note": "separate import: ui/table-row-link — client component"
+        }
+      },
       "examples": [
         "<Table>\n  <TableHeader>\n    <TableRow>\n      <TableHead>Name</TableHead>\n      <TableHead>Status</TableHead>\n    </TableRow>\n  </TableHeader>\n  <TableBody>\n    <TableRow>\n      <TableCell>Project Alpha</TableCell>\n      <TableCell><Badge color=\"success\">Active</Badge></TableCell>\n    </TableRow>\n  </TableBody>\n</Table>"
       ],
@@ -6770,7 +7192,7 @@
           "type": {
             "name": "string"
           },
-          "required": true
+          "required": false
         },
         "onValueChange": {
           "type": {
@@ -6778,37 +7200,6 @@
             "raw": "(value: string) => void"
           },
           "required": false
-        },
-        "variant": {
-          "type": {
-            "name": "object",
-            "raw": "(inherits from TabsList)"
-          },
-          "required": false,
-          "defaultValue": "line"
-        },
-        "size": {
-          "type": {
-            "name": "enum",
-            "value": [
-              "sm",
-              "md",
-              "lg"
-            ]
-          },
-          "required": false,
-          "defaultValue": "md"
-        },
-        "orientation": {
-          "type": {
-            "name": "enum",
-            "value": [
-              "horizontal",
-              "vertical"
-            ]
-          },
-          "required": false,
-          "defaultValue": "horizontal"
         }
       },
       "composition": {
@@ -6843,6 +7234,70 @@
         "size": "md",
         "orientation": "horizontal"
       },
+      "subComponents": {
+        "TabsList": {
+          "props": {
+            "variant": {
+              "type": {
+                "name": "enum",
+                "value": [
+                  "line",
+                  "contained"
+                ]
+              },
+              "required": false
+            },
+            "size": {
+              "type": {
+                "name": "enum",
+                "value": [
+                  "sm",
+                  "md",
+                  "lg"
+                ]
+              },
+              "required": false
+            },
+            "orientation": {
+              "type": {
+                "name": "enum",
+                "value": [
+                  "horizontal",
+                  "vertical"
+                ]
+              },
+              "required": false
+            }
+          }
+        },
+        "TabsTrigger": {
+          "props": {
+            "value": {
+              "type": {
+                "name": "string"
+              },
+              "required": true
+            },
+            "variant": {
+              "type": {
+                "name": "object",
+                "raw": "(inherits from TabsList)"
+              },
+              "required": false
+            }
+          }
+        },
+        "TabsContent": {
+          "props": {
+            "value": {
+              "type": {
+                "name": "string"
+              },
+              "required": true
+            }
+          }
+        }
+      },
       "examples": [
         "<Tabs defaultValue=\"overview\">\n  <TabsList variant=\"contained\">\n    <TabsTrigger value=\"overview\">Overview</TabsTrigger>\n    <TabsTrigger value=\"activity\">Activity</TabsTrigger>\n  </TabsList>\n  <TabsContent value=\"overview\">Overview content</TabsContent>\n  <TabsContent value=\"activity\">Activity content</TabsContent>\n</Tabs>"
       ],
@@ -7293,7 +7748,8 @@
         },
         "value": {
           "type": {
-            "name": "string"
+            "name": "union",
+            "raw": "string | string[]"
           },
           "required": false
         },
@@ -7327,6 +7783,18 @@
         "variant": "default",
         "size": "md"
       },
+      "subComponents": {
+        "ToggleGroupItem": {
+          "props": {
+            "value": {
+              "type": {
+                "name": "string"
+              },
+              "required": false
+            }
+          }
+        }
+      },
       "examples": [
         "<ToggleGroup type=\"single\" variant=\"outline\" size=\"sm\" value={alignment} onValueChange={setAlignment}>\n  <ToggleGroupItem value=\"left\"><IconAlignLeft /></ToggleGroupItem>\n  <ToggleGroupItem value=\"center\"><IconAlignCenter /></ToggleGroupItem>\n  <ToggleGroupItem value=\"right\"><IconAlignRight /></ToggleGroupItem>\n</ToggleGroup>"
       ],
@@ -7466,49 +7934,7 @@
             "name": "ReactNode"
           },
           "required": false,
-          "description": "nested TreeItems"
-        },
-        "itemId": {
-          "type": {
-            "name": "string"
-          },
-          "required": true
-        },
-        "label": {
-          "type": {
-            "name": "ReactNode"
-          },
-          "required": false
-        },
-        "secondaryLabel": {
-          "type": {
-            "name": "ReactNode"
-          },
-          "required": false
-        },
-        "icon": {
-          "type": {
-            "name": "ReactNode"
-          },
-          "required": false
-        },
-        "actions": {
-          "type": {
-            "name": "ReactNode"
-          },
-          "required": false
-        },
-        "disabled": {
-          "type": {
-            "name": "boolean"
-          },
-          "required": false
-        },
-        "depth": {
-          "type": {
-            "name": "number"
-          },
-          "required": false
+          "description": "declarative mode"
         }
       },
       "composition": {
@@ -7521,6 +7947,61 @@
         ]
       },
       "docPath": "docs/components/ui/tree-view.md",
+      "subComponents": {
+        "TreeItem": {
+          "props": {
+            "itemId": {
+              "type": {
+                "name": "string"
+              },
+              "required": true
+            },
+            "label": {
+              "type": {
+                "name": "ReactNode"
+              },
+              "required": false
+            },
+            "secondaryLabel": {
+              "type": {
+                "name": "ReactNode"
+              },
+              "required": false
+            },
+            "icon": {
+              "type": {
+                "name": "ReactNode"
+              },
+              "required": false
+            },
+            "actions": {
+              "type": {
+                "name": "ReactNode"
+              },
+              "required": false
+            },
+            "disabled": {
+              "type": {
+                "name": "boolean"
+              },
+              "required": false
+            },
+            "depth": {
+              "type": {
+                "name": "number"
+              },
+              "required": false
+            },
+            "children": {
+              "type": {
+                "name": "ReactNode"
+              },
+              "required": false,
+              "description": "nested TreeItems"
+            }
+          }
+        }
+      },
       "gotchas": [
         "Supports both data-driven (items prop) and declarative (children) modes",
         "Don't mix data-driven and declarative in the same TreeView — pick one",
@@ -7971,43 +8452,6 @@
             "name": "string"
           },
           "required": false
-        },
-        "label": {
-          "type": {
-            "name": "string"
-          },
-          "required": false
-        },
-        "icon": {
-          "type": {
-            "name": "object",
-            "raw": "ComponentType<{ className?: string }>"
-          },
-          "required": false,
-          "description": "optional icon component"
-        },
-        "onClick": {
-          "type": {
-            "name": "function",
-            "raw": "() => void"
-          },
-          "required": false
-        },
-        "color": {
-          "type": {
-            "name": "enum",
-            "value": [
-              "default",
-              "error"
-            ]
-          },
-          "required": false
-        },
-        "disabled": {
-          "type": {
-            "name": "boolean"
-          },
-          "required": false
         }
       },
       "composition": {
@@ -8019,6 +8463,49 @@
         ]
       },
       "docPath": "docs/components/composed/bulk-action-bar.md",
+      "subComponents": {
+        "BulkActionBarAction": {
+          "props": {
+            "label": {
+              "type": {
+                "name": "string"
+              },
+              "required": false
+            },
+            "icon": {
+              "type": {
+                "name": "object",
+                "raw": "ComponentType<{ className?: string }>"
+              },
+              "required": false,
+              "description": "optional icon component"
+            },
+            "onClick": {
+              "type": {
+                "name": "function",
+                "raw": "() => void"
+              },
+              "required": false
+            },
+            "color": {
+              "type": {
+                "name": "enum",
+                "value": [
+                  "default",
+                  "error"
+                ]
+              },
+              "required": false
+            },
+            "disabled": {
+              "type": {
+                "name": "boolean"
+              },
+              "required": false
+            }
+          }
+        }
+      },
       "examples": [
         "<BulkActionBar\n  show={selected.length > 0}\n  count={selected.length}\n  onClearSelection={() => setSelected([])}\n  actions={[\n    { label: 'Archive', icon: IconArchive, onClick: archiveSelected },\n    { label: 'Delete', icon: IconTrash, onClick: deleteSelected, color: 'error' },\n  ]}\n/>"
       ],
@@ -8321,13 +8808,12 @@
             "name": "union",
             "raw": "Date | null"
           },
-          "required": false,
-          "description": "time stored as a Date object"
+          "required": false
         },
         "onChange": {
           "type": {
             "name": "function",
-            "raw": "(date: Date) => void"
+            "raw": "(date: Date | null) => void"
           },
           "required": false
         },
@@ -8336,7 +8822,7 @@
             "name": "string"
           },
           "required": false,
-          "defaultValue": "Pick a time"
+          "defaultValue": "Pick a date"
         },
         "formatStr": {
           "type": {
@@ -8371,292 +8857,524 @@
             "name": "string"
           },
           "required": false
+        }
+      },
+      "composition": {
+        "notes": [
+          "**7 sub-components in one kit:** DatePicker, DateRangePicker, DateTimePicker, TimePicker, CalendarGrid, MonthPicker, YearPicker, Presets. Built on Popover (trigger + calendar content) + date-fns.",
+          "**Layered abstractions:** - High-level: DatePicker / DateRangePicker / DateTimePicker / TimePicker (use these 95% of the time — Popover-wrapped, single-field pickers with formatted value display). - Low-level: CalendarGrid / MonthPicker / YearPicker (use for custom picker layouts, inline calendars, dashboards with embedded date selection).",
+          "**useCalendar hook** manages month navigation state — use it when building custom picker UI (e.g. inline calendar with custom header).",
+          "**Presets component** is standalone — drop it next to a DateRangePicker's calendar for quick-select sidebars (Today / Last 7 days / This month / etc.).",
+          "**Events on calendar:** CalendarGrid accepts `events: { date, color, label }[]` — renders up to 3 colored dots per day cell. Useful for availability / booked-days highlights.",
+          "**min/max/disabledDates** are shared contract across the whole family — pass the same bounds config to any date picker variant."
+        ]
+      },
+      "docPath": "docs/components/composed/date-picker.md",
+      "defaults": {
+        "placeholder": "Pick a date range",
+        "formatStr": "MMM d",
+        "numberOfMonths": 1,
+        "format": "12h",
+        "minuteStep": 1,
+        "secondStep": 1,
+        "showSeconds": false
+      },
+      "subComponents": {
+        "DateRangePicker": {
+          "props": {
+            "startDate": {
+              "type": {
+                "name": "union",
+                "raw": "Date | null"
+              },
+              "required": false
+            },
+            "endDate": {
+              "type": {
+                "name": "union",
+                "raw": "Date | null"
+              },
+              "required": false
+            },
+            "onChange": {
+              "type": {
+                "name": "function",
+                "raw": "(range: { start: Date | null, end: Date | null }) => void"
+              },
+              "required": false
+            },
+            "placeholder": {
+              "type": {
+                "name": "string"
+              },
+              "required": false,
+              "defaultValue": "Pick a date range"
+            },
+            "formatStr": {
+              "type": {
+                "name": "string"
+              },
+              "required": false,
+              "defaultValue": "MMM d, yyyy"
+            },
+            "minDate": {
+              "type": {
+                "name": "object",
+                "raw": "Date"
+              },
+              "required": false
+            },
+            "maxDate": {
+              "type": {
+                "name": "object",
+                "raw": "Date"
+              },
+              "required": false
+            },
+            "disabledDates": {
+              "type": {
+                "name": "function",
+                "raw": "(date: Date) => boolean"
+              },
+              "required": false
+            },
+            "presets": {
+              "type": {
+                "name": "object",
+                "raw": "PresetKey[]"
+              },
+              "required": false,
+              "description": "shows quick-select sidebar"
+            },
+            "numberOfMonths": {
+              "type": {
+                "name": "number"
+              },
+              "required": false,
+              "defaultValue": 1
+            }
+          }
         },
-        "startDate": {
-          "type": {
-            "name": "union",
-            "raw": "Date | null"
-          },
-          "required": false
+        "DateTimePicker": {
+          "props": {
+            "value": {
+              "type": {
+                "name": "union",
+                "raw": "Date | null"
+              },
+              "required": false
+            },
+            "onChange": {
+              "type": {
+                "name": "function",
+                "raw": "(date: Date | null) => void"
+              },
+              "required": false
+            },
+            "minDate": {
+              "type": {
+                "name": "object",
+                "raw": "Date"
+              },
+              "required": false
+            },
+            "maxDate": {
+              "type": {
+                "name": "object",
+                "raw": "Date"
+              },
+              "required": false
+            },
+            "disabledDates": {
+              "type": {
+                "name": "function",
+                "raw": "(date: Date) => boolean"
+              },
+              "required": false
+            },
+            "timeFormat": {
+              "type": {
+                "name": "enum",
+                "value": [
+                  "12h",
+                  "24h"
+                ]
+              },
+              "required": false
+            },
+            "minuteStep": {
+              "type": {
+                "name": "number"
+              },
+              "required": false
+            },
+            "placeholder": {
+              "type": {
+                "name": "string"
+              },
+              "required": false
+            },
+            "className": {
+              "type": {
+                "name": "string"
+              },
+              "required": false
+            }
+          }
         },
-        "endDate": {
-          "type": {
-            "name": "union",
-            "raw": "Date | null"
-          },
-          "required": false
+        "TimePicker": {
+          "props": {
+            "value": {
+              "type": {
+                "name": "union",
+                "raw": "Date | null"
+              },
+              "required": false,
+              "description": "time stored as a Date object"
+            },
+            "onChange": {
+              "type": {
+                "name": "function",
+                "raw": "(date: Date) => void"
+              },
+              "required": false
+            },
+            "format": {
+              "type": {
+                "name": "enum",
+                "value": [
+                  "12h",
+                  "24h"
+                ]
+              },
+              "required": false,
+              "defaultValue": "12h"
+            },
+            "minuteStep": {
+              "type": {
+                "name": "number"
+              },
+              "required": false,
+              "defaultValue": 1
+            },
+            "secondStep": {
+              "type": {
+                "name": "number"
+              },
+              "required": false,
+              "defaultValue": 1
+            },
+            "showSeconds": {
+              "type": {
+                "name": "boolean"
+              },
+              "required": false,
+              "defaultValue": false
+            },
+            "placeholder": {
+              "type": {
+                "name": "string"
+              },
+              "required": false,
+              "defaultValue": "Pick a time"
+            },
+            "disabled": {
+              "type": {
+                "name": "boolean"
+              },
+              "required": false,
+              "defaultValue": false
+            },
+            "className": {
+              "type": {
+                "name": "string"
+              },
+              "required": false
+            }
+          }
         },
-        "presets": {
-          "type": {
-            "name": "object",
-            "raw": "PresetKey[]"
-          },
-          "required": true
+        "CalendarGrid": {
+          "props": {
+            "currentMonth": {
+              "type": {
+                "name": "object",
+                "raw": "Date"
+              },
+              "required": true
+            },
+            "selected": {
+              "type": {
+                "name": "union",
+                "raw": "Date | null"
+              },
+              "required": false
+            },
+            "rangeStart": {
+              "type": {
+                "name": "union",
+                "raw": "Date | null"
+              },
+              "required": false
+            },
+            "rangeEnd": {
+              "type": {
+                "name": "union",
+                "raw": "Date | null"
+              },
+              "required": false
+            },
+            "hoverDate": {
+              "type": {
+                "name": "union",
+                "raw": "Date | null"
+              },
+              "required": false
+            },
+            "onSelect": {
+              "type": {
+                "name": "function",
+                "raw": "(date: Date) => void (REQUIRED)"
+              },
+              "required": false
+            },
+            "onHover": {
+              "type": {
+                "name": "function",
+                "raw": "(date: Date | null) => void"
+              },
+              "required": false
+            },
+            "onMonthChange": {
+              "type": {
+                "name": "function",
+                "raw": "(date: Date) => void (REQUIRED)"
+              },
+              "required": false
+            },
+            "onHeaderClick": {
+              "type": {
+                "name": "function",
+                "raw": "() => void"
+              },
+              "required": false
+            },
+            "disabledDates": {
+              "type": {
+                "name": "function",
+                "raw": "(date: Date) => boolean"
+              },
+              "required": false
+            },
+            "minDate": {
+              "type": {
+                "name": "object",
+                "raw": "Date"
+              },
+              "required": false
+            },
+            "maxDate": {
+              "type": {
+                "name": "object",
+                "raw": "Date"
+              },
+              "required": false
+            },
+            "hidePrevNav": {
+              "type": {
+                "name": "boolean"
+              },
+              "required": false
+            },
+            "hideNextNav": {
+              "type": {
+                "name": "boolean"
+              },
+              "required": false
+            },
+            "events": {
+              "type": {
+                "name": "object",
+                "raw": "CalendarEvent[] — { date: Date, color?: string, label?: string }"
+              },
+              "required": false
+            }
+          }
+        },
+        "YearPicker": {
+          "props": {
+            "currentYear": {
+              "type": {
+                "name": "number"
+              },
+              "required": true
+            },
+            "selectedYear": {
+              "type": {
+                "name": "number"
+              },
+              "required": false
+            },
+            "onYearSelect": {
+              "type": {
+                "name": "function",
+                "raw": "(year: number) => void (REQUIRED)"
+              },
+              "required": false
+            },
+            "minDate": {
+              "type": {
+                "name": "object",
+                "raw": "Date"
+              },
+              "required": false
+            },
+            "maxDate": {
+              "type": {
+                "name": "object",
+                "raw": "Date"
+              },
+              "required": false
+            }
+          }
+        },
+        "MonthPicker": {
+          "props": {
+            "currentYear": {
+              "type": {
+                "name": "number"
+              },
+              "required": true
+            },
+            "selectedMonth": {
+              "type": {
+                "name": "number"
+              },
+              "required": false,
+              "description": "0-11"
+            },
+            "onMonthSelect": {
+              "type": {
+                "name": "function",
+                "raw": "(month: number) => void (REQUIRED)"
+              },
+              "required": false
+            },
+            "minDate": {
+              "type": {
+                "name": "object",
+                "raw": "Date"
+              },
+              "required": false
+            },
+            "maxDate": {
+              "type": {
+                "name": "object",
+                "raw": "Date"
+              },
+              "required": false
+            }
+          }
+        },
+        "Presets": {
+          "props": {
+            "presets": {
+              "type": {
+                "name": "object",
+                "raw": "PresetKey[]"
+              },
+              "required": true
+            },
+            "onSelect": {
+              "type": {
+                "name": "function",
+                "raw": "(start: Date, end: Date) => void (REQUIRED)"
+              },
+              "required": false
+            },
+            "className": {
+              "type": {
+                "name": "string"
+              },
+              "required": false
+            }
+          }
+        },
+        "useCalendar hook": {
+          "props": {}
+        }
+      },
+      "examples": [
+        "<DatePicker value={date} onChange={setDate} placeholder=\"Select date\" />\n\n<DateRangePicker\n  startDate={start}\n  endDate={end}\n  onChange={({ start, end }) => { setStart(start); setEnd(end); }}\n/>\n\n<DateTimePicker value={dateTime} onChange={setDateTime} timeFormat=\"12h\" minuteStep={15} />\n\n<TimePicker value={time} onChange={setTime} format=\"24h\" minuteStep={15} />"
+      ],
+      "gotchas": [
+        "TimePicker stores time inside a Date object — only hours/minutes/seconds are meaningful",
+        "CalendarGrid is a low-level building block — prefer DatePicker/DateRangePicker for most use cases",
+        "MonthPicker month values are 0-indexed (Jan=0, Dec=11) — same as JavaScript `Date.getMonth()`",
+        "YearPicker displays a 12-year grid based on the decade of `currentYear`",
+        "CalendarGrid supports up to 3 event dots per day cell",
+        "useCalendar is a convenience hook for managing calendar month state"
+      ],
+      "changes": [
+        {
+          "version": "0.18.0",
+          "summary": "**Fixed** Added `aria-label` to DatePicker/DateRangePicker trigger buttons"
+        },
+        {
+          "version": "0.4.2",
+          "summary": "**Changed** DateRangePicker default `formatStr` from `'MMM d'` to `'MMM d, yyyy'`"
         },
-        "numberOfMonths": {
+        {
+          "version": "0.1.0",
+          "summary": "**Added** Initial release"
+        }
+      ],
+      "peers": [
+        "date-fns"
+      ]
+    },
+    "deadline-indicator": {
+      "displayName": "DeadlineIndicator",
+      "tier": "composed",
+      "import": "@devalok/shilp-sutra/composed/deadline-indicator",
+      "serverSafe": true,
+      "description": "",
+      "props": {
+        "deadline": {
           "type": {
-            "name": "number"
+            "name": "union",
+            "raw": "Date | string"
           },
           "required": false,
-          "defaultValue": 1
+          "description": "deadline timestamp"
         },
-        "timeFormat": {
+        "warningThreshold": {
           "type": {
-            "name": "enum",
-            "value": [
-              "12h",
-              "24h"
-            ]
+            "name": "number"
           },
-          "required": false
+          "required": false,
+          "description": "minutes before deadline to show warning color",
+          "defaultValue": "{1440} (24h)"
         },
-        "minuteStep": {
+        "criticalThreshold": {
           "type": {
             "name": "number"
           },
           "required": false,
-          "defaultValue": 1
+          "description": "minutes before deadline to show critical/error color",
+          "defaultValue": "{240} (4h)"
         },
         "format": {
           "type": {
             "name": "enum",
             "value": [
-              "12h",
-              "24h"
+              "relative",
+              "absolute"
             ]
           },
           "required": false,
-          "defaultValue": "12h"
-        },
-        "secondStep": {
-          "type": {
-            "name": "number"
-          },
-          "required": false,
-          "defaultValue": 1
-        },
-        "showSeconds": {
-          "type": {
-            "name": "boolean"
-          },
-          "required": false,
-          "defaultValue": false
+          "defaultValue": "relative"
         },
-        "disabled": {
-          "type": {
-            "name": "boolean"
-          },
-          "required": false,
-          "defaultValue": false
-        },
-        "currentMonth": {
-          "type": {
-            "name": "object",
-            "raw": "Date"
-          },
-          "required": true
-        },
-        "selected": {
-          "type": {
-            "name": "union",
-            "raw": "Date | null"
-          },
-          "required": false
-        },
-        "rangeStart": {
-          "type": {
-            "name": "union",
-            "raw": "Date | null"
-          },
-          "required": false
-        },
-        "rangeEnd": {
-          "type": {
-            "name": "union",
-            "raw": "Date | null"
-          },
-          "required": false
-        },
-        "hoverDate": {
-          "type": {
-            "name": "union",
-            "raw": "Date | null"
-          },
-          "required": false
-        },
-        "onSelect": {
-          "type": {
-            "name": "function",
-            "raw": "(start: Date, end: Date) => void (REQUIRED)"
-          },
-          "required": false
-        },
-        "onHover": {
-          "type": {
-            "name": "function",
-            "raw": "(date: Date | null) => void"
-          },
-          "required": false
-        },
-        "onMonthChange": {
-          "type": {
-            "name": "function",
-            "raw": "(date: Date) => void (REQUIRED)"
-          },
-          "required": false
-        },
-        "onHeaderClick": {
-          "type": {
-            "name": "function",
-            "raw": "() => void"
-          },
-          "required": false
-        },
-        "hidePrevNav": {
-          "type": {
-            "name": "boolean"
-          },
-          "required": false
-        },
-        "hideNextNav": {
-          "type": {
-            "name": "boolean"
-          },
-          "required": false
-        },
-        "events": {
-          "type": {
-            "name": "object",
-            "raw": "CalendarEvent[] — { date: Date, color?: string, label?: string }"
-          },
-          "required": false
-        },
-        "currentYear": {
-          "type": {
-            "name": "number"
-          },
-          "required": true
-        },
-        "selectedYear": {
-          "type": {
-            "name": "number"
-          },
-          "required": false
-        },
-        "onYearSelect": {
-          "type": {
-            "name": "function",
-            "raw": "(year: number) => void (REQUIRED)"
-          },
-          "required": false
-        },
-        "selectedMonth": {
-          "type": {
-            "name": "number"
-          },
-          "required": false,
-          "description": "0-11"
-        },
-        "onMonthSelect": {
-          "type": {
-            "name": "function",
-            "raw": "(month: number) => void (REQUIRED)"
-          },
-          "required": false
-        }
-      },
-      "composition": {
-        "notes": [
-          "**7 sub-components in one kit:** DatePicker, DateRangePicker, DateTimePicker, TimePicker, CalendarGrid, MonthPicker, YearPicker, Presets. Built on Popover (trigger + calendar content) + date-fns.",
-          "**Layered abstractions:** - High-level: DatePicker / DateRangePicker / DateTimePicker / TimePicker (use these 95% of the time — Popover-wrapped, single-field pickers with formatted value display). - Low-level: CalendarGrid / MonthPicker / YearPicker (use for custom picker layouts, inline calendars, dashboards with embedded date selection).",
-          "**useCalendar hook** manages month navigation state — use it when building custom picker UI (e.g. inline calendar with custom header).",
-          "**Presets component** is standalone — drop it next to a DateRangePicker's calendar for quick-select sidebars (Today / Last 7 days / This month / etc.).",
-          "**Events on calendar:** CalendarGrid accepts `events: { date, color, label }[]` — renders up to 3 colored dots per day cell. Useful for availability / booked-days highlights.",
-          "**min/max/disabledDates** are shared contract across the whole family — pass the same bounds config to any date picker variant."
-        ]
-      },
-      "docPath": "docs/components/composed/date-picker.md",
-      "defaults": {
-        "placeholder": "Pick a date range",
-        "formatStr": "MMM d",
-        "numberOfMonths": 1,
-        "format": "12h",
-        "minuteStep": 1,
-        "secondStep": 1,
-        "showSeconds": false
-      },
-      "examples": [
-        "<DatePicker value={date} onChange={setDate} placeholder=\"Select date\" />\n\n<DateRangePicker\n  startDate={start}\n  endDate={end}\n  onChange={({ start, end }) => { setStart(start); setEnd(end); }}\n/>\n\n<DateTimePicker value={dateTime} onChange={setDateTime} timeFormat=\"12h\" minuteStep={15} />\n\n<TimePicker value={time} onChange={setTime} format=\"24h\" minuteStep={15} />"
-      ],
-      "gotchas": [
-        "TimePicker stores time inside a Date object — only hours/minutes/seconds are meaningful",
-        "CalendarGrid is a low-level building block — prefer DatePicker/DateRangePicker for most use cases",
-        "MonthPicker month values are 0-indexed (Jan=0, Dec=11) — same as JavaScript `Date.getMonth()`",
-        "YearPicker displays a 12-year grid based on the decade of `currentYear`",
-        "CalendarGrid supports up to 3 event dots per day cell",
-        "useCalendar is a convenience hook for managing calendar month state"
-      ],
-      "changes": [
-        {
-          "version": "0.18.0",
-          "summary": "**Fixed** Added `aria-label` to DatePicker/DateRangePicker trigger buttons"
-        },
-        {
-          "version": "0.4.2",
-          "summary": "**Changed** DateRangePicker default `formatStr` from `'MMM d'` to `'MMM d, yyyy'`"
-        },
-        {
-          "version": "0.1.0",
-          "summary": "**Added** Initial release"
-        }
-      ],
-      "peers": [
-        "date-fns"
-      ]
-    },
-    "deadline-indicator": {
-      "displayName": "DeadlineIndicator",
-      "tier": "composed",
-      "import": "@devalok/shilp-sutra/composed/deadline-indicator",
-      "serverSafe": true,
-      "description": "",
-      "props": {
-        "deadline": {
-          "type": {
-            "name": "union",
-            "raw": "Date | string"
-          },
-          "required": false,
-          "description": "deadline timestamp"
-        },
-        "warningThreshold": {
-          "type": {
-            "name": "number"
-          },
-          "required": false,
-          "description": "minutes before deadline to show warning color",
-          "defaultValue": "{1440} (24h)"
-        },
-        "criticalThreshold": {
-          "type": {
-            "name": "number"
-          },
-          "required": false,
-          "description": "minutes before deadline to show critical/error color",
-          "defaultValue": "{240} (4h)"
-        },
-        "format": {
-          "type": {
-            "name": "enum",
-            "value": [
-              "relative",
-              "absolute"
-            ]
-          },
-          "required": false,
-          "defaultValue": "relative"
-        },
-        "showIcon": {
+        "showIcon": {
           "type": {
             "name": "boolean"
           },
@@ -8716,44 +9434,6 @@
             "name": "string"
           },
           "required": false
-        },
-        "children": {
-          "type": {
-            "name": "ReactNode"
-          },
-          "required": false,
-          "description": "trigger element"
-        },
-        "align": {
-          "type": {
-            "name": "enum",
-            "value": [
-              "start",
-              "center",
-              "end"
-            ]
-          },
-          "required": false,
-          "defaultValue": "start"
-        },
-        "id": {
-          "type": {
-            "name": "string"
-          },
-          "required": false
-        },
-        "native": {
-          "type": {
-            "name": "string"
-          },
-          "required": false,
-          "description": "the emoji character"
-        },
-        "shortcodes": {
-          "type": {
-            "name": "string"
-          },
-          "required": false
         }
       },
       "composition": {
@@ -8771,6 +9451,54 @@
       "defaults": {
         "align": "start"
       },
+      "subComponents": {
+        "EmojiPickerPopover": {
+          "props": {
+            "children": {
+              "type": {
+                "name": "ReactNode"
+              },
+              "required": false,
+              "description": "trigger element"
+            },
+            "align": {
+              "type": {
+                "name": "enum",
+                "value": [
+                  "start",
+                  "center",
+                  "end"
+                ]
+              },
+              "required": false
+            }
+          },
+          "note": "extends EmojiPicker props"
+        },
+        "EmojiData": {
+          "props": {
+            "id": {
+              "type": {
+                "name": "string"
+              },
+              "required": false
+            },
+            "native": {
+              "type": {
+                "name": "string"
+              },
+              "required": false,
+              "description": "the emoji character"
+            },
+            "shortcodes": {
+              "type": {
+                "name": "string"
+              },
+              "required": false
+            }
+          }
+        }
+      },
       "examples": [
         "<EmojiPickerPopover onSelect={(emoji) => insertEmoji(emoji.native)}>\n  <Button variant=\"ghost\" size=\"icon-sm\">😀</Button>\n</EmojiPickerPopover>\n\n<EmojiPicker onSelect={handleEmoji} />"
       ],
@@ -9090,41 +9818,6 @@
           },
           "required": false,
           "description": "FilterSelect / FilterMultiSelect controls"
-        },
-        "label": {
-          "type": {
-            "name": "string"
-          },
-          "required": false
-        },
-        "value": {
-          "type": {
-            "name": "object",
-            "raw": "string[]"
-          },
-          "required": false
-        },
-        "onValueChange": {
-          "type": {
-            "name": "function",
-            "raw": "(values: string[]) => void"
-          },
-          "required": false
-        },
-        "options": {
-          "type": {
-            "name": "object",
-            "raw": "{ value: string; label: string }[]"
-          },
-          "required": false
-        },
-        "allLabel": {
-          "type": {
-            "name": "string"
-          },
-          "required": false,
-          "description": "label for the \"all\" option",
-          "defaultValue": "All"
         }
       },
       "composition": {
@@ -9143,6 +9836,76 @@
         "searchPlaceholder": "Search...",
         "allLabel": "All"
       },
+      "subComponents": {
+        "FilterSelect": {
+          "props": {
+            "label": {
+              "type": {
+                "name": "string"
+              },
+              "required": false
+            },
+            "value": {
+              "type": {
+                "name": "string"
+              },
+              "required": false
+            },
+            "onValueChange": {
+              "type": {
+                "name": "function",
+                "raw": "(value: string) => void"
+              },
+              "required": false
+            },
+            "options": {
+              "type": {
+                "name": "object",
+                "raw": "{ value: string; label: string }[]"
+              },
+              "required": false
+            },
+            "allLabel": {
+              "type": {
+                "name": "string"
+              },
+              "required": false,
+              "description": "label for the \"all\" option"
+            }
+          }
+        },
+        "FilterMultiSelect": {
+          "props": {
+            "label": {
+              "type": {
+                "name": "string"
+              },
+              "required": false
+            },
+            "value": {
+              "type": {
+                "name": "object",
+                "raw": "string[]"
+              },
+              "required": false
+            },
+            "onValueChange": {
+              "type": {
+                "name": "function",
+                "raw": "(values: string[]) => void"
+              },
+              "required": false
+            },
+            "options": {
+              "type": {
+                "name": "object",
+                "raw": "{ value: string; label: string }[]"
+              },
+              "required": false
+            }
+          }
+        }
+      },
       "examples": [
         "<FilterBar searchValue={search} onSearchChange={setSearch} onClearAll={clearFilters}>\n  <FilterSelect\n    label=\"Status\"\n    value={status}\n    onValueChange={setStatus}\n    options={[{ value: 'active', label: 'Active' }, { value: 'done', label: 'Done' }]}\n  />\n  <FilterMultiSelect\n    label=\"Assignees\"\n    value={assignees}\n    onValueChange={setAssignees}\n    options={memberOptions}\n  />\n</FilterBar>"
       ],
@@ -9351,42 +10114,7 @@
       "import": "@devalok/shilp-sutra/composed/loading-skeleton",
       "serverSafe": true,
       "description": "Exports: CardSkeleton, TableSkeleton, BoardSkeleton, ListSkeleton",
-      "props": {
-        "className": {
-          "type": {
-            "name": "string"
-          },
-          "required": false
-        },
-        "rows": {
-          "type": {
-            "name": "number"
-          },
-          "required": false,
-          "defaultValue": 6
-        },
-        "columns": {
-          "type": {
-            "name": "number"
-          },
-          "required": false,
-          "defaultValue": 4
-        },
-        "cardsPerColumn": {
-          "type": {
-            "name": "number"
-          },
-          "required": false,
-          "defaultValue": 3
-        },
-        "showAvatar": {
-          "type": {
-            "name": "boolean"
-          },
-          "required": false,
-          "defaultValue": true
-        }
-      },
+      "props": {},
       "composition": {
         "notes": [
           "**Pre-composed skeleton layouts** — CardSkeleton, TableSkeleton, BoardSkeleton, ListSkeleton. Each mimics the shape of a common DS layout so users see meaningful loading placeholders.",
@@ -9403,6 +10131,90 @@
         "cardsPerColumn": 3,
         "showAvatar": true
       },
+      "subComponents": {
+        "CardSkeleton": {
+          "props": {
+            "className": {
+              "type": {
+                "name": "string"
+              },
+              "required": false
+            }
+          }
+        },
+        "TableSkeleton": {
+          "props": {
+            "rows": {
+              "type": {
+                "name": "number"
+              },
+              "required": false,
+              "defaultValue": 5
+            },
+            "columns": {
+              "type": {
+                "name": "number"
+              },
+              "required": false,
+              "defaultValue": 4
+            },
+            "className": {
+              "type": {
+                "name": "string"
+              },
+              "required": false
+            }
+          }
+        },
+        "BoardSkeleton": {
+          "props": {
+            "columns": {
+              "type": {
+                "name": "number"
+              },
+              "required": false,
+              "defaultValue": 4
+            },
+            "cardsPerColumn": {
+              "type": {
+                "name": "number"
+              },
+              "required": false,
+              "defaultValue": 3
+            },
+            "className": {
+              "type": {
+                "name": "string"
+              },
+              "required": false
+            }
+          }
+        },
+        "ListSkeleton": {
+          "props": {
+            "rows": {
+              "type": {
+                "name": "number"
+              },
+              "required": false,
+              "defaultValue": 6
+            },
+            "showAvatar": {
+              "type": {
+                "name": "boolean"
+              },
+              "required": false,
+              "defaultValue": true
+            },
+            "className": {
+              "type": {
+                "name": "string"
+              },
+              "required": false
+            }
+          }
+        }
+      },
       "examples": [
         "<CardSkeleton />\n<TableSkeleton rows={8} columns={5} />\n<BoardSkeleton columns={3} cardsPerColumn={4} />\n<ListSkeleton rows={10} showAvatar={false} />"
       ],
@@ -9535,13 +10347,6 @@
           "required": false,
           "description": "below this, stacked mobile mode activates",
           "defaultValue": "md"
-        },
-        "active": {
-          "type": {
-            "name": "boolean"
-          },
-          "required": false,
-          "description": "highlights the item"
         }
       },
       "composition": {
@@ -9559,6 +10364,19 @@
         "masterWidth": "280px",
         "breakpoint": "md"
       },
+      "subComponents": {
+        "MasterDetail.ListItem": {
+          "props": {
+            "active": {
+              "type": {
+                "name": "boolean"
+              },
+              "required": false,
+              "description": "highlights the item"
+            }
+          }
+        }
+      },
       "examples": [
         "<MasterDetail selected={selectedId} onBack={() => setSelectedId(null)}>\n  <MasterDetail.List>\n    {items.map((item) => (\n      <MasterDetail.ListItem\n        key={item.id}\n        active={item.id === selectedId}\n        onClick={() => setSelectedId(item.id)}\n      >\n        {item.name}\n      </MasterDetail.ListItem>\n    ))}\n  </MasterDetail.List>\n  <MasterDetail.Detail>\n    {selectedId ? <ItemDetail id={selectedId} /> : <EmptyState />}\n  </MasterDetail.Detail>\n</MasterDetail>"
       ],
@@ -9663,7 +10481,8 @@
             "name": "object",
             "raw": "MultiSelectItem[]"
           },
-          "required": false
+          "required": false,
+          "description": "flat list — use `groups` for grouped rendering"
         },
         "groups": {
           "type": {
@@ -9759,36 +10578,6 @@
           },
           "required": false,
           "description": "trigger element"
-        },
-        "id": {
-          "type": {
-            "name": "string"
-          },
-          "required": false
-        },
-        "label": {
-          "type": {
-            "name": "string"
-          },
-          "required": false
-        },
-        "image": {
-          "type": {
-            "name": "string"
-          },
-          "required": false
-        },
-        "description": {
-          "type": {
-            "name": "string"
-          },
-          "required": false
-        },
-        "disabled": {
-          "type": {
-            "name": "boolean"
-          },
-          "required": false
         }
       },
       "composition": {
@@ -9809,6 +10598,59 @@
         "align": "start",
         "width": "{240}"
       },
+      "subComponents": {
+        "MultiSelectItem": {
+          "props": {
+            "id": {
+              "type": {
+                "name": "string"
+              },
+              "required": false
+            },
+            "label": {
+              "type": {
+                "name": "string"
+              },
+              "required": false
+            },
+            "image": {
+              "type": {
+                "name": "string"
+              },
+              "required": false
+            },
+            "description": {
+              "type": {
+                "name": "string"
+              },
+              "required": false
+            },
+            "disabled": {
+              "type": {
+                "name": "boolean"
+              },
+              "required": false
+            }
+          }
+        },
+        "MultiSelectGroup": {
+          "props": {
+            "label": {
+              "type": {
+                "name": "string"
+              },
+              "required": false
+            },
+            "items": {
+              "type": {
+                "name": "object",
+                "raw": "MultiSelectItem[]"
+              },
+              "required": false
+            }
+          }
+        }
+      },
       "examples": [
         "<MultiSelectPopover\n  items={[\n    { id: '1', label: 'Alice', image: '/alice.jpg' },\n    { id: '2', label: 'Bob' },\n  ]}\n  value={selected}\n  onValueChange={setSelected}\n>\n  <Button>Assign members</Button>\n</MultiSelectPopover>"
       ],
@@ -9875,7 +10717,7 @@
           "**Server-safe page-top header** with title + subtitle + breadcrumbs + actions slot. Renders Breadcrumb internally from the `breadcrumbs` array.",
           "**Auto-derived title:** If `title` is omitted, the last breadcrumb's `label` becomes the h1. Saves duplication when the page title matches the breadcrumb leaf.",
           "**Breadcrumb contract:** Last item should NOT have an `href` (it's the current page — renders as BreadcrumbPage, not a link). Items with `href` render as BreadcrumbLink.",
-          "**actions slot:** Typically one to three buttons (Save, Cancel, More). For larger action groups, use ButtonGroup or a toolbar.",
+          "**actions slot:** Typically one to three buttons (Save, Cancel, More). The slot wraps onto its own line under the title on narrow viewports instead of forcing horizontal overflow, so multiple/wide buttons are mobile-safe. For larger action groups, use ButtonGroup or a toolbar.",
           "**Not for tabs / sub-navigation** — pair with Tabs rendered below PageHeader for that."
         ]
       },
@@ -10001,168 +10843,159 @@
         }
       ]
     },
-    "rich-chat-input": {
-      "displayName": "RichChatInput",
+    "responsive-modal": {
+      "displayName": "ResponsiveModal",
       "tier": "composed",
-      "import": "@devalok/shilp-sutra/composed/rich-chat-input",
+      "import": "@devalok/shilp-sutra/composed/responsive-modal",
       "serverSafe": false,
-      "description": "Compact rich text chat input for unified human+AI workspaces. Built on TipTap.",
+      "description": "",
       "props": {
-        "onSubmit": {
-          "type": {
-            "name": "function",
-            "raw": "(html: string, plainText: string) => void (REQUIRED)"
-          },
-          "required": false
-        },
-        "placeholder": {
-          "type": {
-            "name": "string"
-          },
-          "required": false,
-          "defaultValue": "Type a message..."
-        },
-        "disabled": {
+        "open": {
           "type": {
             "name": "boolean"
           },
           "required": false,
-          "defaultValue": false
-        },
-        "variant": {
-          "type": {
-            "name": "enum",
-            "value": [
-              "compact",
-              "expanded",
-              "minimal"
-            ]
-          },
-          "required": false,
-          "defaultValue": "compact"
-        },
-        "maxRows": {
-          "type": {
-            "name": "number"
-          },
-          "required": false
+          "description": "controlled open state"
         },
-        "enterBehavior": {
+        "defaultOpen": {
           "type": {
-            "name": "enum",
-            "value": [
-              "send",
-              "newline"
-            ]
+            "name": "boolean"
           },
           "required": false,
-          "defaultValue": "send"
-        },
-        "maxLength": {
-          "type": {
-            "name": "object",
-            "raw": "number — enables character counter"
-          },
-          "required": false
-        },
-        "mentions": {
-          "type": {
-            "name": "object",
-            "raw": "MentionItem[] — static list for @mention autocomplete"
-          },
-          "required": false
+          "description": "uncontrolled initial state"
         },
-        "onMentionSearch": {
-          "type": {
-            "name": "function",
-            "raw": "(query: string) => Promise<MentionItem[]> — async search"
-          },
-          "required": false
-        },
-        "onMentionSelect": {
+        "onOpenChange": {
           "type": {
             "name": "function",
-            "raw": "(item: MentionItem) => void"
+            "raw": "(open: boolean) => void"
           },
           "required": false
         },
-        "onFileUpload": {
+        "dismissable": {
           "type": {
-            "name": "function",
-            "raw": "(file: File) => Promise<{ url: string; name: string; size: number }>"
+            "name": "boolean"
           },
-          "required": false
-        },
-        "onImageUpload": {
-          "type": {
-            "name": "function",
-            "raw": "(file: File) => Promise<string>"
+          "required": false,
+          "defaultValue": "true — when false, Escape / outside-click / drag cannot close; only an explicit Close or onOpenChange does"
+        }
+      },
+      "composition": {
+        "parts": [
+          {
+            "name": "ResponsiveModal",
+            "required": true,
+            "description": "root; owns open/close state and the desktop/mobile switch"
           },
-          "required": false
-        },
-        "slashCommands": {
-          "type": {
-            "name": "object",
-            "raw": "SlashCommandGroup[] — enables / command palette"
+          {
+            "name": "ResponsiveModalTrigger",
+            "description": "opens the modal; use `asChild` to wrap your own button"
           },
-          "required": false
-        },
-        "onTyping": {
-          "type": {
-            "name": "function",
-            "raw": "(isTyping: boolean) => void — typing indicator callback"
+          {
+            "name": "ResponsiveModalContent",
+            "description": "the switching panel: centered Dialog at md+, bottom sheet below"
           },
-          "required": false
-        },
-        "onEmpty": {
-          "type": {
-            "name": "function",
-            "raw": "(isEmpty: boolean) => void"
+          {
+            "name": "ResponsiveModalBackground",
+            "slot": "behind",
+            "description": "optional full-bleed layer painted at `-z-10`, clipped to the panel radius"
           },
-          "required": false
-        },
-        "isStreaming": {
-          "type": {
-            "name": "object",
-            "raw": "boolean (default: false) — shows stop button instead of send"
+          {
+            "name": "ResponsiveModalHeader",
+            "slot": "top",
+            "description": "pinned; stays put while the body scrolls"
           },
-          "required": false
-        },
-        "onCancel": {
-          "type": {
-            "name": "function",
-            "raw": "() => void — called when stop button is clicked"
+          {
+            "name": "ResponsiveModalTitle",
+            "required": true,
+            "description": "labels the dialog for accessibility"
           },
-          "required": false
-        },
-        "leadingSlot": {
-          "type": {
-            "name": "ReactNode"
+          {
+            "name": "ResponsiveModalDescription",
+            "description": "optional subtitle"
           },
-          "required": false
-        },
-        "trailingSlot": {
-          "type": {
-            "name": "ReactNode"
+          {
+            "name": "ResponsiveModalBody",
+            "description": "internal scroll region (min-h-0 flex-1 overflow-y-auto), capped 85dvh desktop / 90dvh mobile"
           },
-          "required": false
-        },
-        "disclaimer": {
-          "type": {
-            "name": "object",
-            "raw": "string — small text below the input"
+          {
+            "name": "ResponsiveModalFooter",
+            "slot": "bottom",
+            "description": "pinned action row; stacks on mobile, right-aligned inline on desktop"
           },
-          "required": false
-        },
-        "toolbar": {
-          "type": {
-            "name": "union",
-            "raw": "boolean | ChatToolbarItem[]"
+          {
+            "name": "ResponsiveModalClose",
+            "description": "manual close (Content already renders a built-in close button when dismissable)"
+          }
+        ],
+        "composesWith": [
+          {
+            "component": "dialog",
+            "relation": "alternative-to",
+            "description": "use Dialog directly when you always want a centered modal"
           },
-          "required": false,
-          "defaultValue": true
+          {
+            "component": "sheet",
+            "relation": "alternative-to",
+            "description": "use Sheet directly when you always want an edge panel"
+          }
+        ],
+        "contexts": [
+          {
+            "name": "ResponsiveModal",
+            "effect": "provides open / isMobile / dismissable / onClose to its parts via context"
+          }
+        ]
+      },
+      "docPath": "docs/components/composed/responsive-modal.md",
+      "defaults": {
+        "dismissable": true
+      },
+      "subComponents": {
+        "ResponsiveModalContent": {
+          "props": {
+            "snapPoints": {
+              "type": {
+                "name": "object",
+                "raw": "number[]"
+              },
+              "required": false,
+              "description": "mobile only; ascending viewport-height fractions like [0.4, 0.9] the sheet rests at. Omit for a content-height sheet. Ignored on desktop"
+            },
+            "defaultSnapPoint": {
+              "type": {
+                "name": "number"
+              },
+              "required": false,
+              "description": "mobile only; index into snapPoints the sheet opens at. Defaults to the last/tallest"
+            }
+          }
         }
       },
+      "examples": [
+        "<ResponsiveModal>\n  <ResponsiveModalTrigger asChild><Button>Edit profile</Button></ResponsiveModalTrigger>\n  <ResponsiveModalContent snapPoints={[0.5, 0.9]}>\n    <ResponsiveModalBackground className=\"bg-linear-to-br from-accent-3 to-accent-6 opacity-40\" />\n    <ResponsiveModalHeader>\n      <ResponsiveModalTitle>Edit profile</ResponsiveModalTitle>\n      <ResponsiveModalDescription>Changes save when you apply.</ResponsiveModalDescription>\n    </ResponsiveModalHeader>\n    <ResponsiveModalBody>{/* form fields — scrolls internally */}</ResponsiveModalBody>\n    <ResponsiveModalFooter>\n      <ResponsiveModalClose asChild><Button variant=\"soft\">Cancel</Button></ResponsiveModalClose>\n      <Button>Apply</Button>\n    </ResponsiveModalFooter>\n  </ResponsiveModalContent>\n</ResponsiveModal>"
+      ],
+      "gotchas": [
+        "Built on the same dialog primitive as Dialog and Sheet — focus trap, Escape, scroll lock, and portal are handled. Not server-safe (uses hooks); import in a client component.",
+        "Put a `ResponsiveModalTitle` inside every modal — it sets the ARIA label. Omitting it triggers an accessibility warning.",
+        "The built-in close button sits at `z-10` above `ResponsiveModalBackground` (`-z-10`); keep Header/Body/Footer in normal flow (no `relative z-*` wrapper) or a positioned wrapper will paint over the close button and eat the tap.",
+        "`snapPoints` and `defaultSnapPoint` are mobile-only — they are ignored at md+ (always a centered Dialog).",
+        "Height caps live on the panel (85dvh desktop / 90dvh mobile); do not add your own `max-h` to `ResponsiveModalBody` — it already scrolls.",
+        "Prefer this over `DialogContent responsive` when the mobile form should be a partial bottom sheet; `responsive` collapses to a full-screen takeover that leaves dead space under short content."
+      ],
+      "changes": [
+        {
+          "version": "0.49.0",
+          "summary": "Added — new component. Dialog (md+) / bottom-sheet (mobile) responsive modal with pinned header/footer, internal scroll body, optional full-bleed background slot, drag-to-dismiss, and optional mobile snap points."
+        }
+      ]
+    },
+    "rich-chat-input": {
+      "displayName": "RichChatInput",
+      "tier": "composed",
+      "import": "@devalok/shilp-sutra/composed/rich-chat-input",
+      "serverSafe": false,
+      "description": "Compact rich text chat input for unified human+AI workspaces. Built on TipTap.",
+      "props": {},
       "composition": {
         "notes": [
           "**Chat-specific TipTap editor** — purpose-built for AI + human messaging. Built on RichTextEditor primitives but pre-configured for the chat UX (auto-resize, Enter-to-send, inline toolbar).",
@@ -10175,6 +11008,166 @@
         ]
       },
       "docPath": "docs/components/composed/rich-chat-input.md",
+      "subComponents": {
+        "RichChatInputProps": {
+          "props": {
+            "onSubmit": {
+              "type": {
+                "name": "function",
+                "raw": "(html: string, plainText: string) => void (REQUIRED)"
+              },
+              "required": false
+            },
+            "placeholder": {
+              "type": {
+                "name": "string"
+              },
+              "required": false,
+              "defaultValue": "Type a message..."
+            },
+            "disabled": {
+              "type": {
+                "name": "boolean"
+              },
+              "required": false,
+              "defaultValue": false
+            },
+            "variant": {
+              "type": {
+                "name": "enum",
+                "value": [
+                  "compact",
+                  "expanded",
+                  "minimal"
+                ]
+              },
+              "required": false,
+              "defaultValue": "compact"
+            },
+            "maxRows": {
+              "type": {
+                "name": "number"
+              },
+              "required": false
+            },
+            "enterBehavior": {
+              "type": {
+                "name": "enum",
+                "value": [
+                  "send",
+                  "newline"
+                ]
+              },
+              "required": false,
+              "defaultValue": "send"
+            },
+            "maxLength": {
+              "type": {
+                "name": "object",
+                "raw": "number — enables character counter"
+              },
+              "required": false
+            },
+            "mentions": {
+              "type": {
+                "name": "object",
+                "raw": "MentionItem[] — static list for @mention autocomplete"
+              },
+              "required": false
+            },
+            "onMentionSearch": {
+              "type": {
+                "name": "function",
+                "raw": "(query: string) => Promise<MentionItem[]> — async search"
+              },
+              "required": false
+            },
+            "onMentionSelect": {
+              "type": {
+                "name": "function",
+                "raw": "(item: MentionItem) => void"
+              },
+              "required": false
+            },
+            "onFileUpload": {
+              "type": {
+                "name": "function",
+                "raw": "(file: File) => Promise<{ url: string; name: string; size: number }>"
+              },
+              "required": false
+            },
+            "onImageUpload": {
+              "type": {
+                "name": "function",
+                "raw": "(file: File) => Promise<string>"
+              },
+              "required": false
+            },
+            "slashCommands": {
+              "type": {
+                "name": "object",
+                "raw": "SlashCommandGroup[] — enables / command palette"
+              },
+              "required": false
+            },
+            "onTyping": {
+              "type": {
+                "name": "function",
+                "raw": "(isTyping: boolean) => void — typing indicator callback"
+              },
+              "required": false
+            },
+            "onEmpty": {
+              "type": {
+                "name": "function",
+                "raw": "(isEmpty: boolean) => void"
+              },
+              "required": false
+            },
+            "isStreaming": {
+              "type": {
+                "name": "object",
+                "raw": "boolean (default: false) — shows stop button instead of send"
+              },
+              "required": false
+            },
+            "onCancel": {
+              "type": {
+                "name": "function",
+                "raw": "() => void — called when stop button is clicked"
+              },
+              "required": false
+            },
+            "leadingSlot": {
+              "type": {
+                "name": "ReactNode"
+              },
+              "required": false
+            },
+            "trailingSlot": {
+              "type": {
+                "name": "ReactNode"
+              },
+              "required": false
+            },
+            "disclaimer": {
+              "type": {
+                "name": "object",
+                "raw": "string — small text below the input"
+              },
+              "required": false
+            },
+            "toolbar": {
+              "type": {
+                "name": "union",
+                "raw": "boolean | ChatToolbarItem[]"
+              },
+              "required": false,
+              "defaultValue": true
+            }
+          }
+        }
+      },
       "examples": [
         "<RichChatInput\n  onSubmit={(html, text) => sendMessage(html)}\n  mentions={teamMembers}\n  onFileUpload={uploadFile}\n  slashCommands={[{ label: 'Actions', commands: [...] }]}\n/>\n\n<RichChatInput\n  variant=\"expanded\"\n  onSubmit={handleSubmit}\n  maxLength={2000}\n  disclaimer=\"AI-generated content may be inaccurate.\"\n/>\n\n<RichChatInput\n  variant=\"minimal\"\n  enterBehavior=\"newline\"\n  onSubmit={handleReply}\n/>"
       ],
@@ -10209,7 +11202,7 @@
             "name": "string"
           },
           "required": false,
-          "description": "REQUIRED, HTML string"
+          "description": "HTML string"
         },
         "placeholder": {
           "type": {
@@ -10297,6 +11290,25 @@
         "placeholder": "Start writing...",
         "editable": true
       },
+      "subComponents": {
+        "RichTextViewer": {
+          "props": {
+            "content": {
+              "type": {
+                "name": "string"
+              },
+              "required": false,
+              "description": "REQUIRED, HTML string"
+            },
+            "className": {
+              "type": {
+                "name": "string"
+              },
+              "required": false
+            }
+          }
+        }
+      },
       "examples": [
         "<RichTextEditor content={html} onChange={setHtml} placeholder=\"Write your message...\" />\n\n<RichTextEditor\n  content={html}\n  onChange={setHtml}\n  mentions={[{ id: '1', label: 'Aarav' }]}\n  onImageUpload={async (file) => uploadAndReturnUrl(file)}\n  onFileUpload={async (file) => ({ url: uploadUrl, name: file.name, size: file.size })}\n/>\n\n<RichTextViewer content={savedHtml} />"
       ],
@@ -10412,7 +11424,7 @@
           "**Day / Week calendar view** for time-block display (meetings, shifts, availability). Not a full calendar app — no month view, no drag-to-create.",
           "**Event data is consumer-owned:** You pass `events` as an array; ScheduleView doesn't fetch, doesn't cache, doesn't expand recurring events. All scheduling logic lives in your app.",
           "**Event click + slot click** — `onEventClick` for existing events; `onSlotClick` for creating new events (fires with start/end of the empty slot).",
-          "**Color vocabulary matches the DS** — `primary/success/warning/error/info/neutral`. Map your event types to these at the data layer.",
+          "**Color vocabulary matches the DS** — `accent/success/warning/error/info/neutral`. Map your event types to these at the data layer.",
           "**endHour is exclusive:** `endHour=18` means the last visible slot starts at 17:30 (with 30min slots). Match your UX expectation: 9-5 typically means `startHour=9, endHour=18`.",
           "**Pairs with date-picker/composed** — use DatePicker or DateRangePicker to choose which date to show; pass that as ScheduleView's `date`."
         ]
@@ -10432,6 +11444,10 @@
         "Events that span outside `startHour`/`endHour` may be clipped"
       ],
       "changes": [
+        {
+          "version": "0.49.0",
+          "summary": "**BREAKING** `ScheduleEvent.color` value `\"primary\"` renamed `\"accent\"` (DS colour vocabulary). It was the default, so untyped events are unaffected."
+        },
         {
           "version": "0.1.0",
           "summary": "**Added** Initial release"
@@ -10846,28 +11862,7 @@
       "import": "@devalok/shilp-sutra/shell/command-registry",
       "serverSafe": false,
       "description": "Exports: CommandRegistryProvider, useCommandRegistry",
-      "props": {
-        "children": {
-          "type": {
-            "name": "ReactNode"
-          },
-          "required": false
-        },
-        "registry": {
-          "type": {
-            "name": "object",
-            "raw": "CommandRegistry"
-          },
-          "required": true
-        },
-        "Returns": {
-          "type": {
-            "name": "union",
-            "raw": "CommandRegistry | null"
-          },
-          "required": false
-        }
-      },
+      "props": {},
       "composition": {
         "notes": [
           "**Context provider for AppCommandPalette.** Registers page-level navigation items that the command palette surfaces as commands.",
@@ -10878,6 +11873,36 @@
         ]
       },
       "docPath": "docs/components/shell/command-registry.md",
+      "subComponents": {
+        "CommandRegistryProvider": {
+          "props": {
+            "children": {
+              "type": {
+                "name": "ReactNode"
+              },
+              "required": false
+            },
+            "registry": {
+              "type": {
+                "name": "object",
+                "raw": "CommandRegistry"
+              },
+              "required": true
+            }
+          }
+        },
+        "useCommandRegistry hook": {
+          "props": {
+            "Returns": {
+              "type": {
+                "name": "union",
+                "raw": "CommandRegistry | null"
+              },
+              "required": false
+            }
+          }
+        }
+      },
       "examples": [
         "<CommandRegistryProvider\n  registry={{\n    pages: [\n      { id: 'dashboard', label: 'Dashboard', icon: <IconHome />, path: '/dashboard' },\n      { id: 'projects', label: 'Projects', icon: <IconFolder />, path: '/projects' },\n    ],\n    adminPages: [\n      { id: 'users', label: 'Manage Users', icon: <IconUsers />, path: '/admin/users' },\n    ],\n  }}\n>\n  <App />\n</CommandRegistryProvider>"
       ],
@@ -10913,13 +11938,6 @@
             "name": "ReactNode"
           },
           "required": false
-        },
-        "Returns": {
-          "type": {
-            "name": "object",
-            "raw": "LinkComponent"
-          },
-          "required": false
         }
       },
       "composition": {
@@ -10933,6 +11951,19 @@
         ]
       },
       "docPath": "docs/components/shell/link-context.md",
+      "subComponents": {
+        "useLink hook": {
+          "props": {
+            "Returns": {
+              "type": {
+                "name": "object",
+                "raw": "LinkComponent"
+              },
+              "required": false
+            }
+          }
+        }
+      },
       "examples": [
         "import Link from 'next/link'\n\n<LinkProvider component={Link}>\n  <AppSidebar ... />\n  <BottomNavbar ... />\n</LinkProvider>"
       ],
@@ -11209,102 +12240,655 @@
             "name": "string"
           },
           "required": false
+        }
+      },
+      "composition": {
+        "notes": [
+          "**Composition-based, NOT data-driven.** Use dot-notation subcomponents (`TopBar.Left`, `TopBar.Center`, `TopBar.Right`, `TopBar.Section`, `TopBar.IconButton`, `TopBar.Title`, `TopBar.UserMenu`) to assemble. No \"props config\" — explicit JSX.",
+          "**Two-zone vs three-zone layout** — adding `TopBar.Center` flips the root from `flex` to CSS grid (`1fr auto 1fr`) for true centering. Standard apps are two-zone (Left + Right); dashboards with prominent search are three-zone.",
+          "**Required providers:** - `SidebarProvider` — for SidebarTrigger inside `TopBar.Left` to work - `LinkProvider` — for TopBar.UserMenu's menu items that use `href`",
+          "**NotificationCenter lives inside TopBar.Right** — it's a complete bell+popover component. Drop it in a TopBar.Section next to other icon buttons.",
+          "**UserMenu is composable:** `userMenuItems` inserts custom items between the built-in Profile and the color-mode toggle. Each item can navigate (href), run an action (onClick), or show a separator/badge/color decoration.",
+          "**Responsive hiding:** Actions that shouldn't appear on mobile use `className=\"hidden md:flex\"` on the IconButton — the component doesn't enforce mobile hiding; that's layout responsibility.",
+          "**Pairs with AppSidebar** — desktop app shell is typically `<TopBar>` + `<AppSidebar>` + main content region."
+        ]
+      },
+      "docPath": "docs/components/shell/top-bar.md",
+      "subComponents": {
+        "TopBar.Left": {
+          "props": {
+            "children": {
+              "type": {
+                "name": "ReactNode"
+              },
+              "required": false
+            },
+            "className": {
+              "type": {
+                "name": "string"
+              },
+              "required": false
+            }
+          }
         },
-        "gap": {
+        "TopBar.Center": {
+          "props": {
+            "children": {
+              "type": {
+                "name": "ReactNode"
+              },
+              "required": false
+            },
+            "className": {
+              "type": {
+                "name": "string"
+              },
+              "required": false
+            }
+          }
+        },
+        "TopBar.Right": {
+          "props": {
+            "children": {
+              "type": {
+                "name": "ReactNode"
+              },
+              "required": false
+            },
+            "className": {
+              "type": {
+                "name": "string"
+              },
+              "required": false
+            }
+          }
+        },
+        "TopBar.Section": {
+          "props": {
+            "gap": {
+              "type": {
+                "name": "enum",
+                "value": [
+                  "tight",
+                  "default",
+                  "loose"
+                ]
+              },
+              "required": false,
+              "defaultValue": "default"
+            },
+            "children": {
+              "type": {
+                "name": "ReactNode"
+              },
+              "required": false
+            },
+            "className": {
+              "type": {
+                "name": "string"
+              },
+              "required": false
+            }
+          }
+        },
+        "TopBar.IconButton": {
+          "props": {
+            "icon": {
+              "type": {
+                "name": "ReactNode"
+              },
+              "required": false
+            },
+            "tooltip": {
+              "type": {
+                "name": "string"
+              },
+              "required": false
+            }
+          }
+        },
+        "TopBar.Title": {
+          "props": {
+            "children": {
+              "type": {
+                "name": "ReactNode"
+              },
+              "required": false
+            },
+            "className": {
+              "type": {
+                "name": "string"
+              },
+              "required": false
+            }
+          }
+        },
+        "TopBar.UserMenu": {
+          "props": {
+            "user": {
+              "type": {
+                "name": "object",
+                "raw": "TopBarUser — { name, email?, image? }"
+              },
+              "required": false
+            },
+            "onNavigate": {
+              "type": {
+                "name": "function",
+                "raw": "(path: string) => void"
+              },
+              "required": false
+            },
+            "onLogout": {
+              "type": {
+                "name": "function",
+                "raw": "() => void"
+              },
+              "required": false
+            },
+            "userMenuItems": {
+              "type": {
+                "name": "object",
+                "raw": "UserMenuItem[]"
+              },
+              "required": false
+            },
+            "className": {
+              "type": {
+                "name": "string"
+              },
+              "required": false
+            }
+          }
+        }
+      },
+      "examples": [
+        "<TopBar>\n  <TopBar.Left>\n    <SidebarTrigger />\n    <TopBar.Title>Dashboard</TopBar.Title>\n  </TopBar.Left>\n  <TopBar.Right>\n    <TopBar.Section gap=\"tight\">\n      <TopBar.IconButton icon={<IconSearch />} tooltip=\"Search (Ctrl+K)\" onClick={openSearch} />\n      <NotificationCenter notifications={notifications} />\n      <TopBar.IconButton icon={<IconSparkles />} tooltip=\"AI Chat\" onClick={openAI} />\n    </TopBar.Section>\n    <TopBar.UserMenu\n      user={{ name: 'John', email: 'john@example.com' }}\n      onNavigate={(p) => router.push(p)}\n      onLogout={handleLogout}\n      userMenuItems={[\n        { label: 'Changelog', icon: <IconNews />, href: '/changelog', badge: '3' },\n      ]}\n    />\n  </TopBar.Right>\n</TopBar>",
+        "<TopBar>\n  <TopBar.Left>\n    <SidebarTrigger />\n    <TopBar.Title>Dashboard</TopBar.Title>\n  </TopBar.Left>\n  <TopBar.Center>\n    <SearchBarTrigger />\n  </TopBar.Center>\n  <TopBar.Right>\n    <TopBar.Section gap=\"tight\">\n      <TopBar.IconButton icon={<IconBell />} tooltip=\"Notifications\" onClick={fn} />\n    </TopBar.Section>\n    <TopBar.UserMenu user={user} onLogout={logout} />\n  </TopBar.Right>\n</TopBar>"
+      ],
+      "gotchas": [
+        "Without `TopBar.Center`, layout is flex (two-zone). With it, layout switches to CSS grid `1fr auto 1fr` for true centering.",
+        "`TopBar.IconButton` renders any number of action buttons — no artificial limit. Use responsive hiding (`className=\"hidden md:flex\"`) for mobile.",
+        "`TopBar.UserMenu` includes Profile link, color mode toggle, and logout automatically. `userMenuItems` are inserted between Profile and the toggle.",
+        "Requires SidebarProvider wrapper for SidebarTrigger to work."
+      ],
+      "changes": [
+        {
+          "version": "0.19.0",
+          "summary": "**BREAKING** Rewritten as composition API. Old props-based API removed (`pageTitle`, `onSearchClick`, `onAiChatClick`, `notificationSlot`, `mobileLogo` props)."
+        },
+        {
+          "version": "0.27.2",
+          "summary": "**Fixed** UserMenu email truncation — long emails now truncate instead of overflowing the dropdown"
+        },
+        {
+          "version": "0.7.0",
+          "summary": "**Added** `userMenuItems` prop for custom dropdown items"
+        },
+        {
+          "version": "0.1.1",
+          "summary": "**Changed** Decoupled from Next.js via LinkProvider"
+        },
+        {
+          "version": "0.1.0",
+          "summary": "**Added** Initial release"
+        }
+      ]
+    },
+    "ai-command-provider": {
+      "displayName": "AICommandProvider",
+      "tier": "ai",
+      "import": "@devalok/shilp-sutra/ai/ai-command-provider",
+      "serverSafe": false,
+      "description": "Context provider for the AI command system. Supplies custom block renderers, the action handler, and the agent identity to `AIConversation` / `BlockRenderer` below it, so you configure them once instead of threading props through every message. Ships a `useAICommand()` hook to read the context.",
+      "props": {
+        "children": {
           "type": {
-            "name": "enum",
-            "value": [
-              "tight",
-              "default",
-              "loose"
-            ]
+            "name": "ReactNode"
           },
-          "required": false,
-          "defaultValue": "default"
+          "required": true
         },
-        "icon": {
+        "customBlocks": {
           "type": {
-            "name": "ReactNode"
+            "name": "object",
+            "raw": "Record<string, ComponentType<BlockComponentProps>> — custom block-type renderers available to all descendants"
           },
           "required": false
         },
-        "tooltip": {
+        "onAction": {
           "type": {
-            "name": "string"
+            "name": "function",
+            "raw": "(actionId: string, type: \"confirm\" | \"cancel\" | \"undo\") => void — default action handler for descendant blocks"
           },
           "required": false
         },
-        "user": {
+        "agent": {
+          "type": {
+            "name": "object",
+            "raw": "{ name: string, icon?: IconInput } — default agent identity for assistant messages"
+          },
+          "required": false
+        }
+      },
+      "composition": {
+        "notes": [
+          "**Configure once** — set `customBlocks`, `onAction`, and `agent` here; `AIConversation` and `BlockRenderer` read them via context. Per-component props still win over the context (prop overrides provider).",
+          "**`useAICommand()`** — returns the context (`{ customBlocks, onAction, agent }`) or `null` when no provider is mounted. Custom blocks can use it to reach the shared action handler.",
+          "**Optional** — `AIConversation`/`BlockRenderer` work without a provider if you pass their props directly; the provider is a convenience for app-wide config."
+        ]
+      },
+      "docPath": "docs/components/ai/ai-command-provider.md",
+      "examples": [
+        "<AICommandProvider\n  agent={{ name: 'Devadoot', icon: <IconSparkles /> }}\n  customBlocks={{ chart: ChartBlock }}\n  onAction={(id, type) => handleAction(id, type)}\n>\n  <AIConversation messages={messages} />\n</AICommandProvider>\n\n// Read the context in a descendant:\nfunction MyBlock() {\n  const ctx = useAICommand() // { customBlocks, onAction, agent } | null\n  // ...\n}"
+      ],
+      "gotchas": [
+        "Client component — mount inside a client boundary.",
+        "`useAICommand()` returns `null` (not a throw) when there's no provider — guard for it in custom blocks."
+      ],
+      "changes": [
+        {
+          "version": "0.49.0",
+          "summary": "**Added** Component documentation (the AI layer is now covered by the docs gate + hosted MCP)."
+        }
+      ]
+    },
+    "block-renderer": {
+      "displayName": "BlockRenderer",
+      "tier": "ai",
+      "import": "@devalok/shilp-sutra/ai/block-renderer",
+      "serverSafe": false,
+      "description": "Renders an ordered list of typed AI \"blocks\" — the structured chunks an assistant/ server emits instead of plain text. A registry maps each block's `type` to a React component; consumers can register their own types. This doc also covers the block system and how to author a custom block.",
+      "props": {
+        "blocks": {
           "type": {
             "name": "object",
-            "raw": "TopBarUser — { name, email?, image? }"
+            "raw": "Block[] (required) — ordered blocks to render"
           },
           "required": false
         },
-        "onNavigate": {
+        "onAction": {
           "type": {
             "name": "function",
-            "raw": "(path: string) => void"
+            "raw": "(actionId: string, type: \"confirm\" | \"cancel\" | \"undo\") => void — fired by interactive blocks (e.g. confirm)"
+          },
+          "required": false
+        },
+        "customBlocks": {
+          "type": {
+            "name": "object",
+            "raw": "Record<string, ComponentType<BlockComponentProps>> — extra type→component renderers, merged OVER the built-ins"
+          },
+          "required": false,
+          "description": "prop wins over context"
+        },
+        "staggerDelay": {
+          "type": {
+            "name": "object",
+            "raw": "number — ms between each block's entrance animation"
+          },
+          "required": false,
+          "description": "default 50"
+        },
+        "className": {
+          "type": {
+            "name": "string"
+          },
+          "required": false
+        }
+      },
+      "composition": {
+        "notes": [
+          "**The block system** — the AI conversation renders assistant output as a `Block[]`. Each block has a `type` (string) and a `data` payload. `BlockRenderer` looks up the type in its registry and renders the matching component; an unknown type falls back to an `Alert` showing the raw JSON (so a new server-emitted type degrades gracefully instead of crashing).",
+          "**Built-in block types** (9): `text` (Markdown prose), `table` (tabular data), `confirm` (action confirmation — confirm/cancel buttons + a \"Why this action?\" rationale drawer), `success` / `error` / `info` (status messages), `loading` (pending indicator), `divider` (separator), `stat_row` (a row of metric cards, composes `StatCard`).",
+          "**Confidence** — every block may carry `confidence: \"high\" | \"medium\" | \"low\"`. Low-confidence blocks get a faint warning wash + a \"Low confidence\" chip (owned by the shared `BlockShell` wrapper, so the treatment is consistent across all block types). This is an AI-native affordance: the UI signals how sure the model is.",
+          "**Writing a custom block** — a block component receives `BlockComponentProps<T>` (`data`, `confidence`, `onAction`, `blockId`). Wrap your content in `BlockShell` to inherit the confidence treatment. Register it via `customBlocks` (on `BlockRenderer` or `AICommandProvider`) keyed by the `type` string your server emits.",
+          "**Two public block subpaths** — `text` and `error` import `react-markdown` + `remark-gfm` (a Markdown peer dependency). They were split out of the `ai/blocks` barrel in 0.40.0 so consumers don't pull those peers unless they render Markdown. Import them directly when needed: `@devalok/shilp-sutra/ai/blocks/text`, `@devalok/shilp-sutra/ai/blocks/error`.",
+          "**Provider merge** — `customBlocks` from `AICommandProvider` (context) are merged with the `customBlocks` prop; the prop wins on key collision. Same for `onAction`."
+        ]
+      },
+      "docPath": "docs/components/ai/block-renderer.md",
+      "examples": [
+        "// Render server-emitted blocks:\n<BlockRenderer\n  blocks={message.blocks}\n  onAction={(id, type) => handleAction(id, type)}\n/>\n\n// Register a custom block type:\nfunction ChartBlock({ data }) {\n  return <MyChart series={data.series} />\n}\n<BlockRenderer\n  blocks={message.blocks}\n  customBlocks={{ chart: ChartBlock }}\n/>"
+      ],
+      "gotchas": [
+        "Client component — mount inside a client boundary.",
+        "Requires a mounted `MotionProvider` (block entrances respect reduced-motion).",
+        "Rendering `text`/`error` blocks requires the `react-markdown` + `remark-gfm` peer dependencies — install them if your blocks include Markdown.",
+        "The `ai/blocks/*` components are an implementation detail of the registry; consume blocks via `BlockRenderer`/`AIConversation`, not by importing each block (except the two documented Markdown subpaths)."
+      ],
+      "changes": [
+        {
+          "version": "0.49.0",
+          "summary": "**Added** Component + block-system documentation (the AI layer is now covered by the docs gate + hosted MCP)."
+        }
+      ]
+    },
+    "command-bar": {
+      "displayName": "CommandBar",
+      "tier": "ai",
+      "import": "@devalok/shilp-sutra/ai/command-bar",
+      "serverSafe": false,
+      "description": "A unified AI command input with three layout variants. Supports natural-language submission (`onSubmit`) and, optionally, command-palette filtering (`groups`) in the same bar. Shows an animated brand-gradient border while processing.",
+      "props": {
+        "onSubmit": {
+          "type": {
+            "name": "function",
+            "raw": "(query: string) => void — called on Enter (natural-language submission)"
           },
           "required": false
         },
-        "onLogout": {
+        "state": {
+          "type": {
+            "name": "union",
+            "raw": "\"idle\" | \"typing\" | \"processing\" | \"responded\" — drives visual feedback"
+          },
+          "required": false,
+          "description": "gradient border, placeholder"
+        },
+        "groups": {
+          "type": {
+            "name": "object",
+            "raw": "CommandGroup[] — when provided, enables command-palette filtering alongside AI submission"
+          },
+          "required": false
+        },
+        "onSearch": {
           "type": {
             "name": "function",
-            "raw": "() => void"
+            "raw": "(query: string) => void — fired as the query changes (palette mode)"
+          },
+          "required": false
+        },
+        "emptyMessage": {
+          "type": {
+            "name": "object",
+            "raw": "string — text when a palette search yields nothing"
+          },
+          "required": false
+        },
+        "emptyState": {
+          "type": {
+            "name": "ReactNode"
+          },
+          "required": false
+        },
+        "variant": {
+          "type": {
+            "name": "union",
+            "raw": "\"hero\" | \"inline\" | \"floating\" — layout"
+          },
+          "required": false,
+          "description": "default \"hero\""
+        },
+        "placeholder": {
+          "type": {
+            "name": "union",
+            "raw": "string | string[] — static text, or an array that rotates on an interval"
           },
           "required": false
         },
-        "userMenuItems": {
+        "placeholderInterval": {
+          "type": {
+            "name": "object",
+            "raw": "number — rotation interval in ms when placeholder is an array"
+          },
+          "required": false,
+          "description": "default 4000"
+        },
+        "greeting": {
+          "type": {
+            "name": "object",
+            "raw": "string — text above the input"
+          },
+          "required": false,
+          "description": "hero variant"
+        },
+        "hints": {
           "type": {
             "name": "object",
-            "raw": "UserMenuItem[]"
+            "raw": "string[] — hint strings below the input"
+          },
+          "required": false,
+          "description": "hero variant"
+        },
+        "agentName": {
+          "type": {
+            "name": "string"
+          },
+          "required": false
+        },
+        "agentIcon": {
+          "type": {
+            "name": "ReactNode"
+          },
+          "required": false
+        },
+        "open": {
+          "type": {
+            "name": "object",
+            "raw": "boolean — controlled open state"
+          },
+          "required": false,
+          "description": "floating variant"
+        },
+        "defaultOpen": {
+          "type": {
+            "name": "object",
+            "raw": "boolean — uncontrolled initial open"
+          },
+          "required": false,
+          "description": "floating variant"
+        },
+        "onOpenChange": {
+          "type": {
+            "name": "function",
+            "raw": "(open: boolean) => void — floating variant"
+          },
+          "required": false
+        },
+        "keybinding": {
+          "type": {
+            "name": "union",
+            "raw": "string | string[] | false — global toggle for the floating bar"
+          },
+          "required": false,
+          "description": "default \"mod+j\""
+        },
+        "disabled": {
+          "type": {
+            "name": "boolean"
+          },
+          "required": false
+        },
+        "maxHeight": {
+          "type": {
+            "name": "union",
+            "raw": "string | number — cap on the results/scroll region"
+          },
+          "required": false,
+          "description": "default \"320px\""
+        },
+        "children": {
+          "type": {
+            "name": "ReactNode"
           },
           "required": false
         }
       },
       "composition": {
         "notes": [
-          "**Composition-based, NOT data-driven.** Use dot-notation subcomponents (`TopBar.Left`, `TopBar.Center`, `TopBar.Right`, `TopBar.Section`, `TopBar.IconButton`, `TopBar.Title`, `TopBar.UserMenu`) to assemble. No \"props config\" — explicit JSX.",
-          "**Two-zone vs three-zone layout** — adding `TopBar.Center` flips the root from `flex` to CSS grid (`1fr auto 1fr`) for true centering. Standard apps are two-zone (Left + Right); dashboards with prominent search are three-zone.",
-          "**Required providers:** - `SidebarProvider` — for SidebarTrigger inside `TopBar.Left` to work - `LinkProvider` — for TopBar.UserMenu's menu items that use `href`",
-          "**NotificationCenter lives inside TopBar.Right** — it's a complete bell+popover component. Drop it in a TopBar.Section next to other icon buttons.",
-          "**UserMenu is composable:** `userMenuItems` inserts custom items between the built-in Profile and the color-mode toggle. Each item can navigate (href), run an action (onClick), or show a separator/badge/color decoration.",
-          "**Responsive hiding:** Actions that shouldn't appear on mobile use `className=\"hidden md:flex\"` on the IconButton — the component doesn't enforce mobile hiding; that's layout responsibility.",
-          "**Pairs with AppSidebar** — desktop app shell is typically `<TopBar>` + `<AppSidebar>` + main content region."
+          "**Two modes in one bar** — pass `onSubmit` for natural-language AI; add `groups` to also get command-palette filtering (arrow-key navigation, grouped items). Reuses `CommandGroup`/`CommandItem` from composed/command-palette.",
+          "**`floating` reuses the Dialog primitive** (`DialogContentRaw`) with a global keybinding — same overlay pattern as CommandPalette, so focus-trap/Escape/scroll-lock come for free.",
+          "**State-driven feedback** — set `state=\"processing\"` to show the animated brand-gradient border; `\"responded\"` to settle it. Wire `state` to your agent's lifecycle.",
+          "**Placeholder rotation** — pass an array to `placeholder` for the rotating-prompt effect (paused while typing; respects reduced-motion).",
+          "**Pairs with `AIConversation`** — CommandBar is the input; AIConversation renders the response thread."
         ]
       },
-      "docPath": "docs/components/shell/top-bar.md",
+      "docPath": "docs/components/ai/command-bar.md",
       "examples": [
-        "<TopBar>\n  <TopBar.Left>\n    <SidebarTrigger />\n    <TopBar.Title>Dashboard</TopBar.Title>\n  </TopBar.Left>\n  <TopBar.Right>\n    <TopBar.Section gap=\"tight\">\n      <TopBar.IconButton icon={<IconSearch />} tooltip=\"Search (Ctrl+K)\" onClick={openSearch} />\n      <NotificationCenter notifications={notifications} />\n      <TopBar.IconButton icon={<IconSparkles />} tooltip=\"AI Chat\" onClick={openAI} />\n    </TopBar.Section>\n    <TopBar.UserMenu\n      user={{ name: 'John', email: 'john@example.com' }}\n      onNavigate={(p) => router.push(p)}\n      onLogout={handleLogout}\n      userMenuItems={[\n        { label: 'Changelog', icon: <IconNews />, href: '/changelog', badge: '3' },\n      ]}\n    />\n  </TopBar.Right>\n</TopBar>",
-        "<TopBar>\n  <TopBar.Left>\n    <SidebarTrigger />\n    <TopBar.Title>Dashboard</TopBar.Title>\n  </TopBar.Left>\n  <TopBar.Center>\n    <SearchBarTrigger />\n  </TopBar.Center>\n  <TopBar.Right>\n    <TopBar.Section gap=\"tight\">\n      <TopBar.IconButton icon={<IconBell />} tooltip=\"Notifications\" onClick={fn} />\n    </TopBar.Section>\n    <TopBar.UserMenu user={user} onLogout={logout} />\n  </TopBar.Right>\n</TopBar>"
+        "// Hero variant — the primary AI entry point on a dashboard:\n<CommandBar\n  variant=\"hero\"\n  greeting=\"What can I help with?\"\n  placeholder={['Summarize this project…', 'Draft a status update…', 'Find overdue tasks…']}\n  hints={['⌘J to open anywhere', 'Ask in plain English']}\n  state={aiState}\n  onSubmit={(q) => runAgent(q)}\n/>\n\n// Floating variant — global ⌘J overlay, palette + AI in one:\n<CommandBar\n  variant=\"floating\"\n  keybinding=\"mod+j\"\n  groups={commandGroups}\n  onSearch={setQuery}\n  onSubmit={(q) => runAgent(q)}\n/>"
       ],
       "gotchas": [
-        "Without `TopBar.Center`, layout is flex (two-zone). With it, layout switches to CSS grid `1fr auto 1fr` for true centering.",
-        "`TopBar.IconButton` renders any number of action buttons — no artificial limit. Use responsive hiding (`className=\"hidden md:flex\"`) for mobile.",
-        "`TopBar.UserMenu` includes Profile link, color mode toggle, and logout automatically. `userMenuItems` are inserted between Profile and the toggle.",
-        "Requires SidebarProvider wrapper for SidebarTrigger to work."
+        "Client component — mount inside a client boundary.",
+        "Requires a mounted `MotionProvider`.",
+        "`keybinding` only applies to the `floating` variant; pass `false` to disable the global shortcut.",
+        "Largest component in the AI layer (3 variants share one implementation) — prefer `inline`/`hero` for embedded bars, `floating` for the app-wide launcher."
       ],
       "changes": [
         {
-          "version": "0.19.0",
-          "summary": "**BREAKING** Rewritten as composition API. Old props-based API removed (`pageTitle`, `onSearchClick`, `onAiChatClick`, `notificationSlot`, `mobileLogo` props)."
+          "version": "0.49.0",
+          "summary": "**Added** Component documentation (the AI layer is now covered by the docs gate + hosted MCP)."
+        }
+      ]
+    },
+    "conversation": {
+      "displayName": "AIConversation",
+      "tier": "ai",
+      "import": "@devalok/shilp-sutra/ai/conversation",
+      "serverSafe": false,
+      "description": "A scrollable AI conversation thread: user + assistant turns, streaming processing steps, an agent header, and structured content blocks (rendered via BlockRenderer) with confirm/cancel/undo action support.",
+      "props": {
+        "messages": {
+          "type": {
+            "name": "object",
+            "raw": "ConversationMessage[] (required) — ordered user + assistant turns"
+          },
+          "required": false
         },
-        {
-          "version": "0.27.2",
-          "summary": "**Fixed** UserMenu email truncation — long emails now truncate instead of overflowing the dropdown"
+        "isProcessing": {
+          "type": {
+            "name": "object",
+            "raw": "boolean — shows a live processing indicator below the last message"
+          },
+          "required": false
         },
-        {
-          "version": "0.7.0",
-          "summary": "**Added** `userMenuItems` prop for custom dropdown items"
+        "processingSteps": {
+          "type": {
+            "name": "object",
+            "raw": "ProcessingStep[] — granular steps shown during processing"
+          },
+          "required": false,
+          "description": "status: pending | active | done | error"
+        },
+        "agent": {
+          "type": {
+            "name": "object",
+            "raw": "{ name: string, icon?: IconInput } — agent identity shown as a header on assistant messages"
+          },
+          "required": false
         },
+        "onAction": {
+          "type": {
+            "name": "function",
+            "raw": "(actionId: string, type: \"confirm\" | \"cancel\" | \"undo\") => void — fired by action blocks"
+          },
+          "required": false
+        },
+        "customBlocks": {
+          "type": {
+            "name": "object",
+            "raw": "Record<string, ComponentType<BlockComponentProps>> — extra block-type renderers merged over the built-ins"
+          },
+          "required": false
+        },
+        "maxHeight": {
+          "type": {
+            "name": "union",
+            "raw": "string | number — max height of the container"
+          },
+          "required": false,
+          "description": "enables scrolling"
+        },
+        "autoScroll": {
+          "type": {
+            "name": "object",
+            "raw": "boolean — auto-scroll to bottom on new messages"
+          },
+          "required": false,
+          "description": "default true"
+        },
+        "className": {
+          "type": {
+            "name": "string"
+          },
+          "required": false
+        }
+      },
+      "composition": {
+        "notes": [
+          "**Renders blocks, not raw text** — each assistant turn is a list of typed `Block`s rendered by `BlockRenderer`. See the block-renderer doc for the block system and how to register custom block types.",
+          "**Pairs with `AICommandProvider`** — the provider supplies `customBlocks`, `onAction`, and `agent` via context so you don't thread them through every message. Props on `AIConversation` win over context.",
+          "**Pairs with `CommandBar`** — CommandBar is the input surface (natural-language submission); AIConversation is the output thread. Common layout: CommandBar on top/bottom, AIConversation as the scroll region.",
+          "**Streaming** — set `isProcessing` + feed `processingSteps` to show step-by-step progress (Reading → Drafting → …) while the model works.",
+          "**Actions** — action blocks (e.g. `confirm`) call `onAction(actionId, type)`; wire it to your confirm/cancel/undo handlers."
+        ]
+      },
+      "docPath": "docs/components/ai/conversation.md",
+      "examples": [
+        "<AICommandProvider agent={{ name: 'Devadoot' }} onAction={handleAction}>\n  <AIConversation\n    messages={messages}\n    isProcessing={isThinking}\n    processingSteps={[\n      { label: 'Reading project', status: 'done' },\n      { label: 'Drafting reply', status: 'active' },\n    ]}\n    agent={{ name: 'Devadoot', icon: <IconSparkles /> }}\n    onAction={(id, type) => handleAction(id, type)}\n    maxHeight=\"60vh\"\n  />\n</AICommandProvider>"
+      ],
+      "gotchas": [
+        "Client component — mount inside a client boundary.",
+        "Requires a mounted `MotionProvider` (respects reduced-motion for the step spinner and block entrances).",
+        "`agent` set here labels assistant messages; `AICommandProvider`'s `agent` is the fallback when not passed per-conversation."
+      ],
+      "changes": [
         {
-          "version": "0.1.1",
-          "summary": "**Changed** Decoupled from Next.js via LinkProvider"
+          "version": "0.49.0",
+          "summary": "**Added** Component documentation (the AI layer is now covered by the docs gate + hosted MCP)."
+        }
+      ]
+    },
+    "devadoot-icon": {
+      "displayName": "DevadootIcon",
+      "tier": "ai",
+      "import": "@devalok/shilp-sutra/ai",
+      "serverSafe": false,
+      "description": "The animated Devalok chakra glyph — the visual identity for the AI command system. Uses fill-first animation (the gradient color *is* the animation, Gemini-style), with a distinct state for idle, processing, responded, and error.",
+      "props": {
+        "state": {
+          "type": {
+            "name": "union",
+            "raw": "\"idle\" | \"processing\" | \"responded\" | \"error\" — animation mode"
+          },
+          "required": false,
+          "description": "default \"idle\""
         },
+        "size": {
+          "type": {
+            "name": "object",
+            "raw": "number — pixel size"
+          },
+          "required": false,
+          "description": "default 20"
+        },
+        "className": {
+          "type": {
+            "name": "string"
+          },
+          "required": false
+        }
+      },
+      "composition": {
+        "notes": [
+          "**State-as-identity** — `idle` breathes pink↔rose slowly; `processing` sweeps a pink→purple→magenta gradient + glow; `responded` flashes bright then settles + a scale pop; `error` turns red with a glow pulse. Wire `state` to your agent's status.",
+          "**Pairs with `CommandBar` / `AIConversation`** — commonly placed in the CommandBar (hero/floating) or as the agent header avatar in the conversation.",
+          "**Exported from the `ai` barrel** — `import { DevadootIcon } from '@devalok/shilp-sutra/ai'` (no dedicated subpath)."
+        ]
+      },
+      "docPath": "docs/components/ai/devadoot-icon.md",
+      "examples": [
+        "// Drive the icon from the agent lifecycle:\n<DevadootIcon state={isThinking ? 'processing' : hasReplied ? 'responded' : 'idle'} size={24} />\n\n// Error state:\n<DevadootIcon state=\"error\" />"
+      ],
+      "gotchas": [
+        "Client component — mount inside a client boundary.",
+        "Requires a mounted `MotionProvider`; renders a static chakra when reduced-motion is set.",
+        "Brand-locked colors (Devalok pink↔purple palette) — it's a brand asset, not a generic spinner. Use `Spinner` for neutral loading."
+      ],
+      "changes": [
         {
-          "version": "0.1.0",
-          "summary": "**Added** Initial release"
+          "version": "0.49.0",
+          "summary": "**Added** Component documentation (the AI layer is now covered by the docs gate + hosted MCP)."
         }
       ]
     }
@@ -11503,6 +13087,10 @@
         "name": "--color-surface-raised-active",
         "value": "Canvas"
       },
+      {
+        "name": "--color-surface-chrome",
+        "value": "Canvas"
+      },
       {
         "name": "--color-surface-inverted",
         "value": "CanvasText"