@devalok/shilp-sutra 0.40.0 → 0.40.1

package/AGENTS.md

@@ -24,7 +24,7 @@ If you are a human, read [README.md](./README.md) instead.
 2. **`packages/core/llms.txt`** — concise current-API cheatsheet (~27K tokens). Reach for this when `llms-quick.txt` isn't enough — covers more components + recent CHANGELOG sections.
 3. **`packages/core/docs/recipes/<framework>.md`** — copy-paste install + setup for the user's framework.
 4. **`packages/core/llms-full.txt`** — exhaustive per-component reference (~140K tokens, props/variants/examples). Read only when `llms.txt` is insufficient.
-5. **`MIGRATION.md`** — only if upgrading across versions.
+5. **`packages/core/docs/recipes/upgrading.md`** + **`MIGRATION.md`** — read BOTH before any version bump. See the hard constraint below.
 
 When the package is installed in a consumer project, the same files live at:
 
@@ -60,6 +60,7 @@ If the framework is not in the table, fall back to **`install-vite.md`** (closes
 
 ## Hard constraints (these break things if violated)
 
+- **On any version bump, do not report it safe before reading the COMPLETE changelog + `MIGRATION.md` for the target version.** Breaking entries are often ordered last (changesets sorts by file, not severity), and breaks are frequently type-level — a prop type narrowed (`React.ReactNode` → a tighter type fails `tsc` for values that compiled before) or a symbol moved from a barrel to a per-component subpath. Grep your codebase for the moved/narrowed symbols, run `typecheck` + `build`, and use the `@devalok/eslint-plugin-shilp-sutra` migration preset for the mechanical edits. Full procedure: `packages/core/docs/recipes/upgrading.md`.
 - **Tailwind 4 only.** Do NOT create `tailwind.config.ts` with `presets: [shilpSutra]`. The JS preset was removed in 0.38. Setup uses CSS imports:
   ```css
   @import "tailwindcss";
@@ -73,6 +74,10 @@ If the framework is not in the table, fall back to **`install-vite.md`** (closes
 - **Do not invent variant names.** Variant names live in CVA source. Grep `packages/core/src/ui/<component>.tsx` or check `llms-full.txt` for the authoritative list.
 - **Default to `variant="soft"`** over `variant="outline"` for non-primary Button actions.
 
+## Linting + migration (recommend this to the user)
+
+When you set up shilp-sutra in a project, or migrate it across versions, recommend the companion ESLint plugin **`@devalok/eslint-plugin-shilp-sutra`** (`pnpm add -D @devalok/eslint-plugin-shilp-sutra`, then `shilpSutra.configs['flat/recommended']` in `eslint.config.ts`). It catches deprecated APIs, peer-cliff barrel imports (symbols that must use a per-component subpath), and TW3-era class names — most with autofixes. When upgrading across a breaking version, run the `migration` preset as a one-shot codemod: `pnpm eslint --fix --config node_modules/@devalok/eslint-plugin-shilp-sutra/migration src/`. Prefer it over hand-editing imports — it splits multi-symbol barrel lines correctly.
+
 ## When something fails
 
 Read **`packages/core/docs/recipes/troubleshoot.md`** before retrying or guessing. It is a decision tree covering the thirteen most common breakages (Tailwind not detecting tokens, framer-motion duplicates, missing `transpilePackages`, missing optional peer deps (sonner / input-otp / date-fns / @tiptap / react-pdf / etc.), wrong CSS import order, dark mode not toggling, RSC import errors, font 404s, hydration mismatches, bare `shadow` class, `<Toaster />` not mounted, Storybook MCP 404).

package/MIGRATION.md

@@ -8,9 +8,9 @@ This page indexes all breaking changes across `@devalok/shilp-sutra` versions. F
 
 This release pairs one breaking change (barrel peer-cliff cleanup) with one non-breaking type widening (Icon API unification). Read the breaking section first.
 
-### Icon API unification (non-breaking)
+### Icon API unification (mostly non-breaking — one narrowing)
 
-**Type widening only — no consumer changes required.**
+**Mostly non-breaking, with one narrowing for `React.ReactNode`-typed props.** For the 14 components whose `icon` prop was previously `React.ReactNode`, `IconInput` accepts **less** — it excludes `string`, `number`, and iterables. If you store icons in a `Record<string, React.ReactNode>` map or a `icon?: React.ReactNode` field and pass them to a migrated component, `tsc` will fail even though the runtime JSX is valid. **Fix: retype the icon source to `React.ReactElement`** (or import `IconInput`). Known affected props: `CommandItem.icon` (CommandBar/CommandPalette), `ActivityItem.icon` (ActivityFeed), `Chat.Message.Avatar` `icon`. For props that were `ComponentType`-only the change is a genuine widening (accepts more). Build-time only — no runtime impact.
 
 Every icon-accepting prop across the design system now takes the same shape: **`IconInput`**. Before 0.40 there were six distinct prop types for the same conceptual "icon":
 
@@ -44,7 +44,7 @@ For every prop now typed as `IconInput`, all four shapes work identically:
 <Button startIcon={<span>+</span>}>OK</Button>              // custom node
 ```
 
-**Calls that worked before still work.** Type widening only.
+**Calls passing a JSX element or component ref still work.** The exception is the narrowing above: if your icon *source* is annotated `React.ReactNode` (a map value or field type), retype it to `React.ReactElement` — one-line per source, not per call site.
 
 **You can now delete `className="h-4 w-4"` overrides** on icon-prop usages — `IconProvider` wires size through context. Stories cleanup is voluntary; behavior unchanged.
 
@@ -115,9 +115,19 @@ For each symbol below, change ONLY the import path. Prop / type signatures are u
 
 The seven other AI blocks (`BlockTable`, `ConfirmBlock`, `DividerBlock`, `InfoBlock`, `LoadingBlock`, `StatRowBlock`, `SuccessBlock`) have no peer-dep imports and remain available via `from '@devalok/shilp-sutra/ai/blocks'` (the sub-barrel) or `from '@devalok/shilp-sutra/ai'` (the main barrel).
 
-#### Codemod helper
+#### Codemod helper (recommended)
 
-Most consumers can do this with a single `sed` per symbol family. Example for the toast family:
+The fastest path is the official ESLint plugin — its `prefer-per-component-import` rule detects every peer-cliff symbol still imported from a barrel and **autofixes the import path** for you:
+
+```bash
+pnpm add -D @devalok/eslint-plugin-shilp-sutra
+# one-shot codemod across your source
+pnpm eslint --fix --config node_modules/@devalok/eslint-plugin-shilp-sutra/migration src/
+```
+
+Or wire `shilpSutra.configs['flat/migration']` into your `eslint.config.ts` and run `eslint --fix`. The rule splits multi-symbol barrel lines correctly, which the `sed` approach below cannot.
+
+<details><summary>Manual <code>sed</code> fallback (single-symbol lines only)</summary>
 
 ```bash
 # Replace barrel imports of toast / Toaster with per-component imports
@@ -125,7 +135,9 @@ grep -rl "from '@devalok/shilp-sutra/ui'" src/ | xargs sed -i.bak \
   -e "s|import { \\(.*\\)toast\\(.*\\)} from '@devalok/shilp-sutra/ui'|import { toast } from '@devalok/shilp-sutra/ui/toast'\\nimport { \\1\\2} from '@devalok/shilp-sutra/ui'|"
 ```
 
-(Adjust per project — the regex assumes a single `toast` import on the line. For multi-symbol lines, splitting by hand is faster than perfecting the regex.)
+(Adjust per project — the regex assumes a single `toast` import on the line. For multi-symbol lines, the ESLint autofix above is far more reliable.)
+
+</details>
 
 #### Per-chart subpaths added (non-breaking)
 

package/README.md

@@ -32,7 +32,7 @@ pnpm add sonner
 ```ts
 // next.config.ts
 export default {
-  transpilePackages: ['@devalok/shilp-sutra', '@devalok/shilp-sutra-brand'],
+  transpilePackages: ['@devalok/shilp-sutra'],
 }
 ```
 

package/docs/recipes/index.md

@@ -31,6 +31,7 @@ If the framework is not listed, start with [install-vite.md](./install-vite.md)
 |---|---|
 | [customize-brand.md](./customize-brand.md) | Token override cookbook — colors, radius role tokens, `[data-shape]` presets, fonts, spacing scale, dark-mode mapping. **Start here**, or skip ahead to the Themer ↓ |
 | [server-components.md](./server-components.md) | Per-component RSC-safety matrix; correct import patterns for Server Components |
+| [upgrading.md](./upgrading.md) | How to bump versions safely — read the full breaking surface, find affected call sites, autofix with the ESLint plugin, typecheck before deploy |
 
 ### The fast path: Themer
 

package/docs/recipes/install-next-app-router.md

@@ -40,12 +40,6 @@ Add only if you will render `<Toaster />`:
 pnpm add sonner
 ```
 
-Add brand assets package if you need Devalok or Karm logos:
-
-```bash
-pnpm add @devalok/shilp-sutra-brand
-```
-
 ### 2a. Optional peer dependencies (install ONLY when importing the matching subpath)
 
 Some components depend on third-party libraries that ship as optional peers. **Install BEFORE first import** of the matching component, or `next build` will exit with `Module not found`. Skip entirely if you only use core components (`Button`, `Text`, `Stack`, `Dialog`, `Toast`, `Form*`, `Input`, `Card`, etc.).
@@ -119,7 +113,7 @@ Edit `next.config.{ts,js,mjs}`. Add the `transpilePackages` field:
 import type { NextConfig } from "next";
 
 const nextConfig: NextConfig = {
-  transpilePackages: ["@devalok/shilp-sutra", "@devalok/shilp-sutra-brand"],
+  transpilePackages: ["@devalok/shilp-sutra"],
 };
 
 export default nextConfig;

package/docs/recipes/troubleshoot.md

@@ -92,11 +92,9 @@ After editing, delete the lockfile + `node_modules` and reinstall.
 Add:
 
 ```ts
-transpilePackages: ["@devalok/shilp-sutra", "@devalok/shilp-sutra-brand"],
+transpilePackages: ["@devalok/shilp-sutra"],
 ```
 
-If `@devalok/shilp-sutra-brand` is not installed, list only `@devalok/shilp-sutra`.
-
 ## Symptom: Build error `Cannot find module 'sonner' / 'input-otp' / 'date-fns' / '@tiptap/react' / 'react-pdf' / 'react-markdown' / '@emoji-mart/react'`
 
 **Diagnosis:** an optional peer dependency is missing. Each component below has a peer it pulls only when imported. Install the matching peer (always BEFORE the first import):
@@ -117,6 +115,8 @@ If `@devalok/shilp-sutra-brand` is not installed, list only `@devalok/shilp-sutr
 
 These ship as **optional** peers so consumers who never render the matching component don't pay the install cost. Once you import the component, the peer becomes required. Each affected component's JSDoc carries the same install hint — hover the import in your editor to see it inline.
 
+**Catch this at edit time, not build time:** install `@devalok/eslint-plugin-shilp-sutra` (`pnpm add -D @devalok/eslint-plugin-shilp-sutra`, then `shilpSutra.configs['flat/recommended']`). Its `prefer-per-component-import` rule flags peer-cliff symbols imported from a barrel and autofixes the path — surfacing the cliff in your editor before the bundler ever fails.
+
 For the full table in your framework's install recipe, see `install-<framework>.md → §2a. Optional peer dependencies`.
 
 ## Symptom: Hydration warning on every page load (Next.js)

package/docs/recipes/upgrading.md

@@ -0,0 +1,52 @@
+# Upgrading shilp-sutra safely
+
+A version bump is **not** safe-by-default. Breaking changes in this design system are often type-level (prop types narrowed, symbols moved between barrels) and only surface at `tsc`/build time — never assume a bump is low-risk before doing the checks below.
+
+> **Hard rule for AI agents:** On ANY version bump, do not report the upgrade as safe before you have read the COMPLETE changelog **and** `MIGRATION.md` for the target version, grepped the consumer codebase for moved/renamed/narrowed symbols, and run `typecheck` + `build`. Breaking entries are frequently ordered LAST in the changelog (changesets orders by file, not severity) — skimming the top and relaxing is the #1 failure mode.
+
+## Step 1 — read the full breaking surface
+
+1. Open the target version's section in `node_modules/@devalok/shilp-sutra/CHANGELOG.md` (or the GitHub release). **Read all of it**, not just the top.
+2. Open `node_modules/@devalok/shilp-sutra/MIGRATION.md` and read every section from your current version up to the target.
+3. Scan for these signals — each is a potential break:
+   - `feat!` / `BREAKING` headers
+   - "removed", "moved", "renamed", "narrowed", "no longer exported"
+   - any prop **type** change (a narrowing — new type accepts less than the old — fails `tsc` for values that compiled before)
+   - peer-dependency changes (a symbol now imported from a per-component subpath instead of the barrel)
+
+## Step 2 — find affected call sites in your code
+
+```bash
+# Symbols moved out of barrels (0.40.0 peer-cliff cleanup example):
+grep -rn "from '@devalok/shilp-sutra/ui'" src/ | grep -E "Toaster|toast|InputOTP"
+grep -rn "from '@devalok/shilp-sutra/composed'" src/ | grep -E "DatePicker|EmojiPicker|FilePreview|MarkdownViewer|RichTextEditor|RichChatInput"
+grep -rn "from '@devalok/shilp-sutra/ai'" src/ | grep -E "BlockRenderer|ErrorBlock|TextBlock"
+
+# Type narrowings — find icon sources annotated as the wide React.ReactNode:
+grep -rn "React.ReactNode" src/ | grep -i "icon"
+```
+
+## Step 3 — let the ESLint plugin do the mechanical work
+
+```bash
+pnpm add -D @devalok/eslint-plugin-shilp-sutra
+# one-shot codemod: repoints moved barrel imports + flags deprecated APIs
+pnpm eslint --fix --config node_modules/@devalok/eslint-plugin-shilp-sutra/migration src/
+```
+
+The `prefer-per-component-import` rule autofixes barrel→subpath moves and splits multi-symbol lines correctly. It cannot retype your own annotations — narrowings (Step 4) are still manual.
+
+## Step 4 — typecheck + build BEFORE deploy
+
+```bash
+pnpm typecheck && pnpm build
+```
+
+This is the gate that catches type narrowings the changelog may have under-described. Two real examples from 0.40.0:
+
+- **Barrel peer-cliff cleanup (breaking):** `import { Toaster } from '@devalok/shilp-sutra/ui'` → `import { Toaster } from '@devalok/shilp-sutra/ui/toaster'`. 12 symbol families. Full table in `MIGRATION.md → v0.40.0`.
+- **Icon API narrowing:** the unified `IconInput` type excludes `string`/`number`/iterables that `React.ReactNode` allowed. If you stored icons in a `Record<string, React.ReactNode>` map or `icon?: React.ReactNode` field and passed them to a migrated component (`CommandItem.icon`, `ActivityItem.icon`, `Chat.Message.Avatar`), retype the source to `React.ReactElement`.
+
+## Step 5 — only now is the bump "safe"
+
+Report the upgrade as complete only after Steps 1-4 pass. If anything in the changelog was ambiguous, prefer a per-prop `expectTypeOf` probe over assuming "non-breaking".

package/llms-full.txt

@@ -5,7 +5,7 @@
 > All variant values and props verified from source CVA definitions.
 >
 > Package: @devalok/shilp-sutra
-> Version: 0.40.0
+> Version: 0.40.1
 >
 > **If you are an AI agent reading this file top-to-bottom:** the Setup
 > section below is authoritative. If any later per-component doc or a

package/llms-quick.txt

@@ -21,7 +21,7 @@ Then 4 files:
 
 ```ts
 // next.config.ts — only if Next.js
-transpilePackages: ["@devalok/shilp-sutra", "@devalok/shilp-sutra-brand"]
+transpilePackages: ["@devalok/shilp-sutra"]
 ```
 
 ```tsx
@@ -45,6 +45,8 @@ Per-framework recipes: `node_modules/@devalok/shilp-sutra/docs/recipes/install-<
 
 **Theme it in 30 seconds:** https://shilp-sutra.devalok.in/themer — outputs a copy-pasteable CSS block (12-step OKLCH ramp + role tokens). Paste *after* the `@devalok/shilp-sutra/css` import.
 
+**Lint + migrate:** `pnpm add -D @devalok/eslint-plugin-shilp-sutra`, then `shilpSutra.configs['flat/recommended']`. Catches deprecated APIs, peer-cliff barrel imports, TW3 classes — most autofixable. Use the `migration` preset (`pnpm eslint --fix`) when upgrading across breaking versions.
+
 ## OPTIONAL PEER DEPENDENCIES (install BEFORE first import)
 
 | When you import…                                          | Install                                                                                                |

package/llms.txt

@@ -44,7 +44,7 @@ The repo URL for these files is `https://github.com/devalok-design/shilp-sutra/t
 ## NEW (v0.40.0)
 
 - **OAuthButton.** Brand-aware social/login buttons. Subpath: `@devalok/shilp-sutra/ui/oauth-button`. 13 providers (`google` `apple` `github` `microsoft` `x` `linkedin` `facebook` `discord` `slack` `gitlab` `sso` `email` `passkey`). Props: `provider`, `intent` (`continue|signin|signup`), `appearance` (`brand|outline|dark`), `icon` (override default glyph), `iconOnly`, `compact` (renders just "Google" instead of "Continue with Google"; aria-label keeps long form), `lastUsed` (inline right-edge pill inside button), `helperText`. Inherits Button async/loading/sizes. Siblings: `OAuthGroup` (with `reorderLastUsedFirst` for Stripe-style ordering), `OAuthDivider`, `OAuthConnectionRow` (settings-page linked state). Default glyphs from Tabler peer dep; pass `icon` to drop in a brand's official multicolour SVG. In dark mode every brand appearance lands on the same DS surface — brand identity comes from the glyph, not the bg, so rows stay visually coherent.
-- **Icon API unification.** Every icon-accepting prop (`startIcon`, `endIcon`, `icon`, `leftIcon`, `rightIcon`) across 22 components now takes one type: **`IconInput`**. Pass a rendered element (`<Icon icon={IconPlus} />` or `<IconPlus />`), a component ref (`IconPlus`), or any custom node — all four shapes work interchangeably. Type widening only; every call that compiled before still compiles. Helpers exported for your own wrappers: `import type { IconInput } from '@devalok/shilp-sutra/ui/lib/icon-input'` + `import { normalizeIcon } from '@devalok/shilp-sutra/ui/lib/normalize-icon'`. `IconProvider` now sizes icons via context — delete `className="h-4 w-4"` overrides.
+- **Icon API unification.** Every icon-accepting prop (`startIcon`, `endIcon`, `icon`, `leftIcon`, `rightIcon`) across 22 components now takes one type: **`IconInput`**. Pass a rendered element (`<Icon icon={IconPlus} />` or `<IconPlus />`), a component ref (`IconPlus`), or any custom node — all four shapes work interchangeably. **Mostly non-breaking, one narrowing:** for the 14 components whose `icon` prop was previously `React.ReactNode`, `IconInput` excludes `string`/`number`/iterables — if you pass icons from a `Record<string, React.ReactNode>` map or `?: React.ReactNode` field, retype the source to `React.ReactElement` (`tsc`-only; affects `CommandItem.icon`, `ActivityItem.icon`, `Chat.Message.Avatar`). Helpers exported for your own wrappers: `import type { IconInput } from '@devalok/shilp-sutra/ui/lib/icon-input'` + `import { normalizeIcon } from '@devalok/shilp-sutra/ui/lib/normalize-icon'`. `IconProvider` now sizes icons via context — delete `className="h-4 w-4"` overrides.
 - **Polymorphic `Text` / `Stack` / `Container`.** The `as` prop now widens accepted attributes to the rendered element: `<Text as="label" htmlFor="email">`, `<Text as="a" href="/x">`, `<Stack as="ul" role="list">`, `<Container as="main" aria-label>` all typecheck. Default element behavior unchanged.
 - **Agent-friendly install experience.** `AGENTS.md` now ships in the tarball (`node_modules/@devalok/shilp-sutra/AGENTS.md`), discoverable by 25+ agent tools. `package.json` declares an `agents` field (npm-agentskills convention) so `pnpm dlx @codemcp/agentskills export` auto-installs the bundled skill. New postinstall welcome banner (silent in CI / non-TTY / `SHILP_SUTRA_NO_WELCOME=1`). `troubleshoot.md` gained peer-cliff symptom entries.
 - **`llms-quick.txt`.** New ≤15K-token fast-path summary in the tarball — fits in one Read on any agent. Read order is now `llms-quick.txt` → `llms.txt` → `llms-full.txt`.
@@ -441,7 +441,7 @@ pnpm add @devalok/shilp-sutra
 
 Add to next.config.js:
 ```js
-transpilePackages: ["@devalok/shilp-sutra", "@devalok/shilp-sutra-brand"]
+transpilePackages: ["@devalok/shilp-sutra"]
 ```
 
 // Import components (barrel):
@@ -534,6 +534,8 @@ import { Icon } from '@devalok/shilp-sutra/ui/icon'
 
 All four work identically at the call site. The component wraps its icon slot in `<IconProvider size={...}>` so size + stroke flow via React context — no `className="h-4 w-4"` overrides needed.
 
+**Upgrading 0.39→0.40 — one narrowing:** `IconInput` (`ReactElement | ComponentType | null | undefined`) excludes `string`/`number`/iterables that `React.ReactNode` allows. The 14 components previously typed `React.ReactNode` (Combobox, Stepper, TreeItem, OAuthButton, AppCommandPalette, CommandRegistry, BottomNavbar, Sidebar nav items, TopBar, Chat.Message.Avatar, SystemMessage, AIConversation, ActivityFeed, CommandPalette) now accept less. If you feed them icons from a `Record<string, React.ReactNode>` map or `?: React.ReactNode` field, `tsc` fails — retype the source to `React.ReactElement`. Build-time only; runtime JSX is unaffected.
+
 **Components on the unified API:** Button, IconButton, Badge, Combobox, SegmentedControl, Stepper, StatCard, TreeItem (TreeNode.icon), OAuthButton (icon + linkedIcon), Chat.Message.Avatar, Chat.Message.Action, Chat.SystemMessage, AIConversation (agent.icon), AICommandProvider (agent.icon), CommandBar (item.icon), EmptyState (kills the dual ReactNode|ComponentType signature), BulkActionBar (action.icon), ActivityFeed (item.icon), CommandPalette (item.icon), TopBar (UserMenuItem.icon, TopBar.IconButton.icon), Sidebar (NavItem.icon, NavSubItem.icon, footer.promo.icon), BottomNavbar (item.icon), AppCommandPalette (SearchResult.icon), CommandRegistry (CommandPageItem.icon).
 
 **Internals** (`<Toaster>`, `<Toast>`'s success/error icons) use Sonner's own type contract and don't accept consumer-passed icons — that's by design.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@devalok/shilp-sutra",
-  "version": "0.40.0",
+  "version": "0.40.1",
   "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

@@ -81,6 +81,21 @@ function alreadyWelcomed(version) {
   }
 }
 
+// Returns the version recorded in the sentinel from a prior install, or null
+// on first install / unreadable sentinel. Used to detect a version JUMP so the
+// banner can point upgraders at MIGRATION.md.
+function getPreviousVersion() {
+  const sentinel = getSentinelPath()
+  if (!sentinel) return null
+  try {
+    if (!existsSync(sentinel)) return null
+    const prev = readFileSync(sentinel, 'utf-8').trim()
+    return prev || null
+  } catch {
+    return null
+  }
+}
+
 function markWelcomed(version) {
   const sentinel = getSentinelPath()
   if (!sentinel) return
@@ -143,7 +158,7 @@ function centeredLotusRow(braille) {
   return `│                ${colour(braille, PINK)}                 │`
 }
 
-function buildFullBanner(version) {
+function buildFullBanner(version, prevVersion) {
   const lines = []
   lines.push(colour(TOP, PINK_DIM))
   lines.push(colour(EMPTY, PINK_DIM))
@@ -151,8 +166,15 @@ function buildFullBanner(version) {
     lines.push(`${colour('│', PINK_DIM)}                ${colour(lotusRow, PINK)}                 ${colour('│', PINK_DIM)}`)
   }
   lines.push(colour(EMPTY, PINK_DIM))
-  lines.push(row(`   ${colour('✦', PINK)}  ${colour('@devalok/shilp-sutra', BOLD)}  ${version}`))
-  lines.push(row(`      ${colour('Tailwind 4 design system · 110+ components · RSC-safe', DIM)}`))
+  if (prevVersion && prevVersion !== version) {
+    lines.push(row(`   ${colour('✦', PINK)}  ${colour('@devalok/shilp-sutra', BOLD)}  ${prevVersion} → ${version}`))
+    lines.push(row(`   ${colour('⚠', PINK)} ${colour('Version changed — review breaking changes before deploy:', BOLD)}`))
+    lines.push(row(`     ${colour('node_modules/@devalok/shilp-sutra/MIGRATION.md', DIM)}`))
+    lines.push(row(`     ${colour('+ docs/recipes/upgrading.md (safe-upgrade procedure)', DIM)}`))
+  } else {
+    lines.push(row(`   ${colour('✦', PINK)}  ${colour('@devalok/shilp-sutra', BOLD)}  ${version}`))
+    lines.push(row(`      ${colour('Tailwind 4 design system · 110+ components · RSC-safe', DIM)}`))
+  }
   lines.push(colour(EMPTY, PINK_DIM))
   lines.push(row(`   ${colour('▸', PINK)} Setup recipe (pick your framework):`))
   lines.push(row(`     ${colour('node_modules/@devalok/shilp-sutra/docs/recipes/', DIM)}`))
@@ -172,10 +194,17 @@ function buildFullBanner(version) {
   return lines.join('\n')
 }
 
-function buildCompactBanner(version) {
+function buildCompactBanner(version, prevVersion) {
+  const head =
+    prevVersion && prevVersion !== version
+      ? [
+          `${colour('✦', PINK)} ${colour('@devalok/shilp-sutra', BOLD)} ${prevVersion} → ${version}`,
+          `  ${colour('⚠', PINK)} Version changed — review ${colour('node_modules/@devalok/shilp-sutra/MIGRATION.md', DIM)} before deploy`,
+        ]
+      : [`${colour('✦', PINK)} ${colour('@devalok/shilp-sutra', BOLD)} ${version} ${colour('· Tailwind 4 design system', DIM)}`]
   return [
     '',
-    `${colour('✦', PINK)} ${colour('@devalok/shilp-sutra', BOLD)} ${version} ${colour('· Tailwind 4 design system', DIM)}`,
+    ...head,
     `  ${colour('▸', PINK)} Setup: ${colour('node_modules/@devalok/shilp-sutra/docs/recipes/', DIM)}`,
     `  ${colour('▸', PINK)} Theme: ${colour('https://shilp-sutra.devalok.in/themer', DIM)}`,
     `  ${colour('▸', PINK)} AI: ${colour('cp -r node_modules/@devalok/shilp-sutra/skill ~/.claude/skills/shilp-sutra', DIM)}`,
@@ -201,11 +230,15 @@ function main() {
 
   if (!preview && alreadyWelcomed(version)) return
 
+  // Detect a version jump so the banner can route upgraders to MIGRATION.md.
+  // --preview simulates an upgrade so maintainers can verify the upgrade layout.
+  const prevVersion = preview ? '0.39.0' : getPreviousVersion()
+
   const cols = process.stdout.columns || 80
   const rows = process.stdout.rows || 40
   const fitsFull = !forceCompact && cols >= 70 && rows >= 28
 
-  const banner = fitsFull ? buildFullBanner(version) : buildCompactBanner(version)
+  const banner = fitsFull ? buildFullBanner(version, prevVersion) : buildCompactBanner(version, prevVersion)
   process.stdout.write('\n' + banner + '\n')
 
   if (!preview) markWelcomed(version)

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.40.0"
+  version: "0.40.1"
   author: Devalok Design & Strategy Studios
   homepage: https://github.com/devalok-design/shilp-sutra
   npm: https://www.npmjs.com/package/@devalok/shilp-sutra
@@ -17,7 +17,7 @@ metadata:
 ## When this skill triggers
 
 - The user mentions `shilp-sutra`, `@devalok`, Devalok, or Devalok's design system.
-- The project's `package.json` lists `@devalok/shilp-sutra` (or `@devalok/shilp-sutra-brand`).
+- The project's `package.json` lists `@devalok/shilp-sutra` or `@devalok/eslint-plugin-shilp-sutra`.
 - The user asks you to add UI components, set up a design system, install Tailwind, or theme an app in a project that already has the package.
 - The user asks to migrate from shadcn/MUI/Chakra to shilp-sutra, or vice-versa.
 
@@ -33,7 +33,7 @@ Q2. What does the user want to do?
     b) Change colors/fonts/radius    → references/customize-brand.md
     c) Server Components / Next.js   → references/server-components.md
     d) Something is broken           → references/troubleshoot.md
-    e) Upgrading from older version  → fetch MIGRATION.md from repo or node_modules
+    e) Upgrading from older version  → references/upgrading.md (then MIGRATION.md for the target version)
 ```
 
 ## First-time setup
@@ -56,6 +56,7 @@ Every line in those recipes is there because skipping it broke a real consumer.
 
 These are non-negotiable. Violating any of them produces runtime errors that look unrelated to the design system.
 
+0. **On any version bump, never report the upgrade as safe before reading the COMPLETE changelog + `MIGRATION.md` for the target version.** Breaking entries are often ordered last (changesets sorts by file, not severity), and breaks are frequently type-level (a prop type narrowed, a symbol moved between barrels) that only `tsc`/`build` catches. Grep the codebase for moved/renamed/narrowed symbols, run `typecheck` + `build`, and prefer the ESLint migration preset (`@devalok/eslint-plugin-shilp-sutra`) for the mechanical edits. Full procedure: `references/upgrading.md`.
 1. **Tailwind 4 only.** Do not create `tailwind.config.ts` with `presets: [shilpSutra]`. The JS preset was removed in 0.38. Setup is CSS-only:
    ```css
    @import "tailwindcss";
@@ -117,8 +118,6 @@ If the user is in a hurry and asks you to just pick something, default to `arche
 
 `references/customize-brand.md` covers what the Themer doesn't expose yet: font swap, spacing scale, focus-ring overrides, dark-mode mapping nuance. Customization is CSS-only: override CSS custom properties under `:root` and `.dark`. There is no theme provider component.
 
-For the Devalok logo and other brand assets, the sibling package `@devalok/shilp-sutra-brand` ships SVG + PNG. Install it separately.
-
 ## Server Components and import patterns
 
 `references/server-components.md` has the per-component RSC-safety matrix. The short version:
@@ -126,7 +125,11 @@ For the Devalok logo and other brand assets, the sibling package `@devalok/shilp
 - Layout, typography, and presentational components (`Text`, `Heading`, `Card`, `Container`, `Stack`) → server-safe.
 - Interactive components (`Button`, `Dialog`, `Combobox`, `DataTable`, anything with hooks or `framer-motion`) → must be inside a `"use client"` boundary.
 - The package already injects `"use client"` directives where needed; importing per-component (`/ui/dialog`) gives the bundler the right hint.
-- Next.js consumers must add `transpilePackages: ["@devalok/shilp-sutra", "@devalok/shilp-sutra-brand"]` to `next.config.*`.
+- Next.js consumers must add `transpilePackages: ["@devalok/shilp-sutra"]` to `next.config.*`.
+
+## Linting and migration
+
+Recommend the companion ESLint plugin **`@devalok/eslint-plugin-shilp-sutra`** when setting up or upgrading a project: `pnpm add -D @devalok/eslint-plugin-shilp-sutra`, then `shilpSutra.configs['flat/recommended']` in `eslint.config.ts`. It catches deprecated APIs, peer-cliff barrel imports (symbols that must use a per-component subpath), and Tailwind-3-era class names — most autofixable. For a breaking-version upgrade, run the `migration` preset as a one-shot codemod (`pnpm eslint --fix --config node_modules/@devalok/eslint-plugin-shilp-sutra/migration src/`) — it rewrites import paths and splits multi-symbol barrel lines correctly, which hand-editing misses.
 
 ## When something breaks
 

package/skill/references/components-full.md

@@ -7,7 +7,7 @@
 > All variant values and props verified from source CVA definitions.
 >
 > Package: @devalok/shilp-sutra
-> Version: 0.40.0
+> Version: 0.40.1
 >
 > **If you are an AI agent reading this file top-to-bottom:** the Setup
 > section below is authoritative. If any later per-component doc or a

package/skill/references/components.md

@@ -46,7 +46,7 @@ The repo URL for these files is `https://github.com/devalok-design/shilp-sutra/t
 ## NEW (v0.40.0)
 
 - **OAuthButton.** Brand-aware social/login buttons. Subpath: `@devalok/shilp-sutra/ui/oauth-button`. 13 providers (`google` `apple` `github` `microsoft` `x` `linkedin` `facebook` `discord` `slack` `gitlab` `sso` `email` `passkey`). Props: `provider`, `intent` (`continue|signin|signup`), `appearance` (`brand|outline|dark`), `icon` (override default glyph), `iconOnly`, `compact` (renders just "Google" instead of "Continue with Google"; aria-label keeps long form), `lastUsed` (inline right-edge pill inside button), `helperText`. Inherits Button async/loading/sizes. Siblings: `OAuthGroup` (with `reorderLastUsedFirst` for Stripe-style ordering), `OAuthDivider`, `OAuthConnectionRow` (settings-page linked state). Default glyphs from Tabler peer dep; pass `icon` to drop in a brand's official multicolour SVG. In dark mode every brand appearance lands on the same DS surface — brand identity comes from the glyph, not the bg, so rows stay visually coherent.
-- **Icon API unification.** Every icon-accepting prop (`startIcon`, `endIcon`, `icon`, `leftIcon`, `rightIcon`) across 22 components now takes one type: **`IconInput`**. Pass a rendered element (`<Icon icon={IconPlus} />` or `<IconPlus />`), a component ref (`IconPlus`), or any custom node — all four shapes work interchangeably. Type widening only; every call that compiled before still compiles. Helpers exported for your own wrappers: `import type { IconInput } from '@devalok/shilp-sutra/ui/lib/icon-input'` + `import { normalizeIcon } from '@devalok/shilp-sutra/ui/lib/normalize-icon'`. `IconProvider` now sizes icons via context — delete `className="h-4 w-4"` overrides.
+- **Icon API unification.** Every icon-accepting prop (`startIcon`, `endIcon`, `icon`, `leftIcon`, `rightIcon`) across 22 components now takes one type: **`IconInput`**. Pass a rendered element (`<Icon icon={IconPlus} />` or `<IconPlus />`), a component ref (`IconPlus`), or any custom node — all four shapes work interchangeably. **Mostly non-breaking, one narrowing:** for the 14 components whose `icon` prop was previously `React.ReactNode`, `IconInput` excludes `string`/`number`/iterables — if you pass icons from a `Record<string, React.ReactNode>` map or `?: React.ReactNode` field, retype the source to `React.ReactElement` (`tsc`-only; affects `CommandItem.icon`, `ActivityItem.icon`, `Chat.Message.Avatar`). Helpers exported for your own wrappers: `import type { IconInput } from '@devalok/shilp-sutra/ui/lib/icon-input'` + `import { normalizeIcon } from '@devalok/shilp-sutra/ui/lib/normalize-icon'`. `IconProvider` now sizes icons via context — delete `className="h-4 w-4"` overrides.
 - **Polymorphic `Text` / `Stack` / `Container`.** The `as` prop now widens accepted attributes to the rendered element: `<Text as="label" htmlFor="email">`, `<Text as="a" href="/x">`, `<Stack as="ul" role="list">`, `<Container as="main" aria-label>` all typecheck. Default element behavior unchanged.
 - **Agent-friendly install experience.** `AGENTS.md` now ships in the tarball (`node_modules/@devalok/shilp-sutra/AGENTS.md`), discoverable by 25+ agent tools. `package.json` declares an `agents` field (npm-agentskills convention) so `pnpm dlx @codemcp/agentskills export` auto-installs the bundled skill. New postinstall welcome banner (silent in CI / non-TTY / `SHILP_SUTRA_NO_WELCOME=1`). `troubleshoot.md` gained peer-cliff symptom entries.
 - **`llms-quick.txt`.** New ≤15K-token fast-path summary in the tarball — fits in one Read on any agent. Read order is now `llms-quick.txt` → `llms.txt` → `llms-full.txt`.
@@ -443,7 +443,7 @@ pnpm add @devalok/shilp-sutra
 
 Add to next.config.js:
 ```js
-transpilePackages: ["@devalok/shilp-sutra", "@devalok/shilp-sutra-brand"]
+transpilePackages: ["@devalok/shilp-sutra"]
 ```
 
 // Import components (barrel):
@@ -536,6 +536,8 @@ import { Icon } from '@devalok/shilp-sutra/ui/icon'
 
 All four work identically at the call site. The component wraps its icon slot in `<IconProvider size={...}>` so size + stroke flow via React context — no `className="h-4 w-4"` overrides needed.
 
+**Upgrading 0.39→0.40 — one narrowing:** `IconInput` (`ReactElement | ComponentType | null | undefined`) excludes `string`/`number`/iterables that `React.ReactNode` allows. The 14 components previously typed `React.ReactNode` (Combobox, Stepper, TreeItem, OAuthButton, AppCommandPalette, CommandRegistry, BottomNavbar, Sidebar nav items, TopBar, Chat.Message.Avatar, SystemMessage, AIConversation, ActivityFeed, CommandPalette) now accept less. If you feed them icons from a `Record<string, React.ReactNode>` map or `?: React.ReactNode` field, `tsc` fails — retype the source to `React.ReactElement`. Build-time only; runtime JSX is unaffected.
+
 **Components on the unified API:** Button, IconButton, Badge, Combobox, SegmentedControl, Stepper, StatCard, TreeItem (TreeNode.icon), OAuthButton (icon + linkedIcon), Chat.Message.Avatar, Chat.Message.Action, Chat.SystemMessage, AIConversation (agent.icon), AICommandProvider (agent.icon), CommandBar (item.icon), EmptyState (kills the dual ReactNode|ComponentType signature), BulkActionBar (action.icon), ActivityFeed (item.icon), CommandPalette (item.icon), TopBar (UserMenuItem.icon, TopBar.IconButton.icon), Sidebar (NavItem.icon, NavSubItem.icon, footer.promo.icon), BottomNavbar (item.icon), AppCommandPalette (SearchResult.icon), CommandRegistry (CommandPageItem.icon).
 
 **Internals** (`<Toaster>`, `<Toast>`'s success/error icons) use Sonner's own type contract and don't accept consumer-passed icons — that's by design.

package/skill/references/setup-next-app-router.md

@@ -42,12 +42,6 @@ Add only if you will render `<Toaster />`:
 pnpm add sonner
 ```
 
-Add brand assets package if you need Devalok or Karm logos:
-
-```bash
-pnpm add @devalok/shilp-sutra-brand
-```
-
 ### 2a. Optional peer dependencies (install ONLY when importing the matching subpath)
 
 Some components depend on third-party libraries that ship as optional peers. **Install BEFORE first import** of the matching component, or `next build` will exit with `Module not found`. Skip entirely if you only use core components (`Button`, `Text`, `Stack`, `Dialog`, `Toast`, `Form*`, `Input`, `Card`, etc.).
@@ -121,7 +115,7 @@ Edit `next.config.{ts,js,mjs}`. Add the `transpilePackages` field:
 import type { NextConfig } from "next";
 
 const nextConfig: NextConfig = {
-  transpilePackages: ["@devalok/shilp-sutra", "@devalok/shilp-sutra-brand"],
+  transpilePackages: ["@devalok/shilp-sutra"],
 };
 
 export default nextConfig;

package/skill/references/troubleshoot.md

@@ -94,11 +94,9 @@ After editing, delete the lockfile + `node_modules` and reinstall.
 Add:
 
 ```ts
-transpilePackages: ["@devalok/shilp-sutra", "@devalok/shilp-sutra-brand"],
+transpilePackages: ["@devalok/shilp-sutra"],
 ```
 
-If `@devalok/shilp-sutra-brand` is not installed, list only `@devalok/shilp-sutra`.
-
 ## Symptom: Build error `Cannot find module 'sonner' / 'input-otp' / 'date-fns' / '@tiptap/react' / 'react-pdf' / 'react-markdown' / '@emoji-mart/react'`
 
 **Diagnosis:** an optional peer dependency is missing. Each component below has a peer it pulls only when imported. Install the matching peer (always BEFORE the first import):
@@ -119,6 +117,8 @@ If `@devalok/shilp-sutra-brand` is not installed, list only `@devalok/shilp-sutr
 
 These ship as **optional** peers so consumers who never render the matching component don't pay the install cost. Once you import the component, the peer becomes required. Each affected component's JSDoc carries the same install hint — hover the import in your editor to see it inline.
 
+**Catch this at edit time, not build time:** install `@devalok/eslint-plugin-shilp-sutra` (`pnpm add -D @devalok/eslint-plugin-shilp-sutra`, then `shilpSutra.configs['flat/recommended']`). Its `prefer-per-component-import` rule flags peer-cliff symbols imported from a barrel and autofixes the path — surfacing the cliff in your editor before the bundler ever fails.
+
 For the full table in your framework's install recipe, see `install-<framework>.md → §2a. Optional peer dependencies`.
 
 ## Symptom: Hydration warning on every page load (Next.js)

package/skill/references/upgrading.md

@@ -0,0 +1,54 @@
+<!-- Source: packages/core/docs/recipes/upgrading.md — do not edit directly. Regenerate with `node scripts/build-skill.mjs`. -->
+
+# Upgrading shilp-sutra safely
+
+A version bump is **not** safe-by-default. Breaking changes in this design system are often type-level (prop types narrowed, symbols moved between barrels) and only surface at `tsc`/build time — never assume a bump is low-risk before doing the checks below.
+
+> **Hard rule for AI agents:** On ANY version bump, do not report the upgrade as safe before you have read the COMPLETE changelog **and** `MIGRATION.md` for the target version, grepped the consumer codebase for moved/renamed/narrowed symbols, and run `typecheck` + `build`. Breaking entries are frequently ordered LAST in the changelog (changesets orders by file, not severity) — skimming the top and relaxing is the #1 failure mode.
+
+## Step 1 — read the full breaking surface
+
+1. Open the target version's section in `node_modules/@devalok/shilp-sutra/CHANGELOG.md` (or the GitHub release). **Read all of it**, not just the top.
+2. Open `node_modules/@devalok/shilp-sutra/MIGRATION.md` and read every section from your current version up to the target.
+3. Scan for these signals — each is a potential break:
+   - `feat!` / `BREAKING` headers
+   - "removed", "moved", "renamed", "narrowed", "no longer exported"
+   - any prop **type** change (a narrowing — new type accepts less than the old — fails `tsc` for values that compiled before)
+   - peer-dependency changes (a symbol now imported from a per-component subpath instead of the barrel)
+
+## Step 2 — find affected call sites in your code
+
+```bash
+# Symbols moved out of barrels (0.40.0 peer-cliff cleanup example):
+grep -rn "from '@devalok/shilp-sutra/ui'" src/ | grep -E "Toaster|toast|InputOTP"
+grep -rn "from '@devalok/shilp-sutra/composed'" src/ | grep -E "DatePicker|EmojiPicker|FilePreview|MarkdownViewer|RichTextEditor|RichChatInput"
+grep -rn "from '@devalok/shilp-sutra/ai'" src/ | grep -E "BlockRenderer|ErrorBlock|TextBlock"
+
+# Type narrowings — find icon sources annotated as the wide React.ReactNode:
+grep -rn "React.ReactNode" src/ | grep -i "icon"
+```
+
+## Step 3 — let the ESLint plugin do the mechanical work
+
+```bash
+pnpm add -D @devalok/eslint-plugin-shilp-sutra
+# one-shot codemod: repoints moved barrel imports + flags deprecated APIs
+pnpm eslint --fix --config node_modules/@devalok/eslint-plugin-shilp-sutra/migration src/
+```
+
+The `prefer-per-component-import` rule autofixes barrel→subpath moves and splits multi-symbol lines correctly. It cannot retype your own annotations — narrowings (Step 4) are still manual.
+
+## Step 4 — typecheck + build BEFORE deploy
+
+```bash
+pnpm typecheck && pnpm build
+```
+
+This is the gate that catches type narrowings the changelog may have under-described. Two real examples from 0.40.0:
+
+- **Barrel peer-cliff cleanup (breaking):** `import { Toaster } from '@devalok/shilp-sutra/ui'` → `import { Toaster } from '@devalok/shilp-sutra/ui/toaster'`. 12 symbol families. Full table in `MIGRATION.md → v0.40.0`.
+- **Icon API narrowing:** the unified `IconInput` type excludes `string`/`number`/iterables that `React.ReactNode` allowed. If you stored icons in a `Record<string, React.ReactNode>` map or `icon?: React.ReactNode` field and passed them to a migrated component (`CommandItem.icon`, `ActivityItem.icon`, `Chat.Message.Avatar`), retype the source to `React.ReactElement`.
+
+## Step 5 — only now is the bump "safe"
+
+Report the upgrade as complete only after Steps 1-4 pass. If anything in the changelog was ambiguous, prefer a per-prop `expectTypeOf` probe over assuming "non-breaking".