@devalok/shilp-sutra 0.40.0 → 0.41.0

package/AGENTS.md

@@ -24,7 +24,8 @@ If you are a human, read [README.md](./README.md) instead.
 2. **`packages/core/llms.txt`** — concise current-API cheatsheet (~27K tokens). Reach for this when `llms-quick.txt` isn't enough — covers more components + recent CHANGELOG sections.
 3. **`packages/core/docs/recipes/<framework>.md`** — copy-paste install + setup for the user's framework.
 4. **`packages/core/llms-full.txt`** — exhaustive per-component reference (~140K tokens, props/variants/examples). Read only when `llms.txt` is insufficient.
-5. **`MIGRATION.md`** — only if upgrading across versions.
+5. **`packages/core/docs/recipes/upgrading.md`** + **`MIGRATION.md`** — read BOTH before any version bump. See the hard constraint below.
+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,6 +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. **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";
@@ -73,6 +75,31 @@ 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.
+
 ## When something fails
 
 Read **`packages/core/docs/recipes/troubleshoot.md`** before retrying or guessing. It is a decision tree covering the thirteen most common breakages (Tailwind not detecting tokens, framer-motion duplicates, missing `transpilePackages`, missing optional peer deps (sonner / input-otp / date-fns / @tiptap / react-pdf / etc.), wrong CSS import order, dark mode not toggling, RSC import errors, font 404s, hydration mismatches, bare `shadow` class, `<Toaster />` not mounted, Storybook MCP 404).

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

package/README.md

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

package/docs/recipes/index.md

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

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

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

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