@devalok/shilp-sutra 0.46.0 → 0.47.0

package/AGENTS.md

@@ -20,12 +20,24 @@ If you are a human, read [README.md](./README.md) instead.
 
 ## How to get details, in priority order
 
-1. **shilp-sutra MCP** (if connected) — version-exact answers as JSON, cheapest on context: `find_component(query)`, `get_component(name, sections?)`, `get_tokens(category)`, `get_setup(framework)`, `upgrade(from, to)`, `search_docs(query)`. Always pass the consumer's installed version (from `node_modules/@devalok/shilp-sutra/package.json`) as `version`.
+1. **shilp-sutra MCP** — version-exact answers as JSON, cheapest on context. Hosted at `https://shilp-sutra.devalok.in/mcp` (connect it if it isn't already; it beats reading the frozen docs in `node_modules`). Reference tools: `find_component(query)`, `get_component(name, sections?)`, `get_tokens(category)`, `get_setup(framework)`, `upgrade(from, to)`, `search_docs(query)`. Setup tools: `detect_framework(packageJson)`, `preflight(framework, imports)`, `validate_snippet(code)`, `verify_setup(...)`, `report_issue(...)`. Always pass the consumer's installed version (from `node_modules/@devalok/shilp-sutra/package.json`) as `version`.
 2. **`packages/core/llms.txt`** — the ~3K-token router: what exists + where to get detail. Load this by default; it is deliberately tiny.
 3. **`packages/core/docs/components/<tier>/<name>.md`** — single-component doc (~3K tokens: props, examples, composability, gotchas). Read ONLY the components you're using — never bulk-read the directory or concatenate these.
 4. **`packages/core/mcp-manifest.json`** — everything machine-readable (props, tokens, composition; react-docgen shape). Prefer targeted reads over prose when you need structured data without the MCP.
 5. **`packages/core/docs/recipes/<framework>.md`** — copy-paste install + setup for the user's framework.
 6. **`packages/core/docs/recipes/upgrading.md`** + **`MIGRATION.md`** — read BOTH before any version bump. See the hard constraint below.
+
+### Setting up in a new project (do this in order)
+
+If the MCP is connected, run the setup sequence instead of guessing — it closes the four traps that break agent-driven installs (peer-dep cliffs, silent TW4 dead classes, wrong recipe, mis-wired CSS/config):
+
+1. `detect_framework(packageJson)` → the right recipe id + package manager (don't assume App Router, or that `create-remix` still makes Remix).
+2. `get_setup(recipe)` → the full, version-live recipe. Follow every step.
+3. `preflight(framework, imports)` → the exact install for the OPTIONAL peer deps your imports need. Run BEFORE first import or the build fails with `Failed to resolve import`.
+4. `validate_snippet(code)` → run on each file BEFORE writing it. Catches bare `shadow`, `-surface-N`, `bg-gradient-to-*`, removed Button variants, invalid enum props — the dead classes fail silently (no error, no style).
+5. `verify_setup(globalsCss, nextConfig, imports, installedDeps)` → confirm CSS imports + order, `transpilePackages`, and peer coverage after wiring.
+
+Without the MCP, the same information is in `docs/recipes/` (per-framework §2a lists optional peers) and the `@devalok/eslint-plugin-shilp-sutra` plugin catches the dead classes at lint time.
 7. **`node_modules/@devalok/shilp-sutra/BREAKING.json`** — machine-readable manifest of every breaking change per version (moves, type narrowings, removals, renames). Read this programmatically when planning an upgrade — schema in `BREAKING.schema.json`. Lets you answer "does my code import any of these moved symbols?" without parsing CHANGELOG prose.
 
 (`llms-full.txt` and `llms-quick.txt` were removed in 0.45 — the router + per-component docs + manifest replaced them. Do not look for them.)

package/MIGRATION.md

@@ -4,6 +4,16 @@ This page indexes all breaking changes across `@devalok/shilp-sutra` versions. F
 
 > **Upgrading from < 0.36?** Start here, then read each intermediate version section. Breaking changes stack — skipping versions means stacking migrations.
 
+## v0.47.0 — MCP setup-journey tools + manifest `peers` (additive)
+
+**Nothing breaks. No migration required.** Everything in 0.47.0 is additive.
+
+- **`mcp-manifest.json` gains a `peers` field** — components that import optional peer dependencies (data-table, charts, date-picker, rich-text-editor, input-otp, file-preview, markdown-viewer) now list them in a structured `peers: [...]` array. Purely additive to the manifest; existing readers ignore unknown fields. Manifest format version bumped 1.0.0 → 1.1.0.
+- **Hosted MCP gains four setup tools** — `preflight`, `validate_snippet`, `detect_framework`, `verify_setup`. Nothing to install; they run on the hosted server. If your AI agent connects the MCP, it can now resolve peer installs, lint snippets for TW4 dead classes before writing, detect the right recipe, and verify wiring.
+- **AGENTS.md** adds a "Setting up in a new project" sequence and the hosted MCP URL.
+- **TanStack Start install recipe rewritten** for the current `@tanstack/react-start` Vite-plugin setup (the old recipe targeted the retired Vinxi `@tanstack/start`). If you set up TanStack Start against the old recipe, re-check against `docs/recipes/install-tanstack-start.md`.
+- **npm `homepage`** now points at the marketing site instead of Storybook.
+
 ## v0.46.0 — Manrope display font, design system owns heading typography
 
 Nothing breaks at the TypeScript level. One visual behavior change to check after upgrade.

package/docs/recipes/install-tanstack-start.md

@@ -1,20 +1,29 @@
 # Install: TanStack Start
 
-> Setup recipe for adding `@devalok/shilp-sutra` to a TanStack Start project (the React full-stack framework built on Vinxi/Vite).
+> Setup recipe for adding `@devalok/shilp-sutra` to a TanStack Start project (the React full-stack framework built on Vite).
+
+> **Updated 2026-07-10 for the Vite-plugin era.** TanStack Start moved off Vinxi: the package is now `@tanstack/react-start` (not `@tanstack/start`), config lives in `vite.config.ts` (not `app.config.ts`), and the app root is `src/` (not `app/`). If you are on an old Vinxi-based project (`app.config.ts`, `@tanstack/start`), migrate to the Vite plugin first — see the TanStack Start docs.
 
 ## 1. Detect
 
 You are in this recipe if:
 
-- `package.json` lists `"@tanstack/start"` and `"@tanstack/react-router"`
-- `app.config.{ts,js}` (Vinxi) exists at the project root
-- `app/router.tsx` and `app/routes/__root.tsx` exist
+- `package.json` lists `"@tanstack/react-start"` and `"@tanstack/react-router"`
+- `vite.config.{ts,js}` exists and uses the `tanstackStart` plugin from `@tanstack/react-start/plugin/vite`
+- `src/router.tsx` and `src/routes/__root.tsx` exist (a `src/routeTree.gen.ts` is generated on first run)
+
+If instead you see `app.config.ts` + `@tanstack/start`, that is the legacy Vinxi setup — this recipe does not apply until you migrate.
 
 ## 2. Install
 
 ```bash
+# pnpm
 pnpm add @devalok/shilp-sutra framer-motion
 pnpm add -D tailwindcss@^4 @tailwindcss/vite
+
+# npm
+npm install @devalok/shilp-sutra framer-motion
+npm install -D tailwindcss@^4 @tailwindcss/vite
 ```
 
 Optional:
@@ -38,39 +47,79 @@ Some components ship hard peers as optional. **Install BEFORE first import** or
 | `@devalok/shilp-sutra/composed/markdown-viewer`            | `pnpm add react-markdown react-syntax-highlighter`                                                      |
 | Any `Icon` / `IconButton` with Tabler icons                | `pnpm add @tabler/icons-react`                                                                          |
 
-## 3. Wire Tailwind 4 in `app.config.ts`
+## 3. Wire Tailwind 4 in `vite.config.ts`
+
+Add `@tailwindcss/vite` to the existing plugins array. `tanstackStart()` must come before `viteReact()`; `tailwindcss()` can go first so tokens are processed early.
 
 ```ts
-import { defineConfig } from "@tanstack/start/config";
+import { defineConfig } from "vite";
+import { tanstackStart } from "@tanstack/react-start/plugin/vite";
+import viteReact from "@vitejs/plugin-react";
 import tailwindcss from "@tailwindcss/vite";
 
 export default defineConfig({
-  vite: {
-    plugins: [tailwindcss()],
-  },
+  plugins: [
+    tailwindcss(),
+    tanstackStart(),
+    viteReact(),
+  ],
 });
 ```
 
+Do **not** add a `tailwind.config.{ts,js}` — Tailwind 4 is CSS-first.
+
 ## 4. Wire tokens
 
-Create `app/styles/globals.css`:
+Create `src/styles/globals.css`:
 
 ```css
 @import "tailwindcss";
 @import "@devalok/shilp-sutra/css";
 ```
 
-Import it from `app/routes/__root.tsx`:
+Wire it as an asset-URL stylesheet from the root route's `head` (the TanStack Start idiom — the `?url` suffix emits the file as an asset instead of inlining it):
 
 ```tsx
-import "../styles/globals.css";
-```
+// src/routes/__root.tsx
+import {
+  createRootRoute,
+  HeadContent,
+  Outlet,
+  Scripts,
+} from "@tanstack/react-router";
+import globalsCss from "../styles/globals.css?url";
 
-If you prefer asset-URL imports the way Remix does it, use `import css from "../styles/globals.css?url"` and add `<link rel="stylesheet" href={css} />` to the `<head>` returned by `__root.tsx`.
+export const Route = createRootRoute({
+  head: () => ({
+    meta: [
+      { charSet: "utf-8" },
+      { name: "viewport", content: "width=device-width, initial-scale=1" },
+    ],
+    links: [{ rel: "stylesheet", href: globalsCss }],
+  }),
+  component: RootComponent,
+});
+
+function RootComponent() {
+  return (
+    <html lang="en" suppressHydrationWarning>
+      <head>
+        <HeadContent />
+      </head>
+      <body>
+        <Outlet />
+        <Scripts />
+      </body>
+    </html>
+  );
+}
+```
 
 ## 5. Theme toggle
 
-Create `public/theme-bootstrap.js` (a static asset served verbatim):
+Add a pre-hydration bootstrap so there is no flash of the wrong theme. The cleanest place is a `scripts` entry on the root route (runs before hydration); a static `public/theme-bootstrap.js` referenced from `<head>` also works and is CSP-friendly.
+
+Static-asset approach — create `public/theme-bootstrap.js`:
 
 ```js
 (function () {
@@ -84,44 +133,36 @@ Create `public/theme-bootstrap.js` (a static asset served verbatim):
 })();
 ```
 
-Reference it from `app/routes/__root.tsx`:
+Reference it from the root route's `head` scripts:
 
 ```tsx
-import { createRootRoute, Outlet } from "@tanstack/react-router";
-
 export const Route = createRootRoute({
-  component: () => (
-    <html lang="en" suppressHydrationWarning>
-      <head>
-        <script src="/theme-bootstrap.js" />
-      </head>
-      <body>
-        <Outlet />
-      </body>
-    </html>
-  ),
+  head: () => ({
+    // ...meta, links as above...
+    scripts: [{ src: "/theme-bootstrap.js" }],
+  }),
+  component: RootComponent,
 });
 ```
 
-For runtime toggling, use the `useColorMode` hook — see [install-vite.md § 5](./install-vite.md#5-theme-toggle-no-next-themes-here).
+For runtime toggling inside components, use the `useColorMode` hook — see [install-vite.md § 5](./install-vite.md#5-theme-toggle-no-next-themes-here).
 
 ## 6. Toaster (optional)
 
-Mount in `__root.tsx` next to `<Outlet />`:
+Mount once in `__root.tsx`'s `RootComponent`, next to `<Outlet />`:
 
 ```tsx
 import { Toaster } from "@devalok/shilp-sutra/ui/toaster";
 
 // inside <body>
-<>
-  <Outlet />
-  <Toaster />
-</>
+<Outlet />
+<Toaster />
+<Scripts />
 ```
 
 ## 7. Verify
 
-Create or replace `app/routes/index.tsx`:
+Create or replace `src/routes/index.tsx`:
 
 ```tsx
 import { createFileRoute } from "@tanstack/react-router";
@@ -130,7 +171,11 @@ import { Stack } from "@devalok/shilp-sutra/ui/stack";
 import { Text } from "@devalok/shilp-sutra/ui/text";
 
 export const Route = createFileRoute("/")({
-  component: () => (
+  component: Home,
+});
+
+function Home() {
+  return (
     <Stack className="p-ds-08" gap="ds-04">
       <Text variant="heading-2xl">Hello, Shilp Sutra</Text>
       <Stack direction="row" gap="ds-03">
@@ -138,21 +183,23 @@ export const Route = createFileRoute("/")({
         <Button variant="soft">Soft</Button>
       </Stack>
     </Stack>
-  ),
-});
+  );
+}
 ```
 
-Run `pnpm dev` and open the URL.
+Run `pnpm dev` and open the printed URL. Expected output matches [Next App Router § 7](./install-next-app-router.md#7-verify-the-install).
 
 ## 8. TanStack Start specifics
 
+- **No `transpilePackages` equivalent — and you do not need one.** TanStack Start's Vite resolves `@devalok/shilp-sutra` from `node_modules` as native ESM.
 - **Server functions** (`createServerFn`) — do not import shilp-sutra components inside server functions; they run server-only.
-- **Streaming SSR** is the default. All shilp-sutra components SSR cleanly because they have no client-only side effects at module top-level.
+- **Streaming SSR** is the default. Shilp Sutra components SSR cleanly (no client-only side effects at module top-level).
 - **`framer-motion` SSR** — animations gracefully degrade on the initial render.
-- **CSP.** The static `theme-bootstrap.js` asset complies with strict CSP (no inline scripts required).
+- **`routeTree.gen.ts` is generated** — do not edit it by hand; it regenerates on dev/build.
 
 ## 9. What NOT to do
 
-- ❌ Add `tailwind.config.{ts,js}` — Tailwind 4 is CSS-first.
-- ❌ Mount `<Toaster />` inside route components — it should live once at the `__root`.
-- ❌ Mix `@tailwindcss/postcss` and `@tailwindcss/vite` — pick one (Vite plugin recommended for TanStack Start).
+- ❌ Add a `tailwind.config.{ts,js}` — Tailwind 4 is CSS-first.
+- ❌ Use `@tanstack/start` / `app.config.ts` / `@tanstack/start/config` — that is the retired Vinxi setup. Current TanStack Start is `@tanstack/react-start` + `vite.config.ts`.
+- ❌ Mount `<Toaster />` inside route components — it lives once at the `__root`.
+- ❌ Mix `@tailwindcss/postcss` and `@tailwindcss/vite` — pick the Vite plugin.

package/llms.txt

@@ -1,6 +1,6 @@
 # @devalok/shilp-sutra
 
-> Radix UI + Tailwind 4 (CSS-first) + CVA design system for Devalok apps, v0.46.0.
+> Radix UI + Tailwind 4 (CSS-first) + CVA design system for Devalok apps, v0.47.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/mcp-manifest.json

@@ -1,8 +1,8 @@
 {
   "$schema": "./mcp-manifest.schema.json",
-  "manifestVersion": "1.0.0",
+  "manifestVersion": "1.1.0",
   "package": "@devalok/shilp-sutra",
-  "packageVersion": "0.46.0",
+  "packageVersion": "0.47.0",
   "components": {
     "accordion": {
       "displayName": "Accordion",
@@ -1780,6 +1780,17 @@
           "version": "0.1.0",
           "summary": "**Added** Initial release"
         }
+      ],
+      "peers": [
+        "d3-array",
+        "d3-axis",
+        "d3-format",
+        "d3-interpolate",
+        "d3-scale",
+        "d3-selection",
+        "d3-shape",
+        "d3-time-format",
+        "d3-transition"
       ]
     },
     "chat": {
@@ -2787,6 +2798,10 @@
           "version": "0.1.0",
           "summary": "**Added** Initial release"
         }
+      ],
+      "peers": [
+        "@tanstack/react-table",
+        "@tanstack/react-virtual"
       ]
     },
     "data-table-body": {
@@ -3001,6 +3016,10 @@
           "version": "0.1.0",
           "summary": "**Added** Initial release"
         }
+      ],
+      "peers": [
+        "@tanstack/react-table",
+        "@tanstack/react-virtual"
       ]
     },
     "devalok-grain": {
@@ -4038,6 +4057,9 @@
           "version": "0.1.0",
           "summary": "**Added** Initial release"
         }
+      ],
+      "peers": [
+        "input-otp"
       ]
     },
     "label": {
@@ -8587,6 +8609,9 @@
           "version": "0.1.0",
           "summary": "**Added** Initial release"
         }
+      ],
+      "peers": [
+        "date-fns"
       ]
     },
     "deadline-indicator": {
@@ -9037,6 +9062,10 @@
         "All types have error fallback with download link",
         "Embed URLs auto-converted to embed format",
         "Audio player doesn't show separate Download button (integrated in card)"
+      ],
+      "peers": [
+        "react-pdf",
+        "react-zoom-pan-pinch"
       ]
     },
     "filter-bar": {
@@ -9487,6 +9516,10 @@
         "GFM (tables, strikethrough, task lists) is supported via `remark-gfm`",
         "Raw HTML is stripped by default — only enable `allowHtml` for trusted content",
         "Links open in a new tab by default (`target=\"_blank\"` with `rel=\"noopener noreferrer\"`)"
+      ],
+      "peers": [
+        "react-markdown",
+        "react-syntax-highlighter"
       ]
     },
     "master-detail": {
@@ -10192,6 +10225,11 @@
           "version": "0.32.0",
           "summary": "Initial release"
         }
+      ],
+      "peers": [
+        "@tiptap/react",
+        "@tiptap/starter-kit",
+        "@tiptap/extension-placeholder"
       ]
     },
     "rich-text-editor": {
@@ -10333,6 +10371,11 @@
           "version": "0.1.1",
           "summary": "**Fixed** Added content sync effect so editor updates when `content` prop changes externally"
         }
+      ],
+      "peers": [
+        "@tiptap/react",
+        "@tiptap/starter-kit",
+        "@tiptap/extension-placeholder"
       ]
     },
     "schedule-view": {

package/mcp-manifest.schema.json

@@ -81,6 +81,12 @@
           "items": { "type": "string" },
           "description": "Known-misuse bullets, verbatim, DO-NOT phrasing preferred."
         },
+        "peers": {
+          "type": "array",
+          "items": { "type": "string" },
+          "description": "Optional peer dependencies this component imports. Absent for core components (no extra install). Importing the component without these installed fails the build with 'Failed to resolve import'. Mirrors the recipe optional-peer table; read by the MCP preflight/verify_setup tools.",
+          "examples": [["@tanstack/react-table", "@tanstack/react-virtual"]]
+        },
         "changes": {
           "type": "array",
           "items": {

package/package.json

@@ -1,10 +1,10 @@
 {
   "name": "@devalok/shilp-sutra",
-  "version": "0.46.0",
+  "version": "0.47.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>",
-  "homepage": "https://devalok-design.github.io/shilp-sutra/",
+  "homepage": "https://shilp-sutra.devalok.in",
   "repository": {
     "type": "git",
     "url": "https://github.com/devalok-design/shilp-sutra",

package/scripts/welcome.mjs

@@ -173,7 +173,7 @@ function buildFullBanner(version, prevVersion) {
     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(row(`      ${colour('Tailwind 4 design system · 120+ components · RSC-safe', DIM)}`))
   }
   lines.push(colour(EMPTY, PINK_DIM))
   lines.push(row(`   ${colour('▸', PINK)} Setup recipe (pick your framework):`))
@@ -183,7 +183,9 @@ 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('cp -r node_modules/@devalok/shilp-sutra/skill \\', DIM)}`))
+  lines.push(row(`     ${colour('connect the live docs MCP → https://shilp-sutra.devalok.in/mcp', 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)}`))
   lines.push(colour(EMPTY, PINK_DIM))
   lines.push(row(`   ${colour('Disable this banner: SHILP_SUTRA_NO_WELCOME=1', DIM)}`))

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.46.0"
+  version: "0.47.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.46.0.
+> Radix UI + Tailwind 4 (CSS-first) + CVA design system for Devalok apps, v0.47.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/setup-tanstack-start.md

@@ -2,21 +2,30 @@
 
 # Install: TanStack Start
 
-> Setup recipe for adding `@devalok/shilp-sutra` to a TanStack Start project (the React full-stack framework built on Vinxi/Vite).
+> Setup recipe for adding `@devalok/shilp-sutra` to a TanStack Start project (the React full-stack framework built on Vite).
+
+> **Updated 2026-07-10 for the Vite-plugin era.** TanStack Start moved off Vinxi: the package is now `@tanstack/react-start` (not `@tanstack/start`), config lives in `vite.config.ts` (not `app.config.ts`), and the app root is `src/` (not `app/`). If you are on an old Vinxi-based project (`app.config.ts`, `@tanstack/start`), migrate to the Vite plugin first — see the TanStack Start docs.
 
 ## 1. Detect
 
 You are in this recipe if:
 
-- `package.json` lists `"@tanstack/start"` and `"@tanstack/react-router"`
-- `app.config.{ts,js}` (Vinxi) exists at the project root
-- `app/router.tsx` and `app/routes/__root.tsx` exist
+- `package.json` lists `"@tanstack/react-start"` and `"@tanstack/react-router"`
+- `vite.config.{ts,js}` exists and uses the `tanstackStart` plugin from `@tanstack/react-start/plugin/vite`
+- `src/router.tsx` and `src/routes/__root.tsx` exist (a `src/routeTree.gen.ts` is generated on first run)
+
+If instead you see `app.config.ts` + `@tanstack/start`, that is the legacy Vinxi setup — this recipe does not apply until you migrate.
 
 ## 2. Install
 
 ```bash
+# pnpm
 pnpm add @devalok/shilp-sutra framer-motion
 pnpm add -D tailwindcss@^4 @tailwindcss/vite
+
+# npm
+npm install @devalok/shilp-sutra framer-motion
+npm install -D tailwindcss@^4 @tailwindcss/vite
 ```
 
 Optional:
@@ -40,39 +49,79 @@ Some components ship hard peers as optional. **Install BEFORE first import** or
 | `@devalok/shilp-sutra/composed/markdown-viewer`            | `pnpm add react-markdown react-syntax-highlighter`                                                      |
 | Any `Icon` / `IconButton` with Tabler icons                | `pnpm add @tabler/icons-react`                                                                          |
 
-## 3. Wire Tailwind 4 in `app.config.ts`
+## 3. Wire Tailwind 4 in `vite.config.ts`
+
+Add `@tailwindcss/vite` to the existing plugins array. `tanstackStart()` must come before `viteReact()`; `tailwindcss()` can go first so tokens are processed early.
 
 ```ts
-import { defineConfig } from "@tanstack/start/config";
+import { defineConfig } from "vite";
+import { tanstackStart } from "@tanstack/react-start/plugin/vite";
+import viteReact from "@vitejs/plugin-react";
 import tailwindcss from "@tailwindcss/vite";
 
 export default defineConfig({
-  vite: {
-    plugins: [tailwindcss()],
-  },
+  plugins: [
+    tailwindcss(),
+    tanstackStart(),
+    viteReact(),
+  ],
 });
 ```
 
+Do **not** add a `tailwind.config.{ts,js}` — Tailwind 4 is CSS-first.
+
 ## 4. Wire tokens
 
-Create `app/styles/globals.css`:
+Create `src/styles/globals.css`:
 
 ```css
 @import "tailwindcss";
 @import "@devalok/shilp-sutra/css";
 ```
 
-Import it from `app/routes/__root.tsx`:
+Wire it as an asset-URL stylesheet from the root route's `head` (the TanStack Start idiom — the `?url` suffix emits the file as an asset instead of inlining it):
 
 ```tsx
-import "../styles/globals.css";
-```
+// src/routes/__root.tsx
+import {
+  createRootRoute,
+  HeadContent,
+  Outlet,
+  Scripts,
+} from "@tanstack/react-router";
+import globalsCss from "../styles/globals.css?url";
 
-If you prefer asset-URL imports the way Remix does it, use `import css from "../styles/globals.css?url"` and add `<link rel="stylesheet" href={css} />` to the `<head>` returned by `__root.tsx`.
+export const Route = createRootRoute({
+  head: () => ({
+    meta: [
+      { charSet: "utf-8" },
+      { name: "viewport", content: "width=device-width, initial-scale=1" },
+    ],
+    links: [{ rel: "stylesheet", href: globalsCss }],
+  }),
+  component: RootComponent,
+});
+
+function RootComponent() {
+  return (
+    <html lang="en" suppressHydrationWarning>
+      <head>
+        <HeadContent />
+      </head>
+      <body>
+        <Outlet />
+        <Scripts />
+      </body>
+    </html>
+  );
+}
+```
 
 ## 5. Theme toggle
 
-Create `public/theme-bootstrap.js` (a static asset served verbatim):
+Add a pre-hydration bootstrap so there is no flash of the wrong theme. The cleanest place is a `scripts` entry on the root route (runs before hydration); a static `public/theme-bootstrap.js` referenced from `<head>` also works and is CSP-friendly.
+
+Static-asset approach — create `public/theme-bootstrap.js`:
 
 ```js
 (function () {
@@ -86,44 +135,36 @@ Create `public/theme-bootstrap.js` (a static asset served verbatim):
 })();
 ```
 
-Reference it from `app/routes/__root.tsx`:
+Reference it from the root route's `head` scripts:
 
 ```tsx
-import { createRootRoute, Outlet } from "@tanstack/react-router";
-
 export const Route = createRootRoute({
-  component: () => (
-    <html lang="en" suppressHydrationWarning>
-      <head>
-        <script src="/theme-bootstrap.js" />
-      </head>
-      <body>
-        <Outlet />
-      </body>
-    </html>
-  ),
+  head: () => ({
+    // ...meta, links as above...
+    scripts: [{ src: "/theme-bootstrap.js" }],
+  }),
+  component: RootComponent,
 });
 ```
 
-For runtime toggling, use the `useColorMode` hook — see [install-vite.md § 5](./install-vite.md#5-theme-toggle-no-next-themes-here).
+For runtime toggling inside components, use the `useColorMode` hook — see [install-vite.md § 5](./install-vite.md#5-theme-toggle-no-next-themes-here).
 
 ## 6. Toaster (optional)
 
-Mount in `__root.tsx` next to `<Outlet />`:
+Mount once in `__root.tsx`'s `RootComponent`, next to `<Outlet />`:
 
 ```tsx
 import { Toaster } from "@devalok/shilp-sutra/ui/toaster";
 
 // inside <body>
-<>
-  <Outlet />
-  <Toaster />
-</>
+<Outlet />
+<Toaster />
+<Scripts />
 ```
 
 ## 7. Verify
 
-Create or replace `app/routes/index.tsx`:
+Create or replace `src/routes/index.tsx`:
 
 ```tsx
 import { createFileRoute } from "@tanstack/react-router";
@@ -132,7 +173,11 @@ import { Stack } from "@devalok/shilp-sutra/ui/stack";
 import { Text } from "@devalok/shilp-sutra/ui/text";
 
 export const Route = createFileRoute("/")({
-  component: () => (
+  component: Home,
+});
+
+function Home() {
+  return (
     <Stack className="p-ds-08" gap="ds-04">
       <Text variant="heading-2xl">Hello, Shilp Sutra</Text>
       <Stack direction="row" gap="ds-03">
@@ -140,21 +185,23 @@ export const Route = createFileRoute("/")({
         <Button variant="soft">Soft</Button>
       </Stack>
     </Stack>
-  ),
-});
+  );
+}
 ```
 
-Run `pnpm dev` and open the URL.
+Run `pnpm dev` and open the printed URL. Expected output matches [Next App Router § 7](./install-next-app-router.md#7-verify-the-install).
 
 ## 8. TanStack Start specifics
 
+- **No `transpilePackages` equivalent — and you do not need one.** TanStack Start's Vite resolves `@devalok/shilp-sutra` from `node_modules` as native ESM.
 - **Server functions** (`createServerFn`) — do not import shilp-sutra components inside server functions; they run server-only.
-- **Streaming SSR** is the default. All shilp-sutra components SSR cleanly because they have no client-only side effects at module top-level.
+- **Streaming SSR** is the default. Shilp Sutra components SSR cleanly (no client-only side effects at module top-level).
 - **`framer-motion` SSR** — animations gracefully degrade on the initial render.
-- **CSP.** The static `theme-bootstrap.js` asset complies with strict CSP (no inline scripts required).
+- **`routeTree.gen.ts` is generated** — do not edit it by hand; it regenerates on dev/build.
 
 ## 9. What NOT to do
 
-- ❌ Add `tailwind.config.{ts,js}` — Tailwind 4 is CSS-first.
-- ❌ Mount `<Toaster />` inside route components — it should live once at the `__root`.
-- ❌ Mix `@tailwindcss/postcss` and `@tailwindcss/vite` — pick one (Vite plugin recommended for TanStack Start).
+- ❌ Add a `tailwind.config.{ts,js}` — Tailwind 4 is CSS-first.
+- ❌ Use `@tanstack/start` / `app.config.ts` / `@tanstack/start/config` — that is the retired Vinxi setup. Current TanStack Start is `@tanstack/react-start` + `vite.config.ts`.
+- ❌ Mount `<Toaster />` inside route components — it lives once at the `__root`.
+- ❌ Mix `@tailwindcss/postcss` and `@tailwindcss/vite` — pick the Vite plugin.