@devalok/shilp-sutra 0.40.1 → 0.41.0

package/AGENTS.md

@@ -25,6 +25,7 @@ If you are a human, read [README.md](./README.md) instead.
 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. **`packages/core/docs/recipes/upgrading.md`** + **`MIGRATION.md`** — read BOTH before any version bump. See the hard constraint below.
+6. **`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.
 
 When the package is installed in a consumer project, the same files live at:
 
@@ -60,7 +61,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`.
+- **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. **Fastest path: parse `node_modules/@devalok/shilp-sutra/BREAKING.json` for the version range** — it has the structured break data so you can grep your codebase for affected symbols deterministically. Then 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";
@@ -74,6 +75,27 @@ 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.
 
+## Spacing cadence (when building layouts — forms, settings, login, anything with vertical rhythm)
+
+The `--spacing-ds-*` scale runs `ds-01`→`ds-09` (2px→48px) with many adjacent steps. It is a *primitive* scale, not a layout recipe. When you compose a UI, **do not reach for every adjacent token** — that produces 5-6 near-identical gaps the eye can't group, and rhythm reads muddy.
+
+**Pick a 3-tier cadence — each tier visibly ~1.5-2× the previous, so each gap is distinct:**
+
+| Tier | Token (px) | Use for |
+|---|---|---|
+| Related (one unit) | `ds-03` (8) | label ↔ field, eyebrow ↔ title, items inside one micro-cluster |
+| Grouped (a section's items) | `ds-05` (16) | header-stack → form, between stacked field-groups, multi-line footers |
+| Section (independent blocks) | `ds-07` (32) | between page sections, form ↔ footer cluster |
+| Hero (optional 4th) | `ds-08`+ (40+) | top page chrome, brand block → first content |
+
+**Rules of thumb:**
+- Before stamping a `gap-ds-*` / `space-y-ds-*`, decide which tier the spacing is. Use the matching token.
+- Aim for **3-4 distinct spacing values total on one surface.** Using 5+ is the signal your rhythm is muddy.
+- **Anti-pattern:** using `ds-02` (4) AND `ds-04` (12) as *different* relationship signals on the same surface — they collapse into "vaguely tight" instead of two clear tiers. Prefer `ds-03`; skip `ds-02`/`ds-04` unless deliberate (e.g. a chip gap at `ds-01`).
+- The squint test must still reveal the grouping. (Refactoring UI / Apple HIG / Material all converge on 3-4 perceptual tiers; near-linear scales like 4/8/12/16 blur because the proportional jump shrinks as values grow.)
+
+This is guidance, not a hard constraint — a deliberate exception is fine. The default keeps agent-built UIs from drifting into flat, ungrouped spacing.
+
 ## 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.

package/BREAKING.json

@@ -0,0 +1,66 @@
+{
+  "$schema": "./BREAKING.schema.json",
+  "package": "@devalok/shilp-sutra",
+  "versions": {
+    "0.40.0": {
+      "summary": "Barrel peer-cliff cleanup — 12 symbol families removed from /ui, /composed, /ai barrels (per-component subpath only). Icon API unification narrows the `icon` prop on 14 components from React.ReactNode to IconInput.",
+      "migrationDoc": "MIGRATION.md#v0400--barrel-peer-cliff-cleanup--icon-api-unification",
+      "moved": [
+        { "symbol": "Toaster", "from": "@devalok/shilp-sutra/ui", "to": "@devalok/shilp-sutra/ui/toaster", "peer": "sonner", "eslintRule": "prefer-per-component-import" },
+        { "symbol": "toast", "from": "@devalok/shilp-sutra/ui", "to": "@devalok/shilp-sutra/ui/toast", "peer": "sonner", "eslintRule": "prefer-per-component-import" },
+        { "symbol": "InputOTP", "from": "@devalok/shilp-sutra/ui", "to": "@devalok/shilp-sutra/ui/input-otp", "peer": "input-otp", "eslintRule": "prefer-per-component-import" },
+        { "symbol": "DatePicker", "from": "@devalok/shilp-sutra/composed", "to": "@devalok/shilp-sutra/composed/date-picker", "peer": "date-fns", "eslintRule": "prefer-per-component-import" },
+        { "symbol": "DateRangePicker", "from": "@devalok/shilp-sutra/composed", "to": "@devalok/shilp-sutra/composed/date-picker", "peer": "date-fns", "eslintRule": "prefer-per-component-import" },
+        { "symbol": "DateTimePicker", "from": "@devalok/shilp-sutra/composed", "to": "@devalok/shilp-sutra/composed/date-picker", "peer": "date-fns", "eslintRule": "prefer-per-component-import" },
+        { "symbol": "TimePicker", "from": "@devalok/shilp-sutra/composed", "to": "@devalok/shilp-sutra/composed/date-picker", "peer": "date-fns", "eslintRule": "prefer-per-component-import" },
+        { "symbol": "CalendarGrid", "from": "@devalok/shilp-sutra/composed", "to": "@devalok/shilp-sutra/composed/date-picker", "peer": "date-fns", "eslintRule": "prefer-per-component-import" },
+        { "symbol": "MonthPicker", "from": "@devalok/shilp-sutra/composed", "to": "@devalok/shilp-sutra/composed/date-picker", "peer": "date-fns", "eslintRule": "prefer-per-component-import" },
+        { "symbol": "YearPicker", "from": "@devalok/shilp-sutra/composed", "to": "@devalok/shilp-sutra/composed/date-picker", "peer": "date-fns", "eslintRule": "prefer-per-component-import" },
+        { "symbol": "Presets", "from": "@devalok/shilp-sutra/composed", "to": "@devalok/shilp-sutra/composed/date-picker", "peer": "date-fns", "eslintRule": "prefer-per-component-import" },
+        { "symbol": "useCalendar", "from": "@devalok/shilp-sutra/composed", "to": "@devalok/shilp-sutra/composed/date-picker", "peer": "date-fns", "eslintRule": "prefer-per-component-import" },
+        { "symbol": "EmojiPicker", "from": "@devalok/shilp-sutra/composed", "to": "@devalok/shilp-sutra/composed/emoji-picker", "peer": "@emoji-mart/data", "eslintRule": "prefer-per-component-import" },
+        { "symbol": "EmojiPickerPopover", "from": "@devalok/shilp-sutra/composed", "to": "@devalok/shilp-sutra/composed/emoji-picker", "peer": "@emoji-mart/data", "eslintRule": "prefer-per-component-import" },
+        { "symbol": "EmojiNode", "from": "@devalok/shilp-sutra/composed", "to": "@devalok/shilp-sutra/composed/extensions/emoji-node", "peer": "@tiptap/react", "eslintRule": "prefer-per-component-import" },
+        { "symbol": "createEmojiSuggestion", "from": "@devalok/shilp-sutra/composed", "to": "@devalok/shilp-sutra/composed/extensions/emoji-suggestion", "peer": "@tiptap/react", "eslintRule": "prefer-per-component-import" },
+        { "symbol": "FilePreview", "from": "@devalok/shilp-sutra/composed", "to": "@devalok/shilp-sutra/composed/file-preview", "peer": "react-pdf", "eslintRule": "prefer-per-component-import" },
+        { "symbol": "MarkdownViewer", "from": "@devalok/shilp-sutra/composed", "to": "@devalok/shilp-sutra/composed/markdown-viewer", "peer": "react-markdown", "eslintRule": "prefer-per-component-import" },
+        { "symbol": "RichTextEditor", "from": "@devalok/shilp-sutra/composed", "to": "@devalok/shilp-sutra/composed/rich-text-editor", "peer": "@tiptap/react", "eslintRule": "prefer-per-component-import" },
+        { "symbol": "RichTextViewer", "from": "@devalok/shilp-sutra/composed", "to": "@devalok/shilp-sutra/composed/rich-text-editor", "peer": "@tiptap/react", "eslintRule": "prefer-per-component-import" },
+        { "symbol": "RichChatInput", "from": "@devalok/shilp-sutra/composed", "to": "@devalok/shilp-sutra/composed/rich-chat-input", "peer": "@tiptap/react", "eslintRule": "prefer-per-component-import" },
+        { "symbol": "AudioPlayer", "from": "@devalok/shilp-sutra/composed", "to": "@devalok/shilp-sutra/composed/rich-chat-input", "peer": "@tiptap/react", "eslintRule": "prefer-per-component-import" },
+        { "symbol": "AudioWaveform", "from": "@devalok/shilp-sutra/composed", "to": "@devalok/shilp-sutra/composed/rich-chat-input", "peer": "@tiptap/react", "eslintRule": "prefer-per-component-import" },
+        { "symbol": "useVoiceRecorder", "from": "@devalok/shilp-sutra/composed", "to": "@devalok/shilp-sutra/composed/rich-chat-input", "peer": "@tiptap/react", "eslintRule": "prefer-per-component-import" },
+        { "symbol": "BlockRenderer", "from": "@devalok/shilp-sutra/ai", "to": "@devalok/shilp-sutra/ai/block-renderer", "peer": "react-markdown", "eslintRule": "prefer-per-component-import" },
+        { "symbol": "ErrorBlock", "from": "@devalok/shilp-sutra/ai/blocks", "to": "@devalok/shilp-sutra/ai/blocks/error", "peer": "react-markdown", "eslintRule": "prefer-per-component-import" },
+        { "symbol": "TextBlock", "from": "@devalok/shilp-sutra/ai/blocks", "to": "@devalok/shilp-sutra/ai/blocks/text", "peer": "react-markdown", "eslintRule": "prefer-per-component-import" }
+      ],
+      "narrowed": [
+        {
+          "prop": "icon",
+          "components": [
+            "Combobox option",
+            "Stepper step",
+            "TreeItem",
+            "OAuthButton",
+            "AppCommandPalette",
+            "CommandRegistry",
+            "BottomNavbar",
+            "Sidebar NavItem",
+            "Sidebar NavSubItem",
+            "Sidebar footer.promo",
+            "TopBar UserMenuItem",
+            "Chat.Message.Avatar",
+            "Chat.SystemMessage",
+            "AIConversation agent",
+            "ActivityFeed item",
+            "CommandPalette item",
+            "CommandBar item"
+          ],
+          "from": "React.ReactNode",
+          "to": "IconInput",
+          "fix": "Retype the icon source from React.ReactNode to React.ReactElement (or import the IconInput type). Build-time only; runtime JSX is unaffected."
+        }
+      ]
+    }
+  }
+}

package/BREAKING.schema.json

@@ -0,0 +1,184 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://shilp-sutra.devalok.in/breaking-manifest.schema.json",
+  "title": "shilp-sutra BREAKING manifest",
+  "description": "Machine-readable record of breaking changes per published version. Lets AI agents and migration tools answer 'what breaks between X and Y?' programmatically instead of parsing CHANGELOG prose. Cumulative — every prior version's breaks remain so a consumer jumping 0.37 → 0.41 can see every break in range.",
+  "type": "object",
+  "required": ["package", "versions"],
+  "additionalProperties": false,
+  "properties": {
+    "$schema": { "type": "string" },
+    "package": {
+      "type": "string",
+      "description": "npm package name this manifest covers.",
+      "examples": ["@devalok/shilp-sutra"]
+    },
+    "versions": {
+      "type": "object",
+      "description": "Map of semver version → breaking-change record. A version only appears if it had at least one breaking change. Non-breaking releases are absent (an empty object would falsely signal 'this version had breaks I forgot to document').",
+      "patternProperties": {
+        "^\\d+\\.\\d+\\.\\d+$": { "$ref": "#/$defs/versionEntry" }
+      },
+      "additionalProperties": false
+    }
+  },
+  "$defs": {
+    "versionEntry": {
+      "type": "object",
+      "additionalProperties": false,
+      "description": "All breaks shipped in this version. Every present field is an array; omit empty fields entirely. A consumer planning an upgrade reads the union of all entries between current and target version.",
+      "properties": {
+        "summary": {
+          "type": "string",
+          "description": "One-line human summary of the version's breaks. Mirrors the `> ⚠️ Breaking in X.Y.Z` callout in CHANGELOG."
+        },
+        "migrationDoc": {
+          "type": "string",
+          "description": "Relative path inside the package tarball to the human migration guide for this version.",
+          "examples": ["MIGRATION.md#v0400--barrel-peer-cliff-cleanup--icon-api-unification"]
+        },
+        "moved": {
+          "type": "array",
+          "description": "Symbols whose import path changed. Old path no longer exports the symbol; new path does. Consumer fix is a search-and-replace of the import path; prop/type signatures are unchanged.",
+          "items": { "$ref": "#/$defs/move" }
+        },
+        "narrowed": {
+          "type": "array",
+          "description": "Prop types that accept LESS than before. A consumer value valid under the old type may now fail tsc. Not a runtime break. The fix is typically retyping the value's source.",
+          "items": { "$ref": "#/$defs/narrowing" }
+        },
+        "removed": {
+          "type": "array",
+          "description": "Symbols (components, props, variants, exports) deleted with no replacement on the same path. If a renamed-with-deprecation, list under `renamed` instead.",
+          "items": { "$ref": "#/$defs/removal" }
+        },
+        "renamed": {
+          "type": "array",
+          "description": "Symbols whose name changed in place (same import path, new export name) or whose prop name changed (same component, new prop name).",
+          "items": { "$ref": "#/$defs/rename" }
+        },
+        "notes": {
+          "type": "array",
+          "description": "Free-form breaking changes that don't fit the structured categories above (e.g. visual-only changes, DOM structure shifts, default-value flips). Reader must check these manually — the migration is NOT one-shot autofixable.",
+          "items": { "type": "string" }
+        }
+      }
+    },
+    "move": {
+      "type": "object",
+      "required": ["symbol", "from", "to"],
+      "additionalProperties": false,
+      "properties": {
+        "symbol": {
+          "type": "string",
+          "description": "Exported name as it appears in an import statement.",
+          "examples": ["Toaster", "DatePicker"]
+        },
+        "from": {
+          "type": "string",
+          "description": "Old import path (no longer exports this symbol after this version).",
+          "examples": ["@devalok/shilp-sutra/ui"]
+        },
+        "to": {
+          "type": "string",
+          "description": "New import path (exports this symbol going forward).",
+          "examples": ["@devalok/shilp-sutra/ui/toaster"]
+        },
+        "peer": {
+          "type": "string",
+          "description": "Optional. If this move was driven by a peer-cliff cleanup, the peer dependency the new subpath pulls.",
+          "examples": ["sonner", "input-otp", "date-fns"]
+        },
+        "eslintRule": {
+          "type": "string",
+          "description": "Optional. The `@devalok/eslint-plugin-shilp-sutra` rule that autofixes this move.",
+          "examples": ["prefer-per-component-import"]
+        }
+      }
+    },
+    "narrowing": {
+      "type": "object",
+      "required": ["prop", "components", "from", "to", "fix"],
+      "additionalProperties": false,
+      "properties": {
+        "prop": {
+          "type": "string",
+          "description": "Prop name whose type narrowed.",
+          "examples": ["icon", "startIcon"]
+        },
+        "components": {
+          "type": "array",
+          "description": "Components whose this-prop narrowed. List each affected component explicitly — the same prop name on a component whose type was already narrower than the new type is NOT affected.",
+          "items": { "type": "string" },
+          "examples": [["CommandItem", "ActivityItem", "Chat.Message.Avatar"]]
+        },
+        "from": {
+          "type": "string",
+          "description": "Previous TypeScript type, as a string. Use the exact source form.",
+          "examples": ["React.ReactNode"]
+        },
+        "to": {
+          "type": "string",
+          "description": "New TypeScript type, as a string. Must be a subset of `from` (otherwise it's a widening, not a narrowing).",
+          "examples": ["IconInput"]
+        },
+        "fix": {
+          "type": "string",
+          "description": "One-line consumer fix. Should be actionable from the type alone.",
+          "examples": ["Retype the icon source from React.ReactNode to React.ReactElement."]
+        }
+      }
+    },
+    "removal": {
+      "type": "object",
+      "required": ["symbol", "where"],
+      "additionalProperties": false,
+      "properties": {
+        "symbol": {
+          "type": "string",
+          "examples": ["variant=\"filled\""]
+        },
+        "where": {
+          "type": "string",
+          "description": "What the symbol was on — a component, an import path, or a token namespace.",
+          "examples": ["Alert", "@devalok/shilp-sutra/tailwind"]
+        },
+        "replacement": {
+          "type": "string",
+          "description": "Optional. If a replacement exists at the same site, name it. If there is none, omit.",
+          "examples": ["variant=\"solid\""]
+        },
+        "deprecatedSince": {
+          "type": "string",
+          "description": "Optional. The version that first emitted a deprecation warning, if a cycle was observed.",
+          "examples": ["0.32.0"]
+        }
+      }
+    },
+    "rename": {
+      "type": "object",
+      "required": ["from", "to", "where"],
+      "additionalProperties": false,
+      "properties": {
+        "from": {
+          "type": "string",
+          "examples": ["isLoadingMore"]
+        },
+        "to": {
+          "type": "string",
+          "examples": ["loadingMore"]
+        },
+        "where": {
+          "type": "string",
+          "description": "Component or import path the rename applies to.",
+          "examples": ["MessageList"]
+        },
+        "kind": {
+          "type": "string",
+          "enum": ["prop", "export", "variant"],
+          "default": "prop"
+        }
+      }
+    }
+  }
+}

package/MIGRATION.md

@@ -4,6 +4,14 @@ 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.41.0 — `BREAKING.json` manifest + recipe polish (no migration needed)
+
+**Non-breaking minor.** No consumer code changes required.
+
+- **New:** `packages/core/BREAKING.json` ships in the tarball — a machine-readable record of every breaking change per version. AI agents and migration tooling can `import manifest from '@devalok/shilp-sutra/BREAKING.json'` instead of parsing this file. Schema at `BREAKING.schema.json`.
+- **Docs:** Next.js App Router install recipe gained a Tested-on matrix, explicit replace-the-whole-scaffold-globals.css guidance, Turbopack note, and three new gotchas (`pnpm-workspace.yaml`, auto-generated `AGENTS.md` markers, scaffold body-font cascade). No setup change required for existing consumers.
+- **Internals:** release.yml now regenerates Agent Skill references before the pre-publish audit (kills the skill-drift email spam class). No impact on the published tarball.
+
 ## v0.40.0 — Barrel peer-cliff cleanup + Icon API unification
 
 This release pairs one breaking change (barrel peer-cliff cleanup) with one non-breaking type widening (Icon API unification). Read the breaking section first.

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

@@ -2,6 +2,8 @@
 
 > Setup recipe for adding `@devalok/shilp-sutra` to a Next.js 13+ App Router project.
 
+> **Tested cold-install on:** Next 16.2.6 + React 19.2 + Turbopack + pnpm 10.30 + Node 22 + Windows 11 (2026-05-25). Earlier versions of Next 13/14/15 are still supported on this recipe; deltas called out inline.
+
 ## 1. Detect the framework
 
 You are in this recipe if **all** of these are true:
@@ -59,27 +61,35 @@ Some components depend on third-party libraries that ship as optional peers. **I
 
 ## 3. Configure PostCSS
 
-Create or update `postcss.config.mjs` at the project root:
+**Next 14+ scaffolds this for you.** Verify `postcss.config.mjs` (or `.js` / `.cjs` / `.json`) at the project root contains:
 
 ```js
-export default {
+const config = {
   plugins: {
     "@tailwindcss/postcss": {},
   },
 };
+
+export default config;
 ```
 
-If a `postcss.config.{js,cjs,json}` already exists, merge the plugin in. Do not delete the existing file.
+If the file is missing, create it with the contents above. If another PostCSS file exists with different plugins, merge `@tailwindcss/postcss` in — do not delete the existing file.
 
 ## 4. Wire Tailwind 4 + design tokens
 
-Locate the global CSS file. Common paths in priority order:
+### 4a. Locate the global CSS file
+
+Next 13+ default location depends on the `--src-dir` choice at scaffold time:
+
+- `src/app/globals.css` — default since Next 14 when scaffolded without `--src-dir false`. **Most common in Next 16+ defaults.**
+- `app/globals.css` — when scaffolded with `--src-dir false` (no `src/`).
+- `app/global.css` — older Next 13 scaffolds.
 
-- `app/globals.css`
-- `src/app/globals.css`
-- `app/global.css`
+If none exists, create at whichever path matches the project's existing `app/` location.
 
-If none exists, create `app/globals.css`. Set the file contents to (or merge into):
+### 4b. Replace the scaffold's CSS with the shilp-sutra setup
+
+A fresh `create-next-app` scaffold writes a `globals.css` with `:root` color vars, an `@theme inline` block linked to Geist font vars, a `prefers-color-scheme` dark override, and a `body { font-family: Arial }` block. **Replace the entire file** with the shilp-sutra setup unless you have a specific reason to keep scaffold styles:
 
 ```css
 @import "tailwindcss";
@@ -88,7 +98,11 @@ If none exists, create `app/globals.css`. Set the file contents to (or merge int
 
 **Order matters.** `tailwindcss` MUST come first. The shilp-sutra `/css` entry registers `@theme` blocks that the Tailwind import must process.
 
-If the project has its own theme overrides, place them AFTER both imports:
+If you want to keep the scaffold's color/font vars alongside shilp-sutra tokens (rare — usually you want one or the other), put scaffold's `@theme inline` / `:root` / `body` blocks AFTER the shilp-sutra import. Otherwise the scaffold's `body { font-family: Arial }` will compete with shilp-sutra's font setup.
+
+### 4c. Optional: add your own theme overrides
+
+Place after both imports:
 
 ```css
 @import "tailwindcss";
@@ -99,12 +113,16 @@ If the project has its own theme overrides, place them AFTER both imports:
 }
 ```
 
-Import the CSS file once from `app/layout.tsx` (it should already be imported in a fresh `create-next-app` project):
+### 4d. Ensure CSS is imported from the layout
+
+The CSS import in `app/layout.tsx` (or `src/app/layout.tsx`) should already exist in a fresh scaffold:
 
 ```tsx
 import "./globals.css";
 ```
 
+If you removed the Geist-font import from layout.tsx (see § 6), keep this CSS import line.
+
 ## 5. Configure `transpilePackages`
 
 Edit `next.config.{ts,js,mjs}`. Add the `transpilePackages` field:
@@ -123,6 +141,8 @@ If a `transpilePackages` array already exists, append to it. Do not replace.
 
 Without `transpilePackages`, Next will refuse to load our pre-built `dist/*.js` because it ships native ESM that does not match Next's CJS-leaning loader for `node_modules`.
 
+**Turbopack:** as of Next 16, Turbopack is the default bundler (`next dev` and `next build`). `transpilePackages` is respected by both Turbopack and the Webpack backend. Tested on Turbopack 16.2 cold-install (2026-05-25); no extra config needed.
+
 ## 6. Scaffold the Providers wrapper
 
 Create `app/providers.tsx`:
@@ -149,13 +169,21 @@ export function Providers({ children }: { children: ReactNode }) {
 - Drop the `Toaster` import and its JSX usage
 - Skip installing `sonner`
 
-Mount `<Providers>` from `app/layout.tsx`:
+Mount `<Providers>` from `app/layout.tsx` (or `src/app/layout.tsx`). **Replace the scaffold's layout** with the version below — the scaffold imports `next/font/google` (Geist) and applies font-variable classes to `<html>`, which you don't need when shilp-sutra ships its own fonts:
 
 ```tsx
+import type { Metadata } from "next";
 import "./globals.css";
 import { Providers } from "./providers";
 
-export default function RootLayout({ children }: { children: React.ReactNode }) {
+export const metadata: Metadata = {
+  title: "Your app",
+  description: "Built with shilp-sutra",
+};
+
+export default function RootLayout({
+  children,
+}: Readonly<{ children: React.ReactNode }>) {
   return (
     <html lang="en" suppressHydrationWarning>
       <body>
@@ -166,11 +194,20 @@ export default function RootLayout({ children }: { children: React.ReactNode })
 }
 ```
 
+Specifically, **remove these scaffold lines**:
+
+- `import { Geist, Geist_Mono } from "next/font/google";`
+- The `const geistSans = Geist({...})` and `const geistMono = Geist_Mono({...})` blocks
+- The `className={`${geistSans.variable} ${geistMono.variable} h-full antialiased`}` on `<html>`
+- The `className="min-h-full flex flex-col"` on `<body>`
+
+If you want to keep Geist alongside shilp-sutra's fonts, leave the `Geist` imports — but know that shilp-sutra's `font-sans` token resolves to Inter (body) and Ranade (display), not to the scaffold's `--font-geist-sans`. Loading both is wasted bytes.
+
 `suppressHydrationWarning` on `<html>` is required because `next-themes` writes the `class` attribute before React hydrates. Without it, every page logs a hydration warning.
 
 ## 7. Verify the install
 
-Replace the contents of `app/page.tsx`:
+Replace the contents of `app/page.tsx` (or `src/app/page.tsx`). The scaffold's `page.tsx` imports `next/image` and renders the Vercel marketing layout — replace the whole file:
 
 ```tsx
 import { Button } from "@devalok/shilp-sutra/ui/button";
@@ -209,6 +246,7 @@ If anything is off, see [troubleshoot.md](./troubleshoot.md).
 ## 8. Common gotchas
 
 - **CSS import order.** `tailwindcss` BEFORE `@devalok/shilp-sutra/css`. Reversing the order silently produces a build with no design-system utilities.
+- **Scaffold's `body { font-family: Arial }` overrides shilp-sutra fonts.** The `create-next-app` `globals.css` template sets `font-family: Arial, Helvetica, sans-serif` on `<body>`. If you kept the scaffold's body styles, they win the cascade over shilp-sutra's `font-sans`. § 4b says to replace the whole file — follow it.
 - **Multiple `framer-motion` copies.** Run `pnpm why framer-motion`. If it shows more than one resolved version, contexts (`MotionConfig`, `LayoutGroup`, `AnimatePresence`) silently break. Fix:
   ```jsonc
   // package.json
@@ -222,7 +260,9 @@ If anything is off, see [troubleshoot.md](./troubleshoot.md).
   ```
   For npm/yarn/bun equivalents, see [troubleshoot.md](./troubleshoot.md).
 - **Per-component imports keep RSC fast AND avoid peer-dep cliffs.** Inside Server Components, prefer `@devalok/shilp-sutra/ui/text`, `…/composed/page-header`, etc. The barrel `@devalok/shilp-sutra/ui` re-exports many client components — including some with hard peer-dep imports (e.g. `input-otp`) — so it both inflates the client bundle and forces those peers to be installed even when you never render those components. See [server-components.md](./server-components.md) for the full RSC-safety matrix.
-- **`p-3` vs `p-ds-03` — both are valid.** DS spacing uses the `--spacing-ds-*` namespace (`p-ds-04`, `gap-ds-03`); Tailwind 4's default numeric scale (`p-4`, `gap-2`) coexists by design. Pick `p-ds-*` for values that should track DS theme changes (card padding, form gaps); pick `p-N` for one-off layout values (section breathing room). Do NOT mass-codemod `p-4` → `p-ds-04` — that is not what the package intends.
+- **`p-3` vs `p-ds-03` — both are valid.** DS spacing uses the `--spacing-ds-*` namespace (`p-ds-04`, `gap-ds-03`); Tailwind 4's default numeric scale (`p-4`, `gap-2`) coexists by design. Pick `p-ds-*` for values that should track DS theme changes (card padding, form gaps); pick `p-N` for one-off layout values (section breathing room). Do NOT mass-codemod `p-4` → `p-ds-04` — that is not what the package intends. For layout rhythm, pick a 3-tier cadence (`ds-03` related / `ds-05` grouped / `ds-07` section), not every adjacent token.
+- **Auto-generated `pnpm-workspace.yaml`.** `pnpm 10+` writes a `pnpm-workspace.yaml` at the project root on first install with `ignoredBuiltDependencies` entries. This is harmless for a standalone app, but if you're nesting this project inside a larger monorepo, delete this file and use the parent monorepo's workspace config instead.
+- **Auto-generated `AGENTS.md`.** `create-next-app` writes an `AGENTS.md` with managed `<!-- BEGIN:nextjs-agent-rules -->` / `<!-- END:nextjs-agent-rules -->` markers. Shilp Sutra's agent rules use `<!-- BEGIN:shilp-sutra-agent-rules -->` markers — they coexist cleanly. If you install the shilp-sutra Agent Skill (see the repo root `AGENTS.md` for the one-liner), it adds its block alongside Next's, not over it.
 - **Bare `shadow` is dead.** Tailwind 4 has no `--shadow-DEFAULT`. Use `shadow-raised`, `shadow-overlay`, or `shadow-floating`.
 
 ## 9. What you should NOT do

package/docs/recipes/upgrading.md

@@ -16,6 +16,25 @@ A version bump is **not** safe-by-default. Breaking changes in this design syste
 
 ## Step 2 — find affected call sites in your code
 
+**Fastest path — read the machine-readable manifest:**
+
+```bash
+# Lists every break per version as structured data (moves, narrowings, removals)
+cat node_modules/@devalok/shilp-sutra/BREAKING.json
+```
+
+Or programmatically:
+
+```js
+import manifest from '@devalok/shilp-sutra/BREAKING.json'
+// manifest.versions["0.40.0"].moved        → [{ symbol, from, to, peer, eslintRule }, …]
+// manifest.versions["0.40.0"].narrowed     → [{ prop, components, from, to, fix }, …]
+```
+
+Schema: `@devalok/shilp-sutra/BREAKING.schema.json`. AI agents should prefer this over prose-parsing CHANGELOG.
+
+**Or grep manually:**
+
 ```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"

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.1
+> Version: 0.41.0
 >
 > **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

@@ -47,6 +47,8 @@ Per-framework recipes: `node_modules/@devalok/shilp-sutra/docs/recipes/install-<
 
 **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.
 
+**Machine-readable breaks:** `node_modules/@devalok/shilp-sutra/BREAKING.json` lists every breaking change per version as structured data (moves, narrowings, removals). Read this for programmatic upgrade planning instead of parsing CHANGELOG prose. Schema: `BREAKING.schema.json`.
+
 ## OPTIONAL PEER DEPENDENCIES (install BEFORE first import)
 
 | When you import…                                          | Install                                                                                                |
@@ -67,7 +69,7 @@ Per-framework recipes: `node_modules/@devalok/shilp-sutra/docs/recipes/install-<
 2. **`framer-motion@^12` required peer.** Single copy — configure pnpm/yarn overrides if you see duplicates.
 3. **`sonner@^2`** required only when you render `<Toaster />` or call `toast.*`. Optional otherwise.
 4. **Per-component imports keep RSC fast AND avoid peer-dep cliffs.** Barrel `@devalok/shilp-sutra/ui` works in client contexts but inflates client bundle and forces optional peers to be installed. Prefer `…/ui/text`, `…/ui/dialog`, etc. The barrel **no longer** re-exports peer-cliff symbols (`Toaster`, `toast`, `InputOTP`, `DatePicker`, `RichTextEditor`, `EmojiPicker`, `FilePreview`, `MarkdownViewer`, `BlockRenderer`, `ErrorBlock`, `TextBlock`) as of 0.40.0 — import per-component.
-5. **Spacing namespace is `--spacing-ds-*`.** `p-ds-04`, `gap-ds-03` — these DO NOT replace TW4 default `p-4`, `gap-2`. Both coexist by design. Pick `p-ds-*` for values that should track DS theme changes, `p-N` for one-off layout values.
+5. **Spacing namespace is `--spacing-ds-*`.** `p-ds-04`, `gap-ds-03` — these DO NOT replace TW4 default `p-4`, `gap-2`. Both coexist by design. Pick `p-ds-*` for values that should track DS theme changes, `p-N` for one-off layout values. **Cadence when building layouts:** pick a 3-tier scale, not every adjacent token — `ds-03` (related: label↔field), `ds-05` (grouped: between field-groups), `ds-07` (section: between blocks), optional `ds-08`+ (hero). 3-4 distinct gaps per surface max; 5+ = muddy rhythm. Anti-pattern: `ds-02` + `ds-04` as different signals on one surface (they collapse). Squint test must still show grouping.
 6. **Bare `shadow` class renders no shadow in TW4.** Use `shadow-raised` (cards), `shadow-floating` (dropdowns), `shadow-overlay` (dialogs), `shadow-ring` (focus).
 7. **Variant names must match CVA source exactly** — invented variant names silently no-op (CVA falls back to defaults). Grep `packages/core/src/ui/<component>.tsx` if in doubt.
 8. **Default to `variant="soft"`** over `variant="outline"` for non-primary Button actions. Outline only on colored backgrounds or where primary/secondary hierarchy needs a hard border.

package/llms.txt

@@ -49,6 +49,7 @@ The repo URL for these files is `https://github.com/devalok-design/shilp-sutra/t
 - **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).
+- **Machine-readable `BREAKING.json` manifest** (v0.40.2+). Structured record of every breaking change per version (moves, narrowings, removals, renames). At `node_modules/@devalok/shilp-sutra/BREAKING.json` after install; subpath export `@devalok/shilp-sutra/BREAKING.json`. AI agents and migration tooling read this instead of parsing CHANGELOG prose. Schema at `BREAKING.schema.json`. Pre-publish-audit gate enforces a manifest entry for every release with a breaking CHANGELOG signal.
 
 ## BREAKING CHANGES (v0.40.0)
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@devalok/shilp-sutra",
-  "version": "0.40.1",
+  "version": "0.41.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>",
@@ -65,6 +65,8 @@
     },
     "./css": "./dist/tokens/shilp-sutra.css",
     "./tokens": "./dist/tokens/index.css",
+    "./BREAKING.json": "./BREAKING.json",
+    "./BREAKING.schema.json": "./BREAKING.schema.json",
     "./ui": {
       "types": "./dist/ui/index.d.ts",
       "import": "./dist/ui/index.js",
@@ -802,6 +804,8 @@
     "skill",
     "scripts/welcome.mjs",
     "AGENTS.md",
+    "BREAKING.json",
+    "BREAKING.schema.json",
     "MIGRATION.md",
     "README.md",
     "llms.txt",

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.1"
+  version: "0.41.0"
   author: Devalok Design & Strategy Studios
   homepage: https://github.com/devalok-design/shilp-sutra
   npm: https://www.npmjs.com/package/@devalok/shilp-sutra
@@ -64,8 +64,8 @@ These are non-negotiable. Violating any of them produces runtime errors that loo
    ```
 2. **`framer-motion@^12` is a required peer dep.** The consumer must install it. Module-scoped contexts (`MotionConfig`, `LayoutGroup`, `AnimatePresence`) silently break if two copies of framer-motion resolve. Configure pnpm/yarn to dedupe.
 3. **`sonner@^2` is an optional peer dep.** Install only when rendering `<Toaster />`.
-4. **Per-component imports are mandatory for React Server Components.** `@devalok/shilp-sutra/ui/text` is server-safe; the barrel `@devalok/shilp-sutra/ui` pulls client code and crashes RSC. See `references/server-components.md` for the per-component matrix.
-5. **Spacing namespace is `--spacing-ds-*`.** Write `p-ds-04`, not `p-4`. Same for typography: `text-ds-body-md`, not `text-base`.
+4. **Prefer per-component imports — they keep RSC bundles small and avoid peer-dep cliffs.** `@devalok/shilp-sutra/ui/text` is server-safe and pulls only its own peers. The barrel `@devalok/shilp-sutra/ui` re-exports every component (including ones with hard peer deps like `input-otp`), so it forces those peers to install even when unused. With all peers installed the barrel also works in RSC (per-component `"use client"` is honoured), but the client bundle is larger. Prefer per-component for new code; existing barrel usage is not an emergency. See `references/server-components.md`.
+5. **Spacing uses the `--spacing-ds-*` namespace** (`p-ds-04`, `gap-ds-03`); typography uses `text-ds-body-md`. These **coexist with** Tailwind 4's numeric scale (`p-4`, `gap-2`) by design — both valid. Pick `p-ds-*` for values that should track DS theme changes, `p-N` for one-off layout. Do NOT mass-codemod `p-4` → `p-ds-04`. **Cadence when building layouts:** pick a 3-tier scale, not every adjacent token — `ds-03` (related: label↔field), `ds-05` (grouped: between field-groups), `ds-07` (section: between blocks), optional `ds-08`+ (hero). 3-4 distinct gaps per surface; 5+ reads muddy. Anti-pattern: `ds-02` + `ds-04` as different signals on one surface — they collapse. The squint test must still reveal grouping.
 6. **Bare `shadow` does not exist in Tailwind 4.** Use `shadow-raised`, `shadow-overlay`, `shadow-floating`. Bare `rounded` is fine (maps to `--radius`); `rounded-ds-lg` etc. for sized variants.
 7. **Do not invent variant names.** CVA source files at `node_modules/@devalok/shilp-sutra/dist/ui/*.d.ts` (or `packages/core/src/ui/*.tsx` in the DS repo) are authoritative. When in doubt, check `references/components-full.md` for the enumerated list. If you guess a variant that doesn't exist, the prop is silently dropped and the default applies.
 8. **Default `variant="soft"` over `variant="outline"` for non-primary Button actions.** Soft (tinted bg + tinted text, no border) reads warmer in data-dense UIs. Use outline only when soft would disappear on a colored background or when a primary/secondary hierarchy needs a visible border.

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.1
+> Version: 0.41.0
 >
 > **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

@@ -51,6 +51,7 @@ The repo URL for these files is `https://github.com/devalok-design/shilp-sutra/t
 - **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).
+- **Machine-readable `BREAKING.json` manifest** (v0.40.2+). Structured record of every breaking change per version (moves, narrowings, removals, renames). At `node_modules/@devalok/shilp-sutra/BREAKING.json` after install; subpath export `@devalok/shilp-sutra/BREAKING.json`. AI agents and migration tooling read this instead of parsing CHANGELOG prose. Schema at `BREAKING.schema.json`. Pre-publish-audit gate enforces a manifest entry for every release with a breaking CHANGELOG signal.
 
 ## BREAKING CHANGES (v0.40.0)
 

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

@@ -4,6 +4,8 @@
 
 > Setup recipe for adding `@devalok/shilp-sutra` to a Next.js 13+ App Router project.
 
+> **Tested cold-install on:** Next 16.2.6 + React 19.2 + Turbopack + pnpm 10.30 + Node 22 + Windows 11 (2026-05-25). Earlier versions of Next 13/14/15 are still supported on this recipe; deltas called out inline.
+
 ## 1. Detect the framework
 
 You are in this recipe if **all** of these are true:
@@ -61,27 +63,35 @@ Some components depend on third-party libraries that ship as optional peers. **I
 
 ## 3. Configure PostCSS
 
-Create or update `postcss.config.mjs` at the project root:
+**Next 14+ scaffolds this for you.** Verify `postcss.config.mjs` (or `.js` / `.cjs` / `.json`) at the project root contains:
 
 ```js
-export default {
+const config = {
   plugins: {
     "@tailwindcss/postcss": {},
   },
 };
+
+export default config;
 ```
 
-If a `postcss.config.{js,cjs,json}` already exists, merge the plugin in. Do not delete the existing file.
+If the file is missing, create it with the contents above. If another PostCSS file exists with different plugins, merge `@tailwindcss/postcss` in — do not delete the existing file.
 
 ## 4. Wire Tailwind 4 + design tokens
 
-Locate the global CSS file. Common paths in priority order:
+### 4a. Locate the global CSS file
+
+Next 13+ default location depends on the `--src-dir` choice at scaffold time:
+
+- `src/app/globals.css` — default since Next 14 when scaffolded without `--src-dir false`. **Most common in Next 16+ defaults.**
+- `app/globals.css` — when scaffolded with `--src-dir false` (no `src/`).
+- `app/global.css` — older Next 13 scaffolds.
 
-- `app/globals.css`
-- `src/app/globals.css`
-- `app/global.css`
+If none exists, create at whichever path matches the project's existing `app/` location.
 
-If none exists, create `app/globals.css`. Set the file contents to (or merge into):
+### 4b. Replace the scaffold's CSS with the shilp-sutra setup
+
+A fresh `create-next-app` scaffold writes a `globals.css` with `:root` color vars, an `@theme inline` block linked to Geist font vars, a `prefers-color-scheme` dark override, and a `body { font-family: Arial }` block. **Replace the entire file** with the shilp-sutra setup unless you have a specific reason to keep scaffold styles:
 
 ```css
 @import "tailwindcss";
@@ -90,7 +100,11 @@ If none exists, create `app/globals.css`. Set the file contents to (or merge int
 
 **Order matters.** `tailwindcss` MUST come first. The shilp-sutra `/css` entry registers `@theme` blocks that the Tailwind import must process.
 
-If the project has its own theme overrides, place them AFTER both imports:
+If you want to keep the scaffold's color/font vars alongside shilp-sutra tokens (rare — usually you want one or the other), put scaffold's `@theme inline` / `:root` / `body` blocks AFTER the shilp-sutra import. Otherwise the scaffold's `body { font-family: Arial }` will compete with shilp-sutra's font setup.
+
+### 4c. Optional: add your own theme overrides
+
+Place after both imports:
 
 ```css
 @import "tailwindcss";
@@ -101,12 +115,16 @@ If the project has its own theme overrides, place them AFTER both imports:
 }
 ```
 
-Import the CSS file once from `app/layout.tsx` (it should already be imported in a fresh `create-next-app` project):
+### 4d. Ensure CSS is imported from the layout
+
+The CSS import in `app/layout.tsx` (or `src/app/layout.tsx`) should already exist in a fresh scaffold:
 
 ```tsx
 import "./globals.css";
 ```
 
+If you removed the Geist-font import from layout.tsx (see § 6), keep this CSS import line.
+
 ## 5. Configure `transpilePackages`
 
 Edit `next.config.{ts,js,mjs}`. Add the `transpilePackages` field:
@@ -125,6 +143,8 @@ If a `transpilePackages` array already exists, append to it. Do not replace.
 
 Without `transpilePackages`, Next will refuse to load our pre-built `dist/*.js` because it ships native ESM that does not match Next's CJS-leaning loader for `node_modules`.
 
+**Turbopack:** as of Next 16, Turbopack is the default bundler (`next dev` and `next build`). `transpilePackages` is respected by both Turbopack and the Webpack backend. Tested on Turbopack 16.2 cold-install (2026-05-25); no extra config needed.
+
 ## 6. Scaffold the Providers wrapper
 
 Create `app/providers.tsx`:
@@ -151,13 +171,21 @@ export function Providers({ children }: { children: ReactNode }) {
 - Drop the `Toaster` import and its JSX usage
 - Skip installing `sonner`
 
-Mount `<Providers>` from `app/layout.tsx`:
+Mount `<Providers>` from `app/layout.tsx` (or `src/app/layout.tsx`). **Replace the scaffold's layout** with the version below — the scaffold imports `next/font/google` (Geist) and applies font-variable classes to `<html>`, which you don't need when shilp-sutra ships its own fonts:
 
 ```tsx
+import type { Metadata } from "next";
 import "./globals.css";
 import { Providers } from "./providers";
 
-export default function RootLayout({ children }: { children: React.ReactNode }) {
+export const metadata: Metadata = {
+  title: "Your app",
+  description: "Built with shilp-sutra",
+};
+
+export default function RootLayout({
+  children,
+}: Readonly<{ children: React.ReactNode }>) {
   return (
     <html lang="en" suppressHydrationWarning>
       <body>
@@ -168,11 +196,20 @@ export default function RootLayout({ children }: { children: React.ReactNode })
 }
 ```
 
+Specifically, **remove these scaffold lines**:
+
+- `import { Geist, Geist_Mono } from "next/font/google";`
+- The `const geistSans = Geist({...})` and `const geistMono = Geist_Mono({...})` blocks
+- The `className={`${geistSans.variable} ${geistMono.variable} h-full antialiased`}` on `<html>`
+- The `className="min-h-full flex flex-col"` on `<body>`
+
+If you want to keep Geist alongside shilp-sutra's fonts, leave the `Geist` imports — but know that shilp-sutra's `font-sans` token resolves to Inter (body) and Ranade (display), not to the scaffold's `--font-geist-sans`. Loading both is wasted bytes.
+
 `suppressHydrationWarning` on `<html>` is required because `next-themes` writes the `class` attribute before React hydrates. Without it, every page logs a hydration warning.
 
 ## 7. Verify the install
 
-Replace the contents of `app/page.tsx`:
+Replace the contents of `app/page.tsx` (or `src/app/page.tsx`). The scaffold's `page.tsx` imports `next/image` and renders the Vercel marketing layout — replace the whole file:
 
 ```tsx
 import { Button } from "@devalok/shilp-sutra/ui/button";
@@ -211,6 +248,7 @@ If anything is off, see [troubleshoot.md](./troubleshoot.md).
 ## 8. Common gotchas
 
 - **CSS import order.** `tailwindcss` BEFORE `@devalok/shilp-sutra/css`. Reversing the order silently produces a build with no design-system utilities.
+- **Scaffold's `body { font-family: Arial }` overrides shilp-sutra fonts.** The `create-next-app` `globals.css` template sets `font-family: Arial, Helvetica, sans-serif` on `<body>`. If you kept the scaffold's body styles, they win the cascade over shilp-sutra's `font-sans`. § 4b says to replace the whole file — follow it.
 - **Multiple `framer-motion` copies.** Run `pnpm why framer-motion`. If it shows more than one resolved version, contexts (`MotionConfig`, `LayoutGroup`, `AnimatePresence`) silently break. Fix:
   ```jsonc
   // package.json
@@ -224,7 +262,9 @@ If anything is off, see [troubleshoot.md](./troubleshoot.md).
   ```
   For npm/yarn/bun equivalents, see [troubleshoot.md](./troubleshoot.md).
 - **Per-component imports keep RSC fast AND avoid peer-dep cliffs.** Inside Server Components, prefer `@devalok/shilp-sutra/ui/text`, `…/composed/page-header`, etc. The barrel `@devalok/shilp-sutra/ui` re-exports many client components — including some with hard peer-dep imports (e.g. `input-otp`) — so it both inflates the client bundle and forces those peers to be installed even when you never render those components. See [server-components.md](./server-components.md) for the full RSC-safety matrix.
-- **`p-3` vs `p-ds-03` — both are valid.** DS spacing uses the `--spacing-ds-*` namespace (`p-ds-04`, `gap-ds-03`); Tailwind 4's default numeric scale (`p-4`, `gap-2`) coexists by design. Pick `p-ds-*` for values that should track DS theme changes (card padding, form gaps); pick `p-N` for one-off layout values (section breathing room). Do NOT mass-codemod `p-4` → `p-ds-04` — that is not what the package intends.
+- **`p-3` vs `p-ds-03` — both are valid.** DS spacing uses the `--spacing-ds-*` namespace (`p-ds-04`, `gap-ds-03`); Tailwind 4's default numeric scale (`p-4`, `gap-2`) coexists by design. Pick `p-ds-*` for values that should track DS theme changes (card padding, form gaps); pick `p-N` for one-off layout values (section breathing room). Do NOT mass-codemod `p-4` → `p-ds-04` — that is not what the package intends. For layout rhythm, pick a 3-tier cadence (`ds-03` related / `ds-05` grouped / `ds-07` section), not every adjacent token.
+- **Auto-generated `pnpm-workspace.yaml`.** `pnpm 10+` writes a `pnpm-workspace.yaml` at the project root on first install with `ignoredBuiltDependencies` entries. This is harmless for a standalone app, but if you're nesting this project inside a larger monorepo, delete this file and use the parent monorepo's workspace config instead.
+- **Auto-generated `AGENTS.md`.** `create-next-app` writes an `AGENTS.md` with managed `<!-- BEGIN:nextjs-agent-rules -->` / `<!-- END:nextjs-agent-rules -->` markers. Shilp Sutra's agent rules use `<!-- BEGIN:shilp-sutra-agent-rules -->` markers — they coexist cleanly. If you install the shilp-sutra Agent Skill (see the repo root `AGENTS.md` for the one-liner), it adds its block alongside Next's, not over it.
 - **Bare `shadow` is dead.** Tailwind 4 has no `--shadow-DEFAULT`. Use `shadow-raised`, `shadow-overlay`, or `shadow-floating`.
 
 ## 9. What you should NOT do

package/skill/references/upgrading.md

@@ -18,6 +18,25 @@ A version bump is **not** safe-by-default. Breaking changes in this design syste
 
 ## Step 2 — find affected call sites in your code
 
+**Fastest path — read the machine-readable manifest:**
+
+```bash
+# Lists every break per version as structured data (moves, narrowings, removals)
+cat node_modules/@devalok/shilp-sutra/BREAKING.json
+```
+
+Or programmatically:
+
+```js
+import manifest from '@devalok/shilp-sutra/BREAKING.json'
+// manifest.versions["0.40.0"].moved        → [{ symbol, from, to, peer, eslintRule }, …]
+// manifest.versions["0.40.0"].narrowed     → [{ prop, components, from, to, fix }, …]
+```
+
+Schema: `@devalok/shilp-sutra/BREAKING.schema.json`. AI agents should prefer this over prose-parsing CHANGELOG.
+
+**Or grep manually:**
+
 ```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"