@devalok/shilp-sutra 0.39.0 → 0.40.1

package/scripts/welcome.mjs

@@ -0,0 +1,252 @@
+#!/usr/bin/env node
+/**
+ * Postinstall welcome banner for @devalok/shilp-sutra.
+ *
+ * Runs once per major.minor version on consumer install. Silent under CI,
+ * non-TTY environments, NO_COLOR, npm silent loglevel, or when the
+ * SHILP_SUTRA_NO_WELCOME env var is set. Falls back to a compact 6-line
+ * text block if the terminal is narrower than 70 columns or shorter than
+ * 28 rows. Never throws — wrapped in a try/catch so an internal error can
+ * never break the consumer install.
+ *
+ * Safety guards (industry best practice — see research notes in
+ * .changeset/wave-4-install-experience.md):
+ *
+ *   - process.env.CI                          → silent (avoid log noise on CI)
+ *   - process.env.SHILP_SUTRA_NO_WELCOME=1    → silent (user opt-out)
+ *   - process.env.NO_COLOR                    → plain text, no ANSI
+ *   - process.stdout.isTTY === false          → silent (piped builds, Docker)
+ *   - npm_config_loglevel === 'silent'        → silent (respect pkg manager)
+ *   - !INIT_CWD || INIT_CWD inside the package → silent (dev install, not consumer)
+ *   - Sentinel file with current version       → silent on re-install of same ver
+ *   - try/catch around everything              → always exit 0
+ *
+ * The sentinel encodes the version (`node_modules/.shilp-sutra-welcomed`)
+ * so version bumps re-fire the banner once.
+ */
+
+import { existsSync, mkdirSync, readFileSync, writeFileSync } from 'node:fs'
+import { dirname, join, resolve } from 'node:path'
+import { fileURLToPath } from 'node:url'
+
+const __dirname = dirname(fileURLToPath(import.meta.url))
+const PKG_DIR = resolve(__dirname, '..')
+
+// ── Guard rails — bail out early if any condition says "silent". ────────────
+function shouldSkip() {
+  if (process.env.CI) return 'CI environment'
+  if (process.env.SHILP_SUTRA_NO_WELCOME === '1' || process.env.SHILP_SUTRA_NO_WELCOME === 'true') return 'SHILP_SUTRA_NO_WELCOME set'
+  if (process.env.npm_config_loglevel === 'silent') return 'npm silent loglevel'
+  if (!process.stdout.isTTY) return 'not a TTY (piped/Docker/etc.)'
+  // Dev install — we're inside the design-system repo itself, not a consumer
+  const initCwd = process.env.INIT_CWD || process.cwd()
+  const cwd = process.cwd()
+  const isInsideNodeModules = cwd.includes(`${process.platform === 'win32' ? '\\' : '/'}node_modules${process.platform === 'win32' ? '\\' : '/'}`) || cwd.includes('/node_modules/')
+  if (!isInsideNodeModules) return 'dev install (not running from node_modules/)'
+  // INIT_CWD points at the consumer's project root. If absent → odd setup; skip.
+  if (!initCwd || initCwd === cwd) return 'no INIT_CWD set (unusual install context)'
+  return null
+}
+
+function readPkgVersion() {
+  try {
+    const pkg = JSON.parse(readFileSync(join(PKG_DIR, 'package.json'), 'utf-8'))
+    return pkg.version
+  } catch {
+    return null
+  }
+}
+
+// Sentinel: re-fire only on version change. Stored at the workspace root's
+// node_modules/.shilp-sutra-welcomed so it survives pnpm dedupe rebuilds.
+function getSentinelPath() {
+  // Walk up from PKG_DIR (node_modules/@devalok/shilp-sutra/) to the
+  // enclosing node_modules/ root, then write inside it.
+  const parts = PKG_DIR.split(/[/\\]/)
+  const nmIdx = parts.lastIndexOf('node_modules')
+  if (nmIdx === -1) return null
+  const nmRoot = parts.slice(0, nmIdx + 1).join(process.platform === 'win32' ? '\\' : '/')
+  return join(nmRoot, '.shilp-sutra-welcomed')
+}
+
+function alreadyWelcomed(version) {
+  const sentinel = getSentinelPath()
+  if (!sentinel) return false
+  try {
+    if (!existsSync(sentinel)) return false
+    const previousVersion = readFileSync(sentinel, 'utf-8').trim()
+    return previousVersion === version
+  } catch {
+    return false
+  }
+}
+
+// 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
+  try {
+    mkdirSync(dirname(sentinel), { recursive: true })
+    writeFileSync(sentinel, version + '\n')
+  } catch {
+    // ignored — banner already printed, sentinel write is best-effort
+  }
+}
+
+// ── ANSI rendering ──────────────────────────────────────────────────────────
+const useColor = !process.env.NO_COLOR && process.stdout.isTTY
+
+// Devalok pink #d946a6 = RGB(217, 70, 166)
+const PINK = useColor ? '\x1b[38;2;217;70;166m' : ''
+const PINK_DIM = useColor ? '\x1b[38;2;167;55;128m' : ''
+const BOLD = useColor ? '\x1b[1m' : ''
+const DIM = useColor ? '\x1b[2m' : ''
+const RESET = useColor ? '\x1b[0m' : ''
+
+function colour(text, code) {
+  return useColor ? `${code}${text}${RESET}` : text
+}
+
+// Lotus — 13 rows × 30 cols Braille. Centered in a 63-col inner box (16 left,
+// 17 right padding).
+const LOTUS = [
+  '⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⣰⣦⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀',
+  '⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⢀⣴⠟⠹⣧⡀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀',
+  '⠀⠀⠀⠀⠀⠀⠀⠀⣷⣦⣄⣠⣿⠃⢠⣄⠈⢻⣆⣠⣴⡞⡆⠀⠀⠀⠀⠀⠀⠀',
+  '⠀⠀⠀⠀⠀⢀⣀⣀⣿⠀⠈⢻⣇⢀⣾⢟⡄⣸⡿⠋⠀⡇⣇⣀⣀⠀⠀⠀⠀⠀',
+  '⠀⣤⣤⣤⣀⣱⢻⠚⠻⣧⣀⠀⢹⡿⠃⠈⢻⣟⠀⢀⣤⠧⠓⣹⣟⣀⣤⣤⣤⡀',
+  '⠀⠈⠻⣧⠉⠛⣽⠀⠀⠀⠙⣷⡿⠁⠀⠀⠀⢻⣶⠛⠁⠀⠀⡟⠟⠉⣵⡟⠁⠀',
+  '⠀⠀⠀⠹⣧⡀⠏⡇⠀⠀⠀⣿⠁⠀⠀⠀⠀⠀⣿⡄⠀⠀⢠⢷⠀⣼⡟⠀⠀⠀',
+  '⠀⠀⠀⠀⠙⣟⢼⡹⡄⠀⠀⣿⡄⠀⠀⠀⠀⢀⣿⡇⠀⢀⣞⣦⢾⠟⠀⠀⠀⠀',
+  '⠀⠠⢶⣿⣛⠛⢒⣭⢻⣶⣤⣹⣿⣤⣀⣀⣠⣾⣟⣠⣔⡛⢫⣐⠛⢛⣻⣶⠆⠀',
+  '⠀⠀⠀⠉⣻⡽⠛⠉⠁⠀⠉⢙⣿⠖⠒⠛⠻⣿⡋⠉⠁⠈⠉⠙⢿⣿⠉⠀⠀⠀',
+  '⠀⠀⠀⠸⠿⠷⠒⣦⣤⣴⣶⢿⣿⡀⠀⠀⠀⣽⡿⢷⣦⠤⢤⡖⠶⠿⠧⠀⠀⠀',
+  '⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠛⢿⣦⣴⡾⠟⠁⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀',
+  '⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠙⠟⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀',
+]
+
+const TOP = '╭───────────────────────────────────────────────────────────────╮'
+const BOTTOM = '╰───────────────────────────────────────────────────────────────╯'
+const EMPTY = '│                                                               │'
+const INNER_WIDTH = 63
+
+function row(content) {
+  // content is a string of visible chars (ANSI-stripped width assumed equal to char count for ASCII)
+  // We can't easily measure visible width when ANSI codes are present, so always pad based on the
+  // PASSED visibleWidth in callers that contain colour. For plain rows, fall back to .length.
+  const visible = content.replace(/\x1b\[[0-9;]*m/g, '')
+  const padLen = Math.max(0, INNER_WIDTH - visible.length)
+  return `│${content}${' '.repeat(padLen)}│`
+}
+
+function centeredLotusRow(braille) {
+  // 30-col Braille row, 16-left + 17-right padding
+  return `│                ${colour(braille, PINK)}                 │`
+}
+
+function buildFullBanner(version, prevVersion) {
+  const lines = []
+  lines.push(colour(TOP, PINK_DIM))
+  lines.push(colour(EMPTY, PINK_DIM))
+  for (const lotusRow of LOTUS) {
+    lines.push(`${colour('│', PINK_DIM)}                ${colour(lotusRow, PINK)}                 ${colour('│', PINK_DIM)}`)
+  }
+  lines.push(colour(EMPTY, PINK_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)}`))
+  lines.push(colour(EMPTY, PINK_DIM))
+  lines.push(row(`   ${colour('▸', PINK)} Theme it in 30 seconds:`))
+  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('cp -r node_modules/@devalok/shilp-sutra/skill \\', DIM)}`))
+  lines.push(row(`        ${colour('~/.claude/skills/shilp-sutra', DIM)}`))
+  lines.push(colour(EMPTY, PINK_DIM))
+  lines.push(row(`   ${colour('Disable this banner: SHILP_SUTRA_NO_WELCOME=1', DIM)}`))
+  lines.push(colour(EMPTY, PINK_DIM))
+  lines.push(row(`   ${colour('Built by Devalok · devalok.in', PINK)}`))
+  lines.push(colour(EMPTY, PINK_DIM))
+  lines.push(colour(BOTTOM, PINK_DIM))
+  return lines.join('\n')
+}
+
+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 [
+    '',
+    ...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)}`,
+    `  ${colour('Built by Devalok · devalok.in', PINK)}  ${colour('(SHILP_SUTRA_NO_WELCOME=1 to disable)', DIM)}`,
+    '',
+  ].join('\n')
+}
+
+// ── Main ────────────────────────────────────────────────────────────────────
+function main() {
+  // --preview / --compact bypass all guards. Used by maintainers + by the
+  // pre-publish-audit gate to verify the banner renders without ever
+  // shipping a broken one. Compose only — never writes the sentinel.
+  const preview = process.argv.includes('--preview')
+  const forceCompact = process.argv.includes('--compact')
+
+  if (!preview) {
+    const skipReason = shouldSkip()
+    if (skipReason) return // silent
+  }
+
+  const version = readPkgVersion() || '0.0.0-preview'
+
+  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, prevVersion) : buildCompactBanner(version, prevVersion)
+  process.stdout.write('\n' + banner + '\n')
+
+  if (!preview) markWelcomed(version)
+}
+
+try {
+  main()
+} catch {
+  // Never crash the consumer install. A failure here is a UX bug, not a
+  // blocker — pretend nothing happened.
+}

package/skill/SKILL.md

@@ -1,9 +1,9 @@
 ---
 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 eight most common breakages.
+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.38.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";
@@ -96,9 +97,26 @@ Putting `bg-surface-base` on a card is a bug — cards belong on `surface-raised
 
 ## Theming and brand customization
 
-`references/customize-brand.md` covers token overrides — color ramps, radius, font swap, spacing scale, dark-mode mapping. Customization is CSS-only: override CSS custom properties under `:root` and `.dark`. There is no theme provider component.
+### Step 0 — Send the user to the Themer
 
-For the Devalok logo and other brand assets, the sibling package `@devalok/shilp-sutra-brand` ships SVG + PNG. Install it separately.
+Before hand-rolling CSS variables, send the user to **[shilp-sutra.devalok.in/themer](https://shilp-sutra.devalok.in/themer)**. One funnel, four doors:
+
+| User context | Door |
+|---|---|
+| "Make it look like Linear / Stripe / Apple / Notion / Vercel / Material" | `/themer/archetypes` |
+| "Here is our brand color: `#…`" | `/themer/brand` |
+| "Not sure what we want yet" | `/themer/wizard` |
+| "Just show me what we'd ship away with" | `/themer/result?archetype=devalok` |
+
+Every door drops them at `/themer/result` with: a copy-pasteable CSS block (role tokens + 12-step OKLCH accent ramp), install commands for their package manager, a live preview, and a share URL that encodes the theme (`?archetype=…&hue=…&chroma=…&density=…`).
+
+Your job once they have the snippet: paste it into their global stylesheet **after** the `@import "@devalok/shilp-sutra/css";` line. That is it — no `tailwind.config.ts`, no provider, no JS bundle.
+
+If the user is in a hurry and asks you to just pick something, default to `archetype=devalok` (the studio's own preset, balanced for most apps) and use their brand hex if they have one, else `hue=340 chroma=0.19`.
+
+### Step 1 — Hand-roll fallback
+
+`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.
 
 ## Server Components and import patterns
 
@@ -107,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.39.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
@@ -3034,6 +3034,92 @@ const { size, stroke } = useIconContext()
 
 ### v0.1.0
 - **Added** Initial release
+# OAuthButton
+
+- Import: @devalok/shilp-sutra/ui/oauth-button
+- Server-safe: No
+- Category: ui
+
+## Exports
+- `OAuthButton` — primary brand-aware sign-in button
+- `OAuthGroup` — stacked layout wrapper with consistent spacing
+- `OAuthDivider` — `or`-style horizontal rule between OAuth row and email form
+- `OAuthConnectionRow` — settings-page row for a linked provider (Disconnect / Connect action)
+
+## OAuthButton props
+    provider: "google" | "apple" | "github" | "microsoft" | "x" | "linkedin" | "facebook" | "discord" | "slack" | "gitlab" | "sso" | "email" | "passkey" (required)
+    intent: "continue" | "signin" | "signup" (default "continue") — drives the verb in the label
+    appearance: "brand" | "outline" | "dark" (default "brand") — visual treatment
+    icon: ReactNode — override the default Tabler glyph with a brand-multicolour SVG
+    iconOnly: boolean — compact icon-only button; provider name preserved in aria-label
+    compact: boolean — short label ("Google" not "Continue with Google"); aria-label keeps long form
+    lastUsed: boolean — inline right-edge pill inside the button (a stronger pattern is reorder, below)
+    helperText: ReactNode — reassurance copy rendered below the button
+    children: ReactNode — override the default label entirely (i18n / custom copy)
+    size: inherited from Button ("xs" | "sm" | "md" | "lg" | compact + icon variants)
+    fullWidth, loading, onClick, onClickAsync, asyncFeedbackDuration, disabled — inherited from Button
+
+## Data attributes
+- `data-provider="<provider>"` — useful for analytics filtering
+- `data-oauth-appearance="<appearance>"`
+
+## OAuthGroup props
+    orientation: "vertical" | "horizontal" (default "vertical")
+    gap: "ds-02" | "ds-03" | "ds-04" (default "ds-03")
+    fullWidth: boolean (default true) — stretches children to fill width when vertical
+    reorderLastUsedFirst: boolean (default false) — pull the child with lastUsed to position 0
+        (Stripe-style — a stronger conversion lever than a visual badge alone)
+
+## OAuthDivider props
+    label: ReactNode (default "or")
+
+## OAuthConnectionRow props
+    provider: OAuthProvider (required)
+    connected: boolean (required)
+    accountLabel: ReactNode — account identifier shown next to the provider name (e.g. email)
+    onAction: (e) => void — synchronous click handler
+    onActionAsync: (e) => Promise<void> — uses Button's async state machine
+    actionLabel: ReactNode — override the "Disconnect" / "Connect <name>" copy
+    icon: ReactNode — override the default glyph
+    disabled: boolean
+
+## Defaults
+    intent="continue", appearance="brand", iconOnly=false, lastUsed=false
+
+## Example
+```jsx
+// Typical signup flow
+<OAuthGroup>
+  <OAuthButton provider="google" lastUsed />
+  <OAuthButton provider="apple" />
+  <OAuthButton provider="github" />
+</OAuthGroup>
+<OAuthDivider />
+<OAuthGroup>
+  <OAuthButton provider="passkey" appearance="outline" />
+  <OAuthButton provider="email" appearance="outline" />
+</OAuthGroup>
+
+// Async loading + success/error feedback
+<OAuthButton provider="google" fullWidth onClickAsync={signInWithGoogle} />
+
+// True brand-multicolour glyph from the provider's brand page
+<OAuthButton provider="google" icon={<GoogleGSvg />} />
+
+// Settings page — linked state
+<OAuthConnectionRow
+  provider="google"
+  connected
+  accountLabel="namaskar@devalok.in"
+  onAction={disconnectGoogle}
+/>
+```
+
+## Composability
+- **Built on Button.** Async state machine, loading/processing, sizes, and `fullWidth` are inherited. `variant` and `color` are managed internally — pass `appearance` instead.
+- **Tabler peer dep.** Default glyphs come from `@tabler/icons-react`. To match a provider's official multicolour mark, pass `icon={<YourSvg />}`.
+- **Brand-colour backgrounds.** `appearance="brand"` uses each provider's published button colour. `appearance="outline"` falls back to DS-neutral. `appearance="dark"` unifies every provider into an Apple-style black-on-white (light) / white-on-black (dark) treatment — useful when you want a row to feel visually consistent across providers.
+- **Last-used hint.** Storage is the consumer's responsibility — pass `lastUsed={user.lastProvider === 'google'}`.
 # Pagination
 
 - Import: @devalok/shilp-sutra/ui/pagination

package/skill/references/components.md

@@ -28,8 +28,34 @@ Other recipes:
 - `server-components.md` — RSC-safety matrix and import patterns
 - `troubleshoot.md` — decision tree for the 8 most common breakages
 
+## The Themer (fast path for branding)
+
+Before hand-writing CSS variables, point the user at **https://shilp-sutra.devalok.in/themer** — one funnel, four doors. Each door drops the user at a result page with install commands + a copy-pasteable CSS block (role tokens + 12-step OKLCH accent ramp) + a shareable URL.
+
+| User context | URL |
+|---|---|
+| "Make it look like Linear / Stripe / Apple / Material / Notion / Vercel / Devalok" | `/themer/archetypes` |
+| "Here's our brand color: `#…`" | `/themer/brand` |
+| "Not sure" | `/themer/wizard` |
+| "Show me a sample result" | `/themer/result?archetype=devalok` |
+
+Paste the snippet *after* `@import "@devalok/shilp-sutra/css";` in the global stylesheet. No `tailwind.config.ts`, no theme provider, no JS bundle. Fall through to `customize-brand.md` only for tokens the Themer doesn't expose yet (font stack, spacing scale, focus ring).
+
 The repo URL for these files is `https://github.com/devalok-design/shilp-sutra/tree/main/packages/core/docs/recipes`. Consumer projects should also have an `AGENTS.md` at their root with the rules above pre-loaded — read that first if it exists.
 
+## 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. **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`.
+- **Companion package `@devalok/eslint-plugin-shilp-sutra`** (first release). 12 rules — deprecated-API catches, peer-cliff barrel-import detection, TW3→TW4 classname autofixes. `pnpm add -D @devalok/eslint-plugin-shilp-sutra`, then `shilpSutra.configs['flat/recommended']`. Three presets: `recommended`, `strict`, `migration` (one-shot codemod).
+
+## BREAKING CHANGES (v0.40.0)
+
+- **Barrel peer-cliff cleanup.** 12 symbols that statically import optional peers were removed from their parent barrels (`/ui`, `/composed`, `/ai`, `/ai/blocks`) — they now import ONLY via per-component subpath. Affected: `Toaster`/`toast` (→ `/ui/toaster`, `/ui/toast`), `InputOTP*` (→ `/ui/input-otp`), `DatePicker*` (→ `/composed/date-picker`), `EmojiPicker*` (→ `/composed/emoji-picker`), `FilePreview` (→ `/composed/file-preview`), `MarkdownViewer` (→ `/composed/markdown-viewer`), `RichTextEditor*`/`RichChatInput*` (→ their subpaths), `BlockRenderer`/`ErrorBlock`/`TextBlock` (→ `/ai/*`). Fixes `Module not found: Can't resolve 'sonner'`/etc. at consumer build time. Full before/after table in `MIGRATION.md → v0.40.0`. Per-chart subpaths (`/ui/charts/bar-chart`, etc.) added non-breaking alongside.
+
 ## NEW (v0.39.0)
 
 - **Shape presets (`[data-shape]`).** Set on `<html>` (or any subtree) to re-skin roundness across the whole UI. Three ship by default: `sharp` (technical, 2/4/6 px), `slightly-rounded` (default, 6/10/16 px), `rounded` (consumer, 10/16/24 px). Pill shapes (Badge, Switch, Radio, Avatar circle) stay pill regardless.
@@ -417,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):
@@ -443,6 +469,87 @@ import { useColorMode } from '@devalok/shilp-sutra/hooks/use-color-mode'
 // CSS tokens (import once at app root — already included in /css):
 import '@devalok/shilp-sutra/css'
 
+## IMPORT PATH CHEATSHEET (don't guess — these subpaths are NOT always the kebab-case of the component name)
+
+> **0.40.0 — barrel peer-cliff cleanup.** Components below marked `MANDATORY per-component` were removed from their parent barrel (`/ui`, `/composed`, `/ai`, `/ai/blocks`) because they statically import optional peers (`input-otp`, `sonner`, `date-fns`, `@emoji-mart/*`, `react-pdf`, `react-zoom-pan-pinch`, `react-markdown`, `remark-gfm`, `react-syntax-highlighter`, `@tiptap/*`). Fresh consumers using the barrel were getting `Module not found` at build time. The per-component subpath is now the ONLY way to import them. See MIGRATION.md → "v0.40.0 — barrel peer-cliff cleanup" for the full before/after.
+
+Common confusions to memorize:
+
+| Component / API                                | Exact import path                                              |
+|------------------------------------------------|----------------------------------------------------------------|
+| `FormField`, `FormHelperText`, `useFormField`  | `@devalok/shilp-sutra/ui/form`            (NOT `ui/form-field`)|
+| `Label`                                        | `@devalok/shilp-sutra/ui/label`                                |
+| `AppSidebar`                                   | `@devalok/shilp-sutra/shell/sidebar`      (NOT `shell/app-sidebar`)|
+| `TopBar`, `TopBar.*`                           | `@devalok/shilp-sutra/shell/top-bar`                           |
+| `BottomNavbar`                                 | `@devalok/shilp-sutra/shell/bottom-navbar`                     |
+| `AppCommandPalette`                            | `@devalok/shilp-sutra/shell/app-command-palette`               |
+| `CommandRegistryProvider`, `useCommandRegistry`| `@devalok/shilp-sutra/shell/command-registry`                  |
+| `NotificationCenter`                           | `@devalok/shilp-sutra/shell/notification-center`               |
+| `NotificationPreferences`                      | `@devalok/shilp-sutra/shell/notification-preferences`          |
+| `LinkProvider`, `useLink`                      | `@devalok/shilp-sutra/shell/link-context`                      |
+| `CommandPalette` (lower-level palette)         | `@devalok/shilp-sutra/composed/command-palette`                |
+| `BarChart`, `LineChart`, `AreaChart`, `PieChart`, `RadarChart`, `GaugeChart`, `Sparkline`, `ChartContainer`, `Legend` | `@devalok/shilp-sutra/ui/charts` (full barrel, pulls all 9 d3-\* peers) — **prefer per-chart subpath when possible: `/ui/charts/bar-chart`, `/ui/charts/line-chart`, `/ui/charts/area-chart`, `/ui/charts/pie-chart`, `/ui/charts/radar-chart`, `/ui/charts/gauge-chart`, `/ui/charts/sparkline`, `/ui/charts/chart-container`** (each pulls only the d3-\* peers it needs — BarChart needs `d3-scale` + `d3-axis` + `d3-selection`; PieChart/RadarChart need only `d3-shape`) |
+| `DataTable`                                    | `@devalok/shilp-sutra/ui/data-table`                           |
+| `DataTableToolbar`                             | `@devalok/shilp-sutra/ui/data-table-toolbar`                   |
+| `DatePicker`, `DateRangePicker`, `DateTimePicker`, `TimePicker`, `CalendarGrid`, `YearPicker`, `MonthPicker`, `Presets`, `useCalendar` | `@devalok/shilp-sutra/composed/date-picker` **MANDATORY per-component (0.40.0+)** — pulls `date-fns` |
+| `Toaster`                                      | `@devalok/shilp-sutra/ui/toaster` **MANDATORY per-component (0.40.0+)** — pulls `sonner`           |
+| `toast`                                        | `@devalok/shilp-sutra/ui/toast` **MANDATORY per-component (0.40.0+)** — pulls `sonner`             |
+| `InputOTP`, `InputOTPGroup`, `InputOTPSeparator`, `InputOTPSlot` | `@devalok/shilp-sutra/ui/input-otp` **MANDATORY per-component (0.40.0+)** — pulls `input-otp` |
+| `EmojiPicker`, `EmojiPickerPopover`, `EmojiData`, `EmojiSet` | `@devalok/shilp-sutra/composed/emoji-picker` **MANDATORY per-component (0.40.0+)** — pulls `@emoji-mart/data` + `@emoji-mart/react` |
+| `EmojiNode`, `EmojiNodeAttrs`                  | `@devalok/shilp-sutra/composed/extensions/emoji-node` **MANDATORY per-component (0.40.0+)** — pulls `@tiptap/*` |
+| `createEmojiSuggestion`                        | `@devalok/shilp-sutra/composed/extensions/emoji-suggestion` **MANDATORY per-component (0.40.0+)** — pulls `@tiptap/*` |
+| `FilePreview`, `FilePreviewProps`              | `@devalok/shilp-sutra/composed/file-preview` **MANDATORY per-component (0.40.0+)** — pulls `react-pdf` + `react-zoom-pan-pinch` |
+| `MarkdownViewer`                               | `@devalok/shilp-sutra/composed/markdown-viewer` **MANDATORY per-component (0.40.0+)** — pulls `react-markdown` + `react-syntax-highlighter` + `remark-gfm` |
+| `RichChatInput`, `AudioPlayer`, `AudioWaveform`, `useVoiceRecorder` | `@devalok/shilp-sutra/composed/rich-chat-input` **MANDATORY per-component (0.40.0+)** — pulls `@tiptap/*` |
+| `RichTextEditor`, `RichTextViewer`, `MentionItem`, `ToolbarItem` | `@devalok/shilp-sutra/composed/rich-text-editor` **MANDATORY per-component (0.40.0+)** — pulls `@tiptap/*` |
+| `MessageList`, `Message`, `SystemMessage`, `MessageInput`, `DateSeparator`, `UnreadSeparator`, `TypingIndicator` | `@devalok/shilp-sutra/ui/chat` |
+| `CommandBar`                                   | `@devalok/shilp-sutra/ai/command-bar`     (also re-exported from `/ai`) |
+| `AIConversation`                               | `@devalok/shilp-sutra/ai/conversation`                         |
+| `BlockRenderer`                                | `@devalok/shilp-sutra/ai/block-renderer` **MANDATORY per-component (0.40.0+)** — transitively pulls `react-markdown` + `remark-gfm` via ErrorBlock/TextBlock |
+| `AICommandProvider`                            | `@devalok/shilp-sutra/ai/ai-command-provider`                  |
+| `DevadootIcon`                                 | `@devalok/shilp-sutra/ai`                                      |
+| `ErrorBlock`                                   | `@devalok/shilp-sutra/ai/blocks/error` **MANDATORY per-component (0.40.0+)** — pulls `react-markdown` + `remark-gfm` |
+| `TextBlock`                                    | `@devalok/shilp-sutra/ai/blocks/text` **MANDATORY per-component (0.40.0+)** — pulls `react-markdown` + `remark-gfm` |
+| `BlockTable`, `ConfirmBlock`, `DividerBlock`, `InfoBlock`, `LoadingBlock`, `StatRowBlock`, `SuccessBlock` | `@devalok/shilp-sutra/ai/blocks` (barrel — these 7 are peer-cliff-free) |
+| `useColorMode`                                 | `@devalok/shilp-sutra/hooks/use-color-mode`                    |
+| `useMobile`                                    | `@devalok/shilp-sutra/hooks/use-mobile`                        |
+| `MotionProvider`, `springs`, `tweens`, `stagger`, `useMotion` | `@devalok/shilp-sutra/motion`                  |
+| `MotionFade`, `MotionScale`, `MotionPop`, `MotionSlide`, `MotionCollapse`, `MotionStagger`, `MotionStaggerItem` | `@devalok/shilp-sutra/motion/primitives` |
+
+Components named directly after their file (`Button` → `ui/button`, `Card` → `ui/card`, `Avatar` → `ui/avatar`, `Stack` → `ui/stack`, `Text` → `ui/text`, etc.) follow the kebab-case-of-name rule. The table above is for the ones that DON'T.
+
+**When in doubt:** `cat node_modules/@devalok/shilp-sutra/package.json | jq '.exports | keys'` lists every available subpath in the installed version.
+
+## ICON API — one shape across every component (v0.40.0+)
+
+Every icon-accepting prop in the design system (`startIcon`, `endIcon`, `icon`, etc. — see list below) takes the **`IconInput`** type. Pass any of these four shapes interchangeably:
+
+```tsx
+import { IconPlus } from '@tabler/icons-react'
+import { Icon } from '@devalok/shilp-sutra/ui/icon'
+
+<Button startIcon={<Icon icon={IconPlus} />}>Add</Button>   // canonical
+<Button startIcon={<IconPlus />}>Add</Button>                // raw Tabler element
+<Button startIcon={IconPlus}>Add</Button>                    // component ref
+<Button startIcon={<span>+</span>}>Add</Button>              // custom node
+```
+
+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.
+
+**When to use which shape:**
+- `<Icon icon={IconX} />` when you want explicit size/stroke control (size flows from context if not set)
+- `<IconX />` when you trust the surrounding `IconProvider` and don't need stroke control
+- `IconX` (raw ref) when you want the helper to do the wrapping for you (auto-wraps to `<Icon icon={IconX} />`)
+- Custom node when the "icon" is actually `<span>$</span>` or an emoji
+
+**Migration:** zero consumer changes needed if you were already passing valid React content. Components that previously took strict `IconProps['icon']` (BulkActionBar, Message.Action) or `ComponentType<{className}>` (SegmentedControl) now also accept the other three shapes. Strict-to-loose type widening — no breaking calls.
+
 ## CRITICAL: Differences from shadcn/ui
 
 If you have shadcn/ui knowledge, these are the differences that WILL trip you up:
@@ -480,7 +587,7 @@ Components with two-axis system: Button, Badge, Alert, Banner, Progress, StatusB
 
 ### Inputs & Controls
 - Button: variant(solid|soft|outline|ghost|link) color(accent|error|success|warning|neutral) size(xs|sm|md|lg|compact-xs|compact-sm|compact-md|icon-xs|icon-sm|icon-md|icon-lg) shape(default|pill) weight(semibold|normal) + loading, startIcon, endIcon, asChild, processing?('ambient'|'working'|'urgent'|boolean — marching ants SVG border, forces soft variant), processingColor?('accent'|'error'|'success'|'warning'|'neutral'), processingDisabled?(boolean, default true — set false for cancel-by-click). onClickAsync auto-activates processing='working' during loading phase. Layout animation always on. Deprecated aliases still work: variant="default"→solid, variant="destructive"→solid+error, color="default"→accent
-- IconButton: icon(ReactNode, required) shape(square|circle) size(sm|md|lg) + aria-label required
+- IconButton: icon(ReactNode, required as PROP — NOT children) shape(square|circle) size(sm|md|lg) + aria-label required. **Children rejected by type** (`Omit<ButtonProps, 'children'>`); pass the icon via `icon=` prop. Correct: `<IconButton icon={<Icon icon={IconArrowRight} />} aria-label="Submit" />`. Wrong: `<IconButton><Icon icon={IconArrowRight} /></IconButton>` (TS error). Wrap with `<Icon icon={…} />` (not raw Tabler `<IconX />`) so the size context cascades.
 - SplitButton: [Action | ▼] button with dropdown. Props: variant(solid|soft|outline), color, size(xs|sm|md|icon-xs|icon-sm|icon-md), triggerSide(left|right, default right), triggerWidth?(number|string), placement?(Floating UI Placement, default top-end), dropdownContent(ReactNode), open?, onOpenChange?, dropdownLabel?, dropdownIcon?. ARIA: role="group", aria-haspopup="menu", aria-expanded.
 - ButtonGroup: Visually merges adjacent Buttons. Props: variant, color, size, disabled (propagates), orientation(horizontal|vertical), attached(true|false, default true), fullWidth. Compound pattern: Button reads position from context, applies radius + border-removal inline. Tonal dividers for solid/soft/ghost. Focus z-index isolation.
 - Icon: `<Icon icon={IconPlus} />` — context-aware wrapper for Tabler icons. Size tiers: xs(14px) sm(16px) md(18px) lg(20px) xl(24px) 2xl(32px). Default: md. Stroke: light(1.5) regular(2) bold(2.5). Default: regular. Scales per size tier. Reads size from parent Button/IconGroup via IconContext. Explicit props override. Accessibility: aria-hidden by default. Pass label="Add item" for accessible icons. Animation: animate="spin|pulse|bounce|draw". `draw` renders SVG path-draw animation (check/X icons draw progressively via pathLength; other icons fall back to static). State machine: state="idle|loading|success|error". Button integration: startIcon={<Icon icon={IconPlus} />} (NOT raw <IconPlus />). IconGroup: <IconGroup size="sm" gap="tight"> for toolbar patterns.
@@ -638,7 +745,7 @@ Import: `@devalok/shilp-sutra/ui/chat`
 - Old Fade/Collapse/Grow/Slide from @devalok/shilp-sutra/ui/transitions are REMOVED — use Motion* equivalents
 
 ### Hooks
-- toast: imperative API — import { toast } from '@devalok/shilp-sutra/ui/toast'. Methods: toast.success/error/warning/info/loading/message/undo/promise/upload/custom/dismiss. useToast() is deprecated.
+- toast: imperative API — import { toast } from '@devalok/shilp-sutra/ui/toast'. **Signature is `(message: string, options?: { description?, duration?, action?, … })`** (sonner-style positional, NOT object-first). Examples: `toast.success('Saved')`, `toast.error('Failed to fetch', { description: 'Check your network', duration: 7000 })`, `toast.promise(fn, { loading: '…', success: '…', error: '…' })`, `toast.upload(file, { onProgress, onComplete })`. Methods: toast.success/error/warning/info/loading/message/undo/promise/upload/custom/dismiss. useToast() is deprecated. Mount `<Toaster />` at layout root or `toast()` calls are no-ops + log a dev warning.
 - useColorMode(): returns { colorMode, setColorMode, toggleColorMode }
 - useMobile(): returns boolean (true if viewport < 768px)
 - useLink(): returns router-agnostic Link component from LinkProvider context (shell/link-context)

package/skill/references/customize-brand.md

@@ -4,6 +4,21 @@
 
 Override colors, radius, fonts, and spacing without forking the package. All customization happens through CSS custom properties — no JS configuration.
 
+## The fast path: use the Themer
+
+Before hand-writing variables, try **[shilp-sutra.devalok.in/themer](https://shilp-sutra.devalok.in/themer)**. It is one funnel with four entry doors:
+
+- **Pick an archetype** — Linear, Stripe, Apple, Material, Notion, Vercel, or Devalok. Click → result page.
+- **Use my brand color** — paste a hex or dial OKLCH. Auto-generates the 12-step ramp and suggests an archetype.
+- **Walk me through it** — five-question wizard composes the answers into a theme.
+- **Just exploring** — land on a sample result page to see what you ship away with.
+
+Every door drops you at the same result screen: a copy-pasteable CSS block (role tokens + 12-step OKLCH accent ramp), install commands for your package manager, and a share URL that encodes the theme.
+
+Paste the snippet into your global stylesheet *after* the `@import "@devalok/shilp-sutra/css";` line. That's the whole flow — no `tailwind.config.ts`, no theme provider, no JS bundle.
+
+The rest of this doc covers what to do if the Themer doesn't expose a token you need to override (font stack, spacing scale, focus ring) — fall through to the hand-written cases below.
+
 ## How tokens layer
 
 Shilp Sutra's tokens are organized in three tiers: