@devalok/shilp-sutra 0.51.0 → 0.53.0

package/mcp-manifest.json

@@ -2,7 +2,7 @@
   "$schema": "./mcp-manifest.schema.json",
   "manifestVersion": "1.2.0",
   "package": "@devalok/shilp-sutra",
-  "packageVersion": "0.51.0",
+  "packageVersion": "0.53.0",
   "components": {
     "accordion": {
       "displayName": "Accordion",
@@ -386,7 +386,16 @@
             "name": "union",
             "raw": "AutocompleteOption | null"
           },
-          "required": false
+          "required": false,
+          "description": "controlled"
+        },
+        "defaultValue": {
+          "type": {
+            "name": "union",
+            "raw": "AutocompleteOption | null"
+          },
+          "required": false,
+          "description": "uncontrolled initial"
         },
         "onValueChange": {
           "type": {
@@ -414,6 +423,46 @@
           },
           "required": false
         },
+        "size": {
+          "type": {
+            "name": "object",
+            "raw": "(forwarded to Input)"
+          },
+          "required": false
+        },
+        "state": {
+          "type": {
+            "name": "enum",
+            "value": [
+              "default",
+              "error",
+              "warning",
+              "success"
+            ]
+          },
+          "required": false,
+          "description": "forwarded to Input"
+        },
+        "isLoading": {
+          "type": {
+            "name": "boolean"
+          },
+          "required": false
+        },
+        "loadingText": {
+          "type": {
+            "name": "string"
+          },
+          "required": false,
+          "defaultValue": "Loading…"
+        },
+        "renderOption": {
+          "type": {
+            "name": "function",
+            "raw": "(option, query) => ReactNode"
+          },
+          "required": false
+        },
         "className": {
           "type": {
             "name": "string"
@@ -429,25 +478,34 @@
       },
       "composition": {
         "notes": [
-          "**Autocomplete vs Combobox:** Autocomplete allows free-text input (users can type anything); Combobox enforces selection from the list. Pick by whether \"off-list\" values are valid (e.g. city field that accepts typos → Autocomplete; tag picker from a fixed vocabulary → Combobox).",
-          "**Value shape is an object** (`{ value, label }`), not a plain string — this preserves label/value decoupling for display-vs-storage.",
-          "**FormField:** Does NOT auto-consume FormField state. Set explicit error styling via className if needed.",
+          "**Composes `Input`** — the field is the DS `Input`, so it inherits `size`, error/`state` painting, read-only, hover, and FormField wiring. Autocomplete owns only the dropdown + behavior.",
+          "**Autocomplete vs Combobox:** Autocomplete allows free-text input (users can type anything); Combobox enforces selection from the list.",
+          "**Value shape is an object** (`{ value, label }`), not a plain string. Controlled via `value`, or uncontrolled via `defaultValue`.",
+          "**FormField:** auto-consumes FormField state (via the composed Input) — inside a FormField, error border + `aria-invalid`/`aria-describedby`/`required` are wired automatically. Pass `state` to override.",
+          "**Async / \"type to search\":** set `isLoading` to show a spinner (in the field + the listbox) with `loadingText`.",
+          "**Matched-text highlight:** the query substring is bolded in each option by default; override the whole row with `renderOption`.",
           "**Portal rendering:** Dropdown portals to body with z-popover (1400) — stacks above Dialog/Sheet.",
-          "**Keyboard:** ArrowDown/Up navigate suggestions, Enter selects, Esc closes. Typeahead is the input's native filtering."
+          "**Keyboard:** ArrowDown/Up/Home/End navigate, Enter selects, Esc closes."
         ]
       },
       "docPath": "docs/components/ui/autocomplete.md",
       "defaults": {
-        "emptyText": "No options"
+        "emptyText": "No options",
+        "loadingText": "Loading…"
       },
       "examples": [
         "<Autocomplete\n  options={[{ value: 'mumbai', label: 'Mumbai' }]}\n  value={selectedCity}\n  onValueChange={setSelectedCity}\n  placeholder=\"Search cities...\"\n/>"
       ],
       "gotchas": [
         "Allows free-text input (no forced selection) — use Combobox for forced selection",
-        "value is an object { value, label }, NOT just a string"
+        "value is an object { value, label }, NOT just a string",
+        "Client-side filtering only (known list). For huge/remote lists, drive `options` yourself with `isLoading` — no built-in virtualization."
       ],
       "changes": [
+        {
+          "version": "0.53.0",
+          "summary": "**Changed** Re-parented onto the DS `Input` primitive — inherits `size`, error/`state` painting, read-only, hover, and FormField auto-consumption (previously re-rolled its own `<input>` and read FormField error but never painted it)."
+        },
         {
           "version": "0.18.0",
           "summary": "**Fixed** Added `useEffect` to sync query when external value changes"
@@ -1192,6 +1250,7 @@
               "error",
               "success",
               "warning",
+              "info",
               "neutral"
             ]
           },
@@ -1302,6 +1361,7 @@
               "error",
               "success",
               "warning",
+              "info",
               "neutral"
             ]
           },
@@ -5250,7 +5310,7 @@
           "type": {
             "name": "enum",
             "value": [
-              "default",
+              "soft",
               "solid"
             ]
           },
@@ -5263,16 +5323,24 @@
           },
           "required": true
         },
-        "selectedId": {
+        "value": {
           "type": {
-            "name": "string"
+            "name": "object",
+            "raw": "string                          // controlled"
           },
-          "required": true
+          "required": false
         },
-        "onSelect": {
+        "defaultValue": {
+          "type": {
+            "name": "object",
+            "raw": "string                   // uncontrolled initial"
+          },
+          "required": false
+        },
+        "onValueChange": {
           "type": {
             "name": "function",
-            "raw": "(id: string) => void (REQUIRED)"
+            "raw": "(id: string) => void"
           },
           "required": false
         },
@@ -5281,6 +5349,26 @@
             "name": "boolean"
           },
           "required": false
+        },
+        "fullWidth": {
+          "type": {
+            "name": "boolean"
+          },
+          "required": false
+        },
+        "selectedId": {
+          "type": {
+            "name": "object",
+            "raw": "string                     // @deprecated — use value"
+          },
+          "required": false
+        },
+        "onSelect": {
+          "type": {
+            "name": "function",
+            "raw": "(id: string) => void         // @deprecated — use onValueChange"
+          },
+          "required": false
         }
       },
       "composition": {
@@ -5288,20 +5376,29 @@
           "**Data-driven, not compound** — unlike Tabs/ToggleGroup, SegmentedControl takes an `options` array rather than children. This makes it easier to render from a list but harder to customize per-option styling; use Tabs if you need compound children.",
           "**When to use vs Tabs:** SegmentedControl is for mutually-exclusive VIEW-MODE toggles (List/Grid/Kanban) — short labels, no associated content panel. Tabs is for content switching where each tab has a corresponding TabsContent. SegmentedControl renders `role=\"radiogroup\"` with `role=\"radio\"` segments (a panel-less single-select); Tabs renders `role=\"tablist\"`.",
           "**Option icons** auto-size based on the `size` prop — don't set explicit icon sizes.",
-          "Fully controlled — there's no `defaultSelectedId`. Manage state in parent.",
+          "**`fullWidth`** switches segments from content-hug (default) to equal-fill: each segment takes an equal share of the container (a 2-item toggle splits 50/50, a 3-item switcher gives each a third). Use for view switchers and toolbar toggles that should fill their column; leave off for compact inline toolbars.",
+          "**Visual model:** a rounded-rect track (not a full pill) — a translucent recessed groove with a single soft-shadowed sliding thumb. The track has no border/inset shadow; the thumb carries the only edge. Elevation inverts in dark so the groove stays visible.",
+          "**Controlled or uncontrolled** — pass `value` + `onValueChange` to control it, or `defaultValue` (optional; falls back to the first option) to let it own state. Matches the Tabs/ToggleGroup vocabulary. `selectedId`/`onSelect` are deprecated aliases that still work.",
+          "**Option labels accept `ReactNode`** — a segment can hold a count badge or custom node, not just a string. `text` is optional: omit it for an **icon-only** segment and set `ariaLabel` so the segment still has an accessible name.",
+          "**Touch targets** — each segment has a 44px minimum hit area (via `touch-target`) even though the visual height stays dense.",
+          "**RTL** — Arrow-key navigation tracks reading order: in a right-to-left context `ArrowLeft` moves to the next option and `ArrowRight` to the previous (detected from the nearest `dir` attribute).",
           "Built from scratch (no Radix primitive) — standard HTML buttons with `role=\"radio\"` + `aria-checked` and roving tabindex."
         ]
       },
       "docPath": "docs/components/ui/segmented-control.md",
       "examples": [
-        "<SegmentedControl\n  size=\"md\"\n  variant=\"default\"\n  options={[\n    { id: 'list', text: 'List' },\n    { id: 'grid', text: 'Grid' },\n  ]}\n  selectedId={viewMode}\n  onSelect={setViewMode}\n/>"
+        "<SegmentedControl\n  size=\"md\"\n  variant=\"soft\"\n  options={[\n    { id: 'list', text: 'List' },\n    { id: 'grid', text: 'Grid' },\n  ]}\n  value={viewMode}\n  onValueChange={setViewMode}\n/>"
       ],
       "gotchas": [
-        "Controlled only — selectedId + onSelect are required",
+        "Controlled (`value`) or uncontrolled (`defaultValue`) — `selectedId`/`onSelect` are deprecated aliases",
         "Uses data-driven API (options prop), not compound children",
         "Use Tabs (not SegmentedControl) when you need associated content panels per option"
       ],
       "changes": [
+        {
+          "version": "0.52.0",
+          "summary": "**Changed** Visual rebuild — rounded-rect track (was full pill), translucent recessed track with no border/inset, single ring-less soft-shadow thumb. Dark-mode elevation inverts so the groove stays visible. New tokens: `--color-segment-track`, `--color-segment-thumb`, `--shadow-segment`."
+        },
         {
           "version": "0.38.0",
           "summary": "**Removed** (BREAKING) deprecated `variant=\"accent\"` alias. Use `variant=\"solid\"`."
@@ -10929,7 +11026,7 @@
       "displayName": "PriorityIndicator",
       "tier": "composed",
       "import": "@devalok/shilp-sutra/composed/priority-indicator",
-      "serverSafe": true,
+      "serverSafe": false,
       "description": "",
       "props": {
         "priority": {
@@ -10939,6 +11036,13 @@
           },
           "required": false
         },
+        "iconOnly": {
+          "type": {
+            "name": "boolean"
+          },
+          "required": false,
+          "description": "icon-only chip, no visible text"
+        },
         "display": {
           "type": {
             "name": "enum",
@@ -10948,31 +11052,41 @@
             ]
           },
           "required": false,
-          "defaultValue": "full"
+          "description": "@deprecated — use iconOnly"
+        },
+        "children": {
+          "type": {
+            "name": "ReactNode"
+          },
+          "required": false,
+          "description": "override the label, e.g. i18n"
         }
       },
       "composition": {
         "notes": [
-          "**Server-safe priority label** — icon + color + text for task / issue priority.",
+          "**Composes `Badge`** — radius, color semantics, a11y labelling, and reduced-motion handling all come from one place (no bespoke re-roll).",
           "**Composes inside list rows, DataTable cells, Card headers, task panels** — anywhere a priority flag fits.",
-          "**display=\"compact\"** shows only the icon (with priority text as title attribute for tooltip). Use in tight cells; use `display=\"full\"` (default) in free space.",
-          "**Case-insensitive priority** — accepts both UPPERCASE (LOW/MEDIUM/HIGH/URGENT) and lowercase. Designed to match both backend conventions without manual coercion.",
-          "Color semantics: LOW=success, MEDIUM=warning, HIGH=error, URGENT=error with bolder icon."
+          "**`iconOnly`** shows only the icon with a real accessible name (`role=\"img\"` + `aria-label`), for tight cells. Omit it (default) for icon + label.",
+          "**Severity by weight, not motion** — URGENT renders as a solid fill so the top tier reads at a glance; the others are soft. No animation (removes the prior perpetual pulse).",
+          "**Case-insensitive priority** — accepts both UPPERCASE and lowercase; unknown values fall back to MEDIUM instead of throwing.",
+          "**`children`** overrides the label for i18n / custom copy.",
+          "Color semantics: LOW = slate (neutral), MEDIUM = warning, HIGH = error (soft), URGENT = error (solid)."
         ]
       },
       "docPath": "docs/components/composed/priority-indicator.md",
-      "defaults": {
-        "display": "full"
-      },
       "examples": [
-        "<PriorityIndicator priority=\"HIGH\" />\n<PriorityIndicator priority=\"low\" display=\"compact\" />"
+        "<PriorityIndicator priority=\"HIGH\" />\n<PriorityIndicator priority=\"low\" iconOnly />\n<PriorityIndicator priority=\"URGENT\">Critical</PriorityIndicator>"
       ],
       "gotchas": [
-        "Case-insensitive — \"low\" and \"LOW\" both work",
-        "Server-safe: can be imported directly in Next.js Server Components",
-        "`compact` display shows only the icon; `full` shows icon + text label"
+        "Case-insensitive — \"low\" and \"LOW\" both work; unknown values fall back to MEDIUM",
+        "`iconOnly` shows only the icon (accessible-named); default shows icon + text label",
+        "`display` is deprecated — use `iconOnly`"
       ],
       "changes": [
+        {
+          "version": "0.53.0",
+          "summary": "**Changed** Recomposed on the `Badge` primitive (was a bespoke re-rolled chip): inherits pill radius, color semantics, accessible labelling."
+        },
         {
           "version": "0.2.0",
           "summary": "**Added** Identified as server-safe component"
@@ -11557,13 +11671,55 @@
           "required": false,
           "description": "minutes, default: 30",
           "defaultValue": 30
+        },
+        "selectedEventId": {
+          "type": {
+            "name": "string"
+          },
+          "required": false,
+          "description": "rings the active event"
+        },
+        "renderEvent": {
+          "type": {
+            "name": "function",
+            "raw": "(event) => ReactNode (custom event body)"
+          },
+          "required": false
+        },
+        "header": {
+          "type": {
+            "name": "ReactNode"
+          },
+          "required": false,
+          "description": "toolbar slot above the grid"
+        },
+        "emptyState": {
+          "type": {
+            "name": "ReactNode"
+          },
+          "required": false,
+          "description": "shown when events is empty"
+        },
+        "height": {
+          "type": {
+            "name": "union",
+            "raw": "number | string"
+          },
+          "required": false,
+          "description": "grid body height, default 480",
+          "defaultValue": 480
         }
       },
       "composition": {
         "notes": [
           "**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).",
+          "**Event click + slot click** — `onEventClick` for existing events; `onSlotClick` for creating new events (fires with start/end of the empty slot). **Slots are only interactive (focusable + keyboard-navigable) when `onSlotClick` is set** — otherwise they render as inert grid lines, so a read-only schedule adds no keyboard/AT tab stops.",
+          "**Keyboard (interactive slots):** roving tabindex — Arrow keys move between slots (up/down within a day, left/right across days, RTL-aware), Home/End jump within the day; only one slot is in the tab order at a time.",
+          "**Overlapping events** are partitioned into side-by-side columns automatically so double-booked times stay legible.",
+          "**Live now-line** ticks every minute and scrolls into view on mount.",
+          "**`renderEvent`** customizes the event block body; **`header`** adds a toolbar; **`selectedEventId`** rings the active event; **`emptyState`** shows when there are no events.",
+          "**Composes the DS card shell tokens** (`surface-2` + `rounded-surface` + border) and is RTL-safe (logical properties throughout).",
           "**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`."
@@ -11573,7 +11729,8 @@
       "defaults": {
         "startHour": 8,
         "endHour": 18,
-        "slotDuration": 30
+        "slotDuration": 30,
+        "height": 480
       },
       "examples": [
         "<ScheduleView\n  view=\"week\"\n  date={new Date()}\n  events={calendarEvents}\n  onEventClick={(e) => openEvent(e.id)}\n/>"
@@ -11584,6 +11741,10 @@
         "Events that span outside `startHour`/`endHour` may be clipped"
       ],
       "changes": [
+        {
+          "version": "0.53.0",
+          "summary": "**Changed** Read-only schedules no longer flood the tab order — slots are interactive only when `onSlotClick` is set; otherwise inert grid lines. Interactive slots use roving tabindex + Arrow/Home/End keyboard navigation (RTL-aware)."
+        },
         {
           "version": "0.49.0",
           "summary": "**BREAKING** `ScheduleEvent.color` value `\"primary\"` renamed `\"accent\"` (DS colour vocabulary). It was the default, so untyped events are unaffected."
@@ -11928,7 +12089,7 @@
             "raw": "BottomNavbarUser | null"
           },
           "required": false,
-          "description": "optional"
+          "description": "drives per-item role gating, optional"
         },
         "primaryItems": {
           "type": {
@@ -11944,7 +12105,30 @@
             "raw": "BottomNavItem[]"
           },
           "required": false,
-          "description": "overflow items in \"More\" menu, optional"
+          "description": "overflow items in \"More\" sheet, optional"
+        },
+        "indicator": {
+          "type": {
+            "name": "enum",
+            "value": [
+              "pill",
+              "underline",
+              "tint",
+              "none"
+            ]
+          },
+          "required": false,
+          "description": "active-item indicator; default 'pill'"
+        },
+        "labelVisibility": {
+          "type": {
+            "name": "enum",
+            "value": [
+              "always",
+              "selected"
+            ]
+          },
+          "required": false
         },
         "className": {
           "type": {
@@ -11959,7 +12143,11 @@
           "**Responsive switch pattern:** Use `useIsMobile()` hook to conditionally render AppSidebar (desktop) or BottomNavbar (mobile). Example: ```jsx const isMobile = useIsMobile() return isMobile ? <BottomNavbar ... /> : <AppSidebar ... /> ```",
           "**Primary vs overflow:** `primaryItems` (max 4) for the always-visible slots; `moreItems` go into a \"More\" sheet that opens on tap. Don't exceed 4 primary — the bar becomes cramped.",
           "**Router integration via LinkProvider:** Each nav item is rendered using the framework-specific Link component registered in LinkProvider. Without LinkProvider, you get full-page reloads on tap.",
-          "**Badge numbers** cap at 99+ (same as BadgeIndicator pattern).",
+          "**Badge numbers** cap at 99+ (composes the `Badge` primitive).",
+          "**Role gating:** each item may declare `roles: string[]` (shown only when `user.role` matches) or a `canView(user)` predicate for arbitrary logic (`canView` wins). Items with neither are always visible. Gating applies to both `primaryItems` and `moreItems`.",
+          "**Overflow sheet:** the \"More\" surface is the DS `Sheet` (`side=\"bottom\"`) — it inherits focus trap, scroll lock, return-focus, and `aria-modal`; the trigger is wired with `aria-haspopup`/`aria-controls` automatically.",
+          "**Indicator (animated):** the active indicator slides to the selected item (shared-element `layoutId`) and fades in on first appearance. Modes: `pill` (default, Material-3 tonal pill behind the icon), `underline` (top accent bar), `tint` (subtle bg on the whole active cell), `none` (no shape — pair with `activeIcon` for the iOS filled-icon look). `labelVisibility=\"selected\"` shows labels only for the active item.",
+          "**Filled-when-active:** set `activeIcon` on an item (e.g. a Tabler `*Filled` variant) to swap the icon for a filled version while it's the active route; falls back to `icon`.",
           "**Not for desktop:** The viewport-fixed positioning + touch-optimized sizing don't translate well to desktop. Hide behind `md:hidden`."
         ]
       },
@@ -11974,6 +12162,10 @@
         "Requires LinkProvider for framework-specific link components (e.g., Next.js Link)"
       ],
       "changes": [
+        {
+          "version": "0.53.0",
+          "summary": "**Changed** Overflow \"More\" menu re-founded on the DS `Sheet` primitive — inherits focus trap, scroll lock, return-focus, `aria-modal`, and trigger↔panel ARIA wiring (was a hand-rolled `role=\"dialog\"` with none of these). Composes `Badge` for notification counts and the Sheet's built-in close (≥ touch target)."
+        },
         {
           "version": "0.19.0",
           "summary": "**Changed** Background elevated from `bg-surface-1` to `bg-surface-2` for visual hierarchy above app background"
@@ -13279,6 +13471,14 @@
         "name": "--color-backdrop",
         "value": "Canvas"
       },
+      {
+        "name": "--color-segment-track",
+        "value": "color-mix(in oklch, oklch(1 0 0) 7%, transparent)"
+      },
+      {
+        "name": "--color-segment-thumb",
+        "value": "var(--neutral-3)"
+      },
       {
         "name": "--color-overlay",
         "value": "Canvas"
@@ -13933,6 +14133,10 @@
         "name": "--shadow-raised-hover",
         "value": "var(--shadow-sm-internal)"
       },
+      {
+        "name": "--shadow-segment",
+        "value": "0 1px 2px -0.5px oklch(var(--shadow-color) / calc(0.10 * var(--shadow-strength))), 0 3px 8px -2px oklch(var(--shadow-color) / calc(0.09 * var(--shadow-strength)))"
+      },
       {
         "name": "--shadow-floating",
         "value": "var(--shadow-md-internal)"

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@devalok/shilp-sutra",
-  "version": "0.51.0",
+  "version": "0.53.0",
   "description": "Devalok Design System — accessible React components, OKLCH design tokens, and Tailwind 4 CSS-first setup. Ships with AI-agent setup recipes.",
   "license": "MIT",
   "author": "Devalok Design & Strategy Studios <shilp-sutra@devalok.in>",

package/scripts/welcome.mjs

@@ -183,7 +183,7 @@ function buildFullBanner(version, prevVersion) {
   lines.push(row(`     ${colour('https://shilp-sutra.devalok.in/themer', DIM)}`))
   lines.push(colour(EMPTY, PINK_DIM))
   lines.push(row(`   ${colour('▸', PINK)} Wire your AI agent (Claude Code / Cursor / Codex):`))
-  lines.push(row(`     ${colour('connect the live docs MCP → https://shilp-sutra.devalok.in/mcp', DIM)}`))
+  lines.push(row(`     ${colour('live docs MCP added to .mcp.json — approve it to enable', DIM)}`))
   lines.push(row(`     ${colour('(version-exact setup + peer preflight; beats guessing)', DIM)}`))
   lines.push(row(`     ${colour('or copy the skill: cp -r node_modules/@devalok/shilp-sutra/skill \\', DIM)}`))
   lines.push(row(`        ${colour('~/.claude/skills/shilp-sutra', DIM)}`))
@@ -215,6 +215,59 @@ function buildCompactBanner(version, prevVersion) {
   ].join('\n')
 }
 
+// ── MCP auto-discovery ───────────────────────────────────────────────────────
+// Write a project-scoped `.mcp.json` pointing at the hosted docs MCP so an AI
+// coding agent DISCOVERS it right after install. This runs even when stdout is
+// piped (unlike the banner) — a config file is not console noise, and the agent
+// that just ran `install` is exactly who should find it. It is never silent-
+// forced: Claude Code (and peers) still PROMPT the user to approve a project
+// MCP server before enabling it. Safety: additive merge (never clobbers other
+// servers or an existing shilp-sutra entry), skips CI and dev installs, honours
+// opt-out, and a write-once sentinel so a user who deletes it is not re-nagged.
+const SEP = process.platform === 'win32' ? '\\' : '/'
+const MCP_URL = 'https://shilp-sutra.devalok.in/mcp'
+
+function tryWriteMcpConfig() {
+  try {
+    if (process.env.SHILP_SUTRA_NO_WELCOME === '1' || process.env.SHILP_SUTRA_NO_WELCOME === 'true') return
+    if (process.env.SHILP_SUTRA_NO_MCP === '1' || process.env.SHILP_SUTRA_NO_MCP === 'true') return
+    if (process.env.CI) return // writing agent config into a CI checkout is pointless/unwanted
+
+    const initCwd = process.env.INIT_CWD
+    const cwd = process.cwd()
+    const isInsideNodeModules = cwd.includes(`${SEP}node_modules${SEP}`) || cwd.includes('/node_modules/')
+    if (!isInsideNodeModules) return // dev install inside the DS repo itself
+    if (!initCwd || initCwd === cwd) return // no consumer root → unusual context
+
+    // Write-once-ever sentinel (survives re-installs; respects user deletion of .mcp.json)
+    const parts = PKG_DIR.split(/[/\\]/)
+    const nmIdx = parts.lastIndexOf('node_modules')
+    const sentinel = nmIdx === -1 ? null : join(parts.slice(0, nmIdx + 1).join(SEP), '.shilp-sutra-mcp-written')
+    if (sentinel && existsSync(sentinel)) return
+
+    const target = join(initCwd, '.mcp.json')
+    let config = { mcpServers: {} }
+    if (existsSync(target)) {
+      try {
+        config = JSON.parse(readFileSync(target, 'utf-8'))
+      } catch {
+        return // existing but unparseable — never clobber a hand-authored config
+      }
+      if (!config || typeof config !== 'object') return
+      if (!config.mcpServers || typeof config.mcpServers !== 'object') config.mcpServers = {}
+      if (config.mcpServers['shilp-sutra']) {
+        if (sentinel) writeFileSync(sentinel, MCP_URL + '\n')
+        return // already declared — leave the consumer's version untouched
+      }
+    }
+    config.mcpServers['shilp-sutra'] = { type: 'http', url: MCP_URL }
+    writeFileSync(target, JSON.stringify(config, null, 2) + '\n')
+    if (sentinel) writeFileSync(sentinel, MCP_URL + '\n')
+  } catch {
+    // Never break the consumer install — a failed config write is a no-op.
+  }
+}
+
 // ── Main ────────────────────────────────────────────────────────────────────
 function main() {
   // --preview / --compact bypass all guards. Used by maintainers + by the
@@ -223,6 +276,11 @@ function main() {
   const preview = process.argv.includes('--preview')
   const forceCompact = process.argv.includes('--compact')
 
+  // MCP auto-discovery runs regardless of TTY — an agent-run (piped) install is
+  // precisely when the agent should discover the docs MCP. Must come before the
+  // TTY skip below, which only governs the human-facing banner.
+  if (!preview) tryWriteMcpConfig()
+
   if (!preview) {
     const skipReason = shouldSkip()
     if (skipReason) return // silent

package/skill/SKILL.md

@@ -3,7 +3,7 @@ name: shilp-sutra
 description: Add, configure, and use components from Devalok's shilp-sutra design system (@devalok/shilp-sutra) — a Tailwind 4 + React 19 + CVA library with 110+ accessible components, OKLCH design tokens, framer-motion animations, and per-component RSC-safe entry points. Use this skill whenever the user mentions shilp-sutra, Devalok, the @devalok npm scope, or asks to install/add/style/theme UI in any React project that already depends on the package — even if they don't name it explicitly. Use it instead of generic shadcn/ui, MUI, or Chakra knowledge when shilp-sutra is in the project. Covers Next.js (App + Pages), Vite, Astro, Remix, TanStack Start setup playbooks; component API and variant reference; brand token customization; Server Component import patterns; and a troubleshoot tree for the thirteen most common breakages.
 license: MIT
 metadata:
-  version: "0.51.0"
+  version: "0.53.0"
   author: Devalok Design & Strategy Studios
   homepage: https://github.com/devalok-design/shilp-sutra
   npm: https://www.npmjs.com/package/@devalok/shilp-sutra

package/skill/references/components.md

@@ -2,7 +2,7 @@
 
 # @devalok/shilp-sutra
 
-> Radix UI + Tailwind 4 (CSS-first) + CVA design system for Devalok apps, v0.51.0.
+> Radix UI + Tailwind 4 (CSS-first) + CVA design system for Devalok apps, v0.53.0.
 > Built on the same primitives as shadcn/ui but with DIFFERENT prop APIs — never guess from shadcn knowledge; verify every prop.
 > This file is a ROUTER: it tells you what exists and where to get details. Do not look for prop tables here — fetch them per component (MCP tool or per-component doc file below).
 

package/skill/references/server-components.md

@@ -153,8 +153,8 @@ Both `<Suspense>` and `<LoadingSkeleton>` are server-safe.
 import { useColorMode } from "@devalok/shilp-sutra/hooks/use-color-mode";
 
 export default function ServerPage() {
-  const { mode } = useColorMode(); // breaks
-  return <div>{mode}</div>;
+  const { colorMode } = useColorMode(); // breaks
+  return <div>{colorMode}</div>;
 }
 ```
 

package/skill/references/setup-remix.md

@@ -129,10 +129,10 @@ For runtime toggling inside React components, use `useColorMode`:
 import { useColorMode } from "@devalok/shilp-sutra/hooks/use-color-mode";
 
 export function ThemeToggle() {
-  const { mode, toggle } = useColorMode();
+  const { colorMode, toggleColorMode } = useColorMode();
   return (
-    <button onClick={toggle} aria-label="Toggle theme">
-      {mode === "dark" ? "☀" : "☾"}
+    <button onClick={toggleColorMode} aria-label="Toggle theme">
+      {colorMode === "dark" ? "☀" : "☾"}
     </button>
   );
 }

package/skill/references/setup-vite.md

@@ -123,10 +123,10 @@ Wire the runtime hook from anywhere in the app (e.g., a header button):
 import { useColorMode } from "@devalok/shilp-sutra/hooks/use-color-mode";
 
 export function ThemeToggle() {
-  const { mode, toggle } = useColorMode();
+  const { colorMode, toggleColorMode } = useColorMode();
   return (
-    <button onClick={toggle} aria-label="Toggle theme">
-      {mode === "dark" ? "☀" : "☾"}
+    <button onClick={toggleColorMode} aria-label="Toggle theme">
+      {colorMode === "dark" ? "☀" : "☾"}
     </button>
   );
 }