admin-ui-starter-kit 0.1.2 → 0.1.3

package/.agents/skills/admin-ui-consumer-migration/SKILL.md

@@ -0,0 +1,126 @@
+---
+name: admin-ui-consumer-migration
+description: Use when migrating a React app to consume `admin-ui-starter-kit`, replacing copied local UI folders, auditing exact package imports, deciding what stays app-owned, or wiring framework adapters such as Inertia without recreating local package mirrors.
+---
+
+# Admin UI Consumer Migration
+
+Use this skill inside consuming apps, not when editing package internals.
+
+Goal: move reusable UI to `admin-ui-starter-kit` imports while keeping
+app-specific routing, APIs, auth, translations, brand assets, and domain logic
+inside the app.
+
+## First reads
+
+When available in the installed package or repo, read these before editing:
+
+1. `MIGRATION.md` — migration sequence and deletion rules.
+2. `COMPONENT_SELECTION.md` — which component/import to use.
+3. `INTEGRATION.md` — install, provider, exact import, and framework wiring.
+4. `.agents/skills/component-library-rules/references/components/INDEX.json` —
+   searchable component index.
+
+Do not bulk-load every component doc. Use the index, then read only the matching
+component file.
+
+## Migration order
+
+1. Install package, stylesheet, and `<UIProvider>`.
+2. Replace typography, buttons, badges, cards, and simple display components.
+3. Replace repeated row and metadata patterns with `Item` and `MetadataList`.
+4. Replace form rows with `FormField` / `ControlledFormField`.
+5. Replace tables, filters, metrics, comments, overlays, and other features.
+6. Replace page/header/sidebar layout surfaces last.
+7. Delete copied local folders only after imports, typecheck, and build are
+   clean.
+
+## Exact package imports only
+
+Use:
+
+```tsx
+import { Button } from 'admin-ui-starter-kit/base/buttons';
+import { Text } from 'admin-ui-starter-kit/typography';
+import { MetadataList } from 'admin-ui-starter-kit/base/display/metadata';
+import { Comments } from 'admin-ui-starter-kit/features/comments';
+```
+
+Do not use:
+
+```tsx
+import { Button } from '@/components/ui/base/buttons';
+import { Button } from 'admin-ui-starter-kit/base';
+import { MetadataList } from 'admin-ui-starter-kit/base/display/metadata/metadata-list';
+```
+
+If a path is not listed in `package.json` `exports`, treat it as private.
+
+## Adapter rule
+
+Adapters are allowed only when they bind app-specific behaviour.
+
+Good:
+
+```tsx
+import { Link, router } from '@inertiajs/react';
+import { Button, type ButtonProps } from 'admin-ui-starter-kit/base/buttons';
+
+export function InertiaButton({ href, ...props }: ButtonProps & { href: string }) {
+	return <Button {...props} onClick={() => router.visit(href)} />;
+}
+```
+
+Bad:
+
+```ts
+export { Button } from 'admin-ui-starter-kit/base/buttons';
+```
+
+Do not create local mirrors, barrels, or aliases that hide package imports.
+Agents should replace call-site imports directly unless a wrapper adds routing,
+auth, API, translation, or domain behaviour.
+
+## Keep app-owned
+
+Do not migrate these into package imports or generic wrappers:
+
+- Brand/logo assets and product marks.
+- Error boundaries.
+- Auth, permission gates, tenant/workspace selectors.
+- Route-aware global search content and API-backed search.
+- Domain-specific cards/features that encode business rules.
+- Inertia/router/query clients, Wayfinder actions, API calls, app i18n.
+- Page-level data loading and layout orchestration.
+
+## Useful commands
+
+Run in the consuming app:
+
+```bash
+npx admin-ui-starter-kit-audit
+npx admin-ui-starter-kit-audit --fix
+npm run typecheck
+npm run build
+```
+
+Use `--fix` only for conservative import rewrites from known copied paths.
+Review the diff before deleting local folders.
+
+## Component selection shortcuts
+
+| Need | Import |
+| --- | --- |
+| Text/headings | `admin-ui-starter-kit/typography` |
+| Buttons | `admin-ui-starter-kit/base/buttons` |
+| Badges | `admin-ui-starter-kit/base/badge` |
+| Card shell | `admin-ui-starter-kit/base/cards` |
+| Icon/avatar/title row | `admin-ui-starter-kit/base/item` |
+| Label/value metadata | `admin-ui-starter-kit/base/display/metadata` |
+| Form rows | `admin-ui-starter-kit/base/forms` |
+| Tables | `admin-ui-starter-kit/base/table` |
+| Filters | `admin-ui-starter-kit/features/filters` |
+| Comments | `admin-ui-starter-kit/features/comments` |
+| Dialogs/drawers | `admin-ui-starter-kit/features/overlays` |
+| Metrics/charts | `admin-ui-starter-kit/composed/analytics` |
+| Page/header/sidebar | `admin-ui-starter-kit/layout/page`, `/header`, `/sidebar` |

package/.agents/skills/component-library-rules/SKILL.md

@@ -56,6 +56,11 @@ These deeper guides live alongside this file under `references/`. The skill stay
 
 Don't read all of them — find the matching guide for the immediate task, follow it, return.
 
+Consumer-app migration guidance lives outside this maintainer skill:
+[`../admin-ui-consumer-migration/SKILL.md`](../admin-ui-consumer-migration/SKILL.md),
+`MIGRATION.md`, and `COMPONENT_SELECTION.md`. Use those when replacing copied
+local UI in downstream apps.
+
 ## Component reference index
 
 Every component documented in the showcase has a generated markdown
@@ -99,9 +104,14 @@ to see how the library uses it before writing fresh code.
 The references are generated from the MDX showcase by
 `npm run docs:sync-skill`; CI runs the freshness check via `npm run verify`.
 
-## This is the only skill in this repo
+## Maintainer skill scope
 
-There are no other skills shipped with this repo. The harness may surface generic skills (`frontend-design`, `shadcn`, `tailwind-v4-shadcn`, etc.) from the user's plugin set, but **this skill is the source of truth for anything inside `src/components/**`**. Where they conflict, this skill wins. The relevant material from those generic skills is inlined here:
+This skill is the source of truth for anything inside `src/components/**`.
+The separate `admin-ui-consumer-migration` skill is for downstream app
+migrations. The harness may surface generic skills (`frontend-design`,
+`shadcn`, `tailwind-v4-shadcn`, etc.) from the user's plugin set, but for this
+package's component internals, this skill wins. The relevant material from
+those generic skills is inlined here:
 
 - **Visual taste / "escape generic AI aesthetics"** → see rule 16 (visual evaluation) and the "Tone for visual work" section in `AGENTS.md`. The library voice is calm, neutral, dense without being cramped — admin density, not marketing flash.
 - **Adding a shadcn primitive** → step 0 of [`references/base-wrapper.md`](references/base-wrapper.md): `npx shadcn@latest add <primitive>` lands the file in `src/components/ui/<primitive>.tsx`. Then write the wrapper.

package/AGENTS.md

@@ -43,7 +43,7 @@ Read it once for context; it is not a live roadmap.
 
 ## Mandatory reading before any code change
 
-The **only** mandatory skill in this repo is
+The **only** mandatory maintainer skill in this repo is
 [`component-library-rules`](.agents/skills/component-library-rules/SKILL.md).
 It encodes 24 rules covering layer order, typography, density, tokens,
 strings/i18n, framework-agnostic contracts, slot/render-prop
@@ -59,9 +59,11 @@ pages, ui-provider, consumer wiring, import paths, visual evaluation,
 testing, layout, composed-domains. Pull the matching one when the work
 fits; don't read all of them.
 
-This skill is **self-sufficient by design** — there are no other skills
-shipped with this repo. If a topic isn't covered, ask before inventing
-a pattern.
+The repo also ships
+[`admin-ui-consumer-migration`](.agents/skills/admin-ui-consumer-migration/SKILL.md)
+for downstream apps migrating copied UI into the package. Use that skill in
+consumer repos; use `component-library-rules` when changing this package.
+If a topic isn't covered, ask before inventing a pattern.
 
 ## The architectural layers
 

package/COMPONENT_SELECTION.md

@@ -0,0 +1,115 @@
+# Component Selection Guide
+
+Use this when deciding which package entrypoint belongs at a call site.
+
+Public imports are exact. If a path is not listed in `package.json` `exports`
+or documented here, treat it as private.
+
+## Common decisions
+
+| Need | Use | Import |
+| --- | --- | --- |
+| Text, headings, labels, links | `Text`, `Heading`, `Label`, `TextLink` | `admin-ui-starter-kit/typography` |
+| Button or icon button | `Button`, `TextButton`, button variants | `admin-ui-starter-kit/base/buttons` |
+| Status pill or count badge | `Badge` | `admin-ui-starter-kit/base/badge` |
+| Card shell | `SmartCard` | `admin-ui-starter-kit/base/cards` |
+| Row with icon/avatar/title/meta/actions | `Item` family | `admin-ui-starter-kit/base/item` |
+| Label/value metadata | `MetadataList` | `admin-ui-starter-kit/base/display/metadata` |
+| Tooltip, avatar, separator, inline stat | display family | `admin-ui-starter-kit/base/display` |
+| Form label/control/error row | `FormField`, `ControlledFormField` | `admin-ui-starter-kit/base/forms` |
+| Inputs, selects, textareas, QR fields | form field exports | `admin-ui-starter-kit/base/forms` |
+| Searchable select | `Combobox` | `admin-ui-starter-kit/base/combobox` |
+| Popover menu or command menu | `PopoverMenu`, `Command` | `admin-ui-starter-kit/base/popover-menu`, `admin-ui-starter-kit/base/command` |
+| Dropdown navigation menus | navigation family | `admin-ui-starter-kit/base/navigation` |
+| Data table | `DataTable` | `admin-ui-starter-kit/base/table` |
+| Date picker or date range picker | date picker family | `admin-ui-starter-kit/base/date-pickers` |
+| Map or place autocomplete | map family | `admin-ui-starter-kit/base/map` |
+| KPI cards and charts | analytics surfaces | `admin-ui-starter-kit/composed/analytics` |
+| Commerce/order/product surfaces | commerce surfaces | `admin-ui-starter-kit/composed/commerce` |
+| Timeline | timeline surfaces | `admin-ui-starter-kit/composed/timelines` |
+| Comments panel | `Comments` | `admin-ui-starter-kit/features/comments` |
+| Filter bar/facets | filters feature | `admin-ui-starter-kit/features/filters` |
+| Dialog, drawer, alert dialog | overlays feature | `admin-ui-starter-kit/features/overlays` |
+| Global search shell | global search feature | `admin-ui-starter-kit/features/global-search` |
+| Mentions/typeahead | mentions or suggestions feature | `admin-ui-starter-kit/features/mentions`, `admin-ui-starter-kit/features/suggestions` |
+| Rich text editor | TipTap-backed editor | `admin-ui-starter-kit/features/rich-text-editor` |
+| Page title/actions/breadcrumb chrome | page layout | `admin-ui-starter-kit/layout/page` |
+| Header shell/search/action slots | header layout | `admin-ui-starter-kit/layout/header` |
+| Sidebar shell | sidebar layout | `admin-ui-starter-kit/layout/sidebar` |
+
+## Decision tree
+
+1. Is it plain user-facing text?
+   Use `typography`. Do not hand-roll `text-xs text-muted-foreground` spans.
+
+2. Is it a primitive UI control or presentational wrapper?
+   Use `base`. Buttons, badges, cards, form fields, popovers, tables, maps,
+   display helpers, and item rows live there.
+
+3. Is it a reusable domain-shaped surface built from base components?
+   Use `composed`. Metrics, commerce cards, admin rows, timeline surfaces, and
+   dense data-display blocks belong there.
+
+4. Does it include feature state, slots, callbacks, or app-level behaviour?
+   Use `features`. Comments, filters, search, overlays, mentions, sync, and
+   rich text editor live there.
+
+5. Is it page chrome?
+   Use `layout`. Keep routing and active-link state in the app.
+
+6. Does it hardcode backend, auth, routing, app translations, or product
+   branding?
+   Keep it in the app. Wrap package components only where the wrapper binds
+   app-specific behaviour.
+
+## Adapter examples
+
+Use an app adapter when you bind framework behaviour:
+
+```tsx
+import { router } from '@inertiajs/react';
+import { Button, type ButtonProps } from 'admin-ui-starter-kit/base/buttons';
+
+export function InertiaActionButton({
+	href,
+	method = 'get',
+	...props
+}: ButtonProps & { href: string; method?: 'get' | 'post' | 'put' | 'delete' }) {
+	return <Button {...props} onClick={() => router.visit(href, { method })} />;
+}
+```
+
+Do not create app wrappers that only rename or re-export package components:
+
+```ts
+export { Button } from 'admin-ui-starter-kit/base/buttons';
+```
+
+## Exact import rules
+
+Use:
+
+```tsx
+import { Button } from 'admin-ui-starter-kit/base/buttons';
+import { Text } from 'admin-ui-starter-kit/typography';
+import { MetadataList } from 'admin-ui-starter-kit/base/display/metadata';
+```
+
+Do not use:
+
+```tsx
+import { Button } from 'admin-ui-starter-kit/base';
+import { MetadataList } from 'admin-ui-starter-kit/base/display/metadata/metadata-list';
+import { Button } from '@/components/ui/base/buttons';
+```
+
+## Where agents should look
+
+1. `AGENTS.md`
+2. `.agents/skills/component-library-rules/SKILL.md`
+3. `.agents/skills/admin-ui-consumer-migration/SKILL.md`
+4. `.agents/skills/component-library-rules/references/components/INDEX.json`
+5. The specific component doc under `references/components/*.md`
+6. `INTEGRATION.md`
+7. `MIGRATION.md`
+8. `package.json` `exports`

package/INTEGRATION.md

@@ -2,6 +2,11 @@
 
 Use this when installing `admin-ui-starter-kit` into a React app.
 
+If the app already has a copied local design system, follow
+[`MIGRATION.md`](MIGRATION.md) first. Use
+[`COMPONENT_SELECTION.md`](COMPONENT_SELECTION.md) when deciding which exact
+entrypoint replaces a local component.
+
 ## 1. Install the package and required peers
 
 ```bash
@@ -140,6 +145,7 @@ For a quick smoke test:
 ```bash
 npm run typecheck
 npm run build
+npx admin-ui-starter-kit-audit
 ```
 
 If a build reports a missing optional peer, either install the peer listed

package/MIGRATION.md

@@ -0,0 +1,235 @@
+# Migration Guide
+
+Use this when replacing a copied local design system with the published
+`admin-ui-starter-kit` package.
+
+The goal is not to move every UI file into npm. The package owns reusable UI.
+The consuming app owns routing, API calls, auth context, translations, brand
+assets, and domain-specific behaviour.
+
+## 1. Install and mount
+
+```bash
+npm install admin-ui-starter-kit react react-dom tailwindcss lucide-react
+```
+
+If the app still uses `lucide-react` v0, upgrade it as part of the migration.
+This package has a lucide v1 peer.
+
+Mount the stylesheet and provider once:
+
+```tsx
+import 'admin-ui-starter-kit/style.css';
+import { UIProvider } from 'admin-ui-starter-kit/ui-provider';
+
+<UIProvider
+	config={{
+		money: { defaultCurrency: 'USD', locale: 'en-US' },
+		dates: { weekStartsOn: 1 },
+		badge: { defaultSize: 'xs' },
+		button: { defaultSize: 'sm' },
+	}}
+>
+	<App />
+</UIProvider>;
+```
+
+## 2. Replace local primitives first
+
+Start with the low-level imports used everywhere. Keep the changes mechanical
+and verify after each group.
+
+```tsx
+import { Button } from 'admin-ui-starter-kit/base/buttons';
+import { Badge } from 'admin-ui-starter-kit/base/badge';
+import { SmartCard } from 'admin-ui-starter-kit/base/cards';
+import { Text, Heading } from 'admin-ui-starter-kit/typography';
+```
+
+Do not create local mirror files that re-export package primitives. Replace the
+call-site imports directly.
+
+## 3. Replace repeated display patterns
+
+Use package components for shapes that repeat across the app:
+
+```tsx
+import { MetadataList } from 'admin-ui-starter-kit/base/display/metadata';
+import { Item, ItemContent, ItemMedia, ItemTitle } from 'admin-ui-starter-kit/base/item';
+```
+
+Use `MetadataList` for label/value data, compact summaries, and entity details.
+Use `Item` for rows with media, title, description, metadata, or actions.
+
+## 4. Replace form rows
+
+Use the package form shell before moving larger forms:
+
+```tsx
+import { ControlledFormField, Input, Select } from 'admin-ui-starter-kit/base/forms';
+```
+
+Keep form submission, validation schemas, and API mutation wiring in the app.
+The package should own the field row and control presentation, not the backend
+contract.
+
+## 5. Replace tables, filters, metrics, and overlays
+
+Move shared app surfaces after primitives are stable:
+
+```tsx
+import { DataTable } from 'admin-ui-starter-kit/base/table';
+import { FilterProvider } from 'admin-ui-starter-kit/features/filters';
+import { MetricGrid } from 'admin-ui-starter-kit/composed/analytics';
+import { Dialog, Drawer } from 'admin-ui-starter-kit/features/overlays';
+```
+
+Install optional peers only for the entrypoints you import. For example,
+`base/table` needs `@tanstack/react-table`, `composed/analytics` needs
+`recharts`, and `features/rich-text-editor` needs TipTap.
+
+## 6. Replace layouts last
+
+Migrate page chrome after shared atoms and features are clean:
+
+```tsx
+import { PageHeader, PageActions } from 'admin-ui-starter-kit/layout/page';
+import { Header, HeaderSearch } from 'admin-ui-starter-kit/layout/header';
+import { AppSidebar, SidebarProvider } from 'admin-ui-starter-kit/layout/sidebar';
+```
+
+Route-aware layout state, active navigation logic, auth menus, and application
+search content stay in the app. The package provides the shell and slots.
+
+## 7. Keep app-owned adapters, not local mirrors
+
+A consuming app may create adapters for framework wiring, but not local mirrors.
+
+Good:
+
+```tsx
+import { Link } from '@inertiajs/react';
+import { PageHeader, type PageHeaderProps } from 'admin-ui-starter-kit/layout/page';
+
+export function AppPageHeader(props: PageHeaderProps) {
+	return (
+		<PageHeader
+			{...props}
+			renderLink={(href, children) => <Link href={href}>{children}</Link>}
+		/>
+	);
+}
+```
+
+Bad:
+
+```ts
+export { Button } from 'admin-ui-starter-kit/base/buttons';
+export { Text } from 'admin-ui-starter-kit/typography';
+```
+
+The package owns UI. The app owns routing, API calls, auth context, and
+translations.
+
+## 8. Inertia recipe
+
+Keep Inertia imports in the consuming app:
+
+```tsx
+import { Link, router } from '@inertiajs/react';
+import { Button } from 'admin-ui-starter-kit/base/buttons';
+import { Comments } from 'admin-ui-starter-kit/features/comments';
+import { PageHeader } from 'admin-ui-starter-kit/layout/page';
+
+<PageHeader
+	title="Customers"
+	actions={<Button onClick={() => router.visit('/customers/create')}>Create</Button>}
+	renderLink={(href, children) => <Link href={href}>{children}</Link>}
+/>;
+
+<Comments
+	comments={comments}
+	onSubmit={(values) => router.post(route('comments.store'), values)}
+	onDelete={(id) => router.delete(route('comments.destroy', id))}
+	strings={{
+		empty: t('comments.empty'),
+		composerPlaceholder: t('comments.placeholder'),
+	}}
+/>;
+```
+
+Do not add Inertia adapters to the package. Document app adapters locally when
+they bind routes, Wayfinder actions, translations, or app APIs.
+
+## 9. Do not migrate these
+
+Keep these in the consuming app:
+
+- Brand assets, logos, app icons, and product-specific marks.
+- Error boundaries and app-level exception handling.
+- Route-aware search content and backend-connected global search.
+- Auth menus, permission gates, and tenant/workspace selectors.
+- Domain-specific cards and features that encode business rules.
+- API clients, query caches, Inertia router calls, and Wayfinder route actions.
+- App-specific layout orchestration and page-level data loading.
+
+## 10. Delete copied folders after imports are clean
+
+Only delete local copied folders after typecheck and build pass:
+
+```text
+components/ui/base
+components/ui/typography
+components/ui/navigation
+components/layout
+components/features/comments
+components/features/filters
+components/features/metrics
+```
+
+The exact folders vary by app. Delete only copied package equivalents; keep
+app-owned components.
+
+## 11. Hard import rules
+
+Use exact public exports:
+
+```tsx
+import { Button } from 'admin-ui-starter-kit/base/buttons';
+import { Text } from 'admin-ui-starter-kit/typography';
+import { MetadataList } from 'admin-ui-starter-kit/base/display/metadata';
+```
+
+Do not use:
+
+```tsx
+import { Button } from '@/components/ui/base/buttons';
+import { Button } from 'admin-ui-starter-kit/base';
+import { MetadataList } from 'admin-ui-starter-kit/base/display/metadata/metadata-list';
+```
+
+Run the package audit in a consumer app:
+
+```bash
+npx admin-ui-starter-kit-audit
+```
+
+Use `--fix` for conservative import rewrites from known copied paths:
+
+```bash
+npx admin-ui-starter-kit-audit --fix
+```
+
+## 12. Verification
+
+After each migration chunk:
+
+```bash
+npm run typecheck
+npm run build
+npx admin-ui-starter-kit-audit
+```
+
+If a package import fails, check `package.json` `exports` in
+`admin-ui-starter-kit`. Public imports are exact keys. Undocumented nested
+paths are private even when declaration files exist under `dist/`.

package/PUBLISHING.md

@@ -54,7 +54,12 @@ Read the file list. **Confirm:**
 - `dist/files/` and `dist/images/` are included for font and map CSS assets.
 - `style.css.d.ts` is included for strict TypeScript side-effect CSS imports.
 - `dist/showcase/` is included.
-- `README.md`, `INTEGRATION.md`, `LICENSE`, `CHANGELOG.md` are included.
+- `README.md`, `INTEGRATION.md`, `MIGRATION.md`,
+  `COMPONENT_SELECTION.md`, `LICENSE`, `CHANGELOG.md` are included.
+- `.agents/skills/component-library-rules/` and
+  `.agents/skills/admin-ui-consumer-migration/` are included.
+- `scripts/audit-consumer.mjs`, `scripts/install-skill.mjs`, and
+  `scripts/serve-showcase.mjs` are included.
 - `src/App.css` is included so consumers can copy the token source when
   building their own Tailwind output.
 - `node_modules/`, `coverage/`, `.git/`, `dist-ssr/`, the preview app

package/README.md

@@ -99,6 +99,11 @@ exactly your tool.**
 For a full framework and bundler setup walkthrough, see
 [INTEGRATION.md](INTEGRATION.md).
 
+Migrating an app that already copied an older local UI tree? Start with
+[MIGRATION.md](MIGRATION.md), then use
+[COMPONENT_SELECTION.md](COMPONENT_SELECTION.md) to choose exact package
+entrypoints.
+
 ### 1. Add the package
 
 ```bash
@@ -164,23 +169,37 @@ import { UIProvider } from 'admin-ui-starter-kit/ui-provider';
 
 The provider is locked at first mount; pass everything once at the root.
 
-### 6. Install the AI agent skill (optional)
+### 6. Install the AI agent skills (optional)
+
+This package ships AI skills for Claude Code and other agents:
 
-This package ships a `component-library-rules` skill for Claude Code and other
-AI agents. After installing the package:
+- `component-library-rules` — maintainer rules for editing this library.
+- `admin-ui-consumer-migration` — consumer-app migration rules and guardrails.
+
+After installing the package:
 
 ```bash
 npx admin-ui-starter-kit-install-skill
 ```
 
-Copies the skill into your project's `.claude/skills/component-library-rules/`
-and `.agents/skills/component-library-rules/`. Run again to update after a
-package upgrade.
+Copies both skills into your project's `.claude/skills/` and
+`.agents/skills/`. Run again to update after a package upgrade.
 
 Flags:
+- `--skill=all|component-library-rules|admin-ui-consumer-migration` (default `all`)
 - `--target=claude|agents|both` (default `both`) — pick which directory to install into.
 - `--force` — overwrite without prompting.
 
+For migration checks in a consuming app:
+
+```bash
+npx admin-ui-starter-kit-audit
+npx admin-ui-starter-kit-audit --fix
+```
+
+The audit rejects stale copied imports, invalid package subpaths, and local
+files that only re-export package components.
+
 ---
 
 ## Browse the component showcase

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "admin-ui-starter-kit",
-  "version": "0.1.2",
+  "version": "0.1.3",
   "description": "Opinionated React component kit for admin panels and SaaS dashboards, built on top of shadcn/ui + Tailwind CSS v4. Callback-driven, framework-agnostic, i18n-ready.",
   "type": "module",
   "license": "MIT",
@@ -29,6 +29,8 @@
   "files": [
     "dist",
     "README.md",
+    "MIGRATION.md",
+    "COMPONENT_SELECTION.md",
     "INTEGRATION.md",
     "CHANGELOG.md",
     "CONTRIBUTING.md",
@@ -39,10 +41,13 @@
     "CLAUDE.md",
     "AGENTS.md",
     ".agents/skills/component-library-rules",
+    ".agents/skills/admin-ui-consumer-migration",
+    "scripts/audit-consumer.mjs",
     "scripts/install-skill.mjs",
     "scripts/serve-showcase.mjs"
   ],
   "bin": {
+    "admin-ui-starter-kit-audit": "./scripts/audit-consumer.mjs",
     "admin-ui-starter-kit-install-skill": "./scripts/install-skill.mjs",
     "admin-ui-starter-kit-showcase": "./scripts/serve-showcase.mjs"
   },

package/scripts/audit-consumer.mjs

@@ -0,0 +1,326 @@
+#!/usr/bin/env node
+/**
+ * audit-consumer — checks a consuming app for common admin-ui-starter-kit
+ * migration mistakes:
+ *
+ * - stale copied import paths such as @/components/ui/base/buttons
+ * - invalid package imports not listed in package.json exports
+ * - local files that only re-export package components
+ *
+ * Run from a consumer app:
+ *
+ *   npx admin-ui-starter-kit-audit
+ *   npx admin-ui-starter-kit-audit --fix
+ */
+import { promises as fs } from 'node:fs';
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+const PACKAGE_NAME = 'admin-ui-starter-kit';
+const __filename = fileURLToPath(import.meta.url);
+const PACKAGE_ROOT = path.resolve(path.dirname(__filename), '..');
+const PACKAGE_JSON = JSON.parse(
+	await fs.readFile(path.join(PACKAGE_ROOT, 'package.json'), 'utf8'),
+);
+const PUBLIC_EXPORTS = new Set(Object.keys(PACKAGE_JSON.exports ?? {}));
+
+const DEFAULT_PATHS = ['src', 'app', 'resources/js', 'components', 'pages'];
+const CODE_EXTENSIONS = new Set(['.cjs', '.cts', '.js', '.jsx', '.mjs', '.mts', '.ts', '.tsx']);
+const SKIP_DIRS = new Set([
+	'.git',
+	'.next',
+	'.nuxt',
+	'.turbo',
+	'.vercel',
+	'build',
+	'coverage',
+	'dist',
+	'node_modules',
+	'public',
+	'vendor',
+]);
+
+function parseArgs(argv) {
+	const opts = { fix: false, json: false, help: false, paths: [] };
+	for (const arg of argv.slice(2)) {
+		if (arg === '--fix') {
+			opts.fix = true;
+		} else if (arg === '--json') {
+			opts.json = true;
+		} else if (arg === '--help' || arg === '-h') {
+			opts.help = true;
+		} else if (arg.startsWith('--paths=')) {
+			opts.paths.push(...arg.slice('--paths='.length).split(',').filter(Boolean));
+		} else if (arg.startsWith('-')) {
+			throw new Error(`Unknown option: ${arg}`);
+		} else {
+			opts.paths.push(arg);
+		}
+	}
+	return opts;
+}
+
+function printHelp() {
+	console.log(
+		`Usage: npx ${PACKAGE_NAME}-audit [options] [paths...]\n\n` +
+			`Audits a consuming app for stale local UI imports, invalid package subpaths,\n` +
+			`and local files that only mirror ${PACKAGE_NAME} exports.\n\n` +
+			`Options:\n` +
+			`  --fix             Rewrite known copied import paths to package imports\n` +
+			`  --paths=a,b       Comma-separated paths to scan\n` +
+			`  --json            Print machine-readable JSON\n` +
+			`  --help, -h        Show this message\n`,
+	);
+}
+
+async function exists(p) {
+	try {
+		await fs.access(p);
+		return true;
+	} catch {
+		return false;
+	}
+}
+
+async function walk(dir, files = []) {
+	const entries = await fs.readdir(dir, { withFileTypes: true });
+	for (const entry of entries) {
+		if (SKIP_DIRS.has(entry.name)) continue;
+		const full = path.join(dir, entry.name);
+		if (entry.isDirectory()) {
+			await walk(full, files);
+		} else if (entry.isFile() && CODE_EXTENSIONS.has(path.extname(entry.name))) {
+			files.push(full);
+		}
+	}
+	return files;
+}
+
+async function getScanFiles(cwd, requestedPaths) {
+	const roots = requestedPaths.length > 0 ? requestedPaths : DEFAULT_PATHS;
+	const files = [];
+	for (const relative of roots) {
+		const full = path.resolve(cwd, relative);
+		if (!(await exists(full))) continue;
+		const stat = await fs.stat(full);
+		if (stat.isDirectory()) {
+			await walk(full, files);
+		} else if (stat.isFile() && CODE_EXTENSIONS.has(path.extname(full))) {
+			files.push(full);
+		}
+	}
+	return [...new Set(files)].sort();
+}
+
+function getImportSpecifiers(source) {
+	const specifiers = [];
+	const patterns = [
+		/\bimport\s+(?:type\s+)?(?:[^'"]*?\s+from\s+)?['"]([^'"]+)['"]/g,
+		/\bexport\s+(?:type\s+)?[^'"]*?\s+from\s+['"]([^'"]+)['"]/g,
+		/\bimport\s*\(\s*['"]([^'"]+)['"]\s*\)/g,
+	];
+	for (const pattern of patterns) {
+		for (const match of source.matchAll(pattern)) specifiers.push(match[1]);
+	}
+	return specifiers;
+}
+
+function normalizePackageKey(specifier) {
+	if (specifier === PACKAGE_NAME) return '.';
+	if (!specifier.startsWith(`${PACKAGE_NAME}/`)) return null;
+	return `.${specifier.slice(PACKAGE_NAME.length)}`;
+}
+
+function packageImportIssue(specifier) {
+	const key = normalizePackageKey(specifier);
+	if (key === null) return null;
+	if (PUBLIC_EXPORTS.has(key)) return null;
+	return {
+		kind: 'invalid-package-import',
+		specifier,
+		message: `${specifier} is not a public ${PACKAGE_NAME} export`,
+	};
+}
+
+function mapOldSpecifier(specifier) {
+	const typographyPrefixes = [
+		'@/components/ui/base/typography',
+		'@/components/ui/typography',
+		'@/components/typography',
+	];
+	if (typographyPrefixes.some((prefix) => specifier === prefix || specifier.startsWith(`${prefix}/`))) {
+		return `${PACKAGE_NAME}/typography`;
+	}
+
+	const layerMappings = [
+		{ prefix: '@/components/ui/base/', target: 'base' },
+		{ prefix: '@/components/base/', target: 'base' },
+		{ prefix: '@/components/composed/', target: 'composed' },
+		{ prefix: '@/components/features/', target: 'features' },
+		{ prefix: '@/components/layout/', target: 'layout' },
+	];
+
+	for (const mapping of layerMappings) {
+		if (!specifier.startsWith(mapping.prefix)) continue;
+		const rest = specifier.slice(mapping.prefix.length);
+		const parts = rest.split('/').filter(Boolean);
+		if (parts.length === 0) continue;
+
+		if (mapping.target === 'base' && parts[0] === 'display' && parts[1] === 'metadata') {
+			return `${PACKAGE_NAME}/base/display/metadata`;
+		}
+
+		const candidate = `${PACKAGE_NAME}/${mapping.target}/${parts[0]}`;
+		if (PUBLIC_EXPORTS.has(normalizePackageKey(candidate))) return candidate;
+	}
+
+	if (specifier === '@/components/layout') return `${PACKAGE_NAME}/layout`;
+
+	return null;
+}
+
+function isKnownCopiedImport(specifier) {
+	return mapOldSpecifier(specifier) !== null;
+}
+
+function isMirrorFile(source) {
+	const withoutComments = source
+		.replace(/\/\*[\s\S]*?\*\//g, '')
+		.replace(/^\s*\/\/.*$/gm, '')
+		.trim();
+	if (!withoutComments) return false;
+
+	const statements = withoutComments
+		.split(';')
+		.map((statement) => statement.trim())
+		.filter(Boolean);
+	if (statements.length === 0) return false;
+
+	return statements.every((statement) =>
+		/^export\s+(?:type\s+)?(?:\{[\s\S]*\}|\*)\s+from\s+['"]admin-ui-starter-kit(?:\/[^'"]+)?['"]$/m.test(
+			statement,
+		),
+	);
+}
+
+function replaceSpecifiers(source) {
+	let changed = false;
+	const next = source.replace(
+		/(['"])(@\/components\/(?:ui\/base|ui\/typography|base|typography|composed|features|layout)(?:\/[^'"]*)?)\1/g,
+		(match, quote, specifier) => {
+			const replacement = mapOldSpecifier(specifier);
+			if (!replacement) return match;
+			changed = true;
+			return `${quote}${replacement}${quote}`;
+		},
+	);
+	return { changed, source: next };
+}
+
+async function audit(opts) {
+	const cwd = process.cwd();
+	const files = await getScanFiles(cwd, opts.paths);
+	const issues = [];
+	const fixedFiles = [];
+
+	for (const file of files) {
+		const source = await fs.readFile(file, 'utf8');
+		const relative = path.relative(cwd, file);
+		const specifiers = getImportSpecifiers(source);
+
+		for (const specifier of specifiers) {
+			if (isKnownCopiedImport(specifier)) {
+				issues.push({
+					kind: 'stale-local-import',
+					file: relative,
+					specifier,
+					suggested: mapOldSpecifier(specifier),
+					message: `${specifier} should import directly from ${PACKAGE_NAME}`,
+				});
+			}
+
+			const invalidPackageImport = packageImportIssue(specifier);
+			if (invalidPackageImport) {
+				issues.push({ ...invalidPackageImport, file: relative });
+			}
+		}
+
+		if (isMirrorFile(source)) {
+			issues.push({
+				kind: 'local-package-mirror',
+				file: relative,
+				message: 'local file only re-exports admin-ui-starter-kit; replace call-site imports directly',
+			});
+		}
+
+		if (opts.fix) {
+			const replacement = replaceSpecifiers(source);
+			if (replacement.changed) {
+				await fs.writeFile(file, replacement.source);
+				fixedFiles.push(relative);
+			}
+		}
+	}
+
+	return { filesScanned: files.length, issues, fixedFiles: [...new Set(fixedFiles)].sort() };
+}
+
+function printReport(result, opts) {
+	if (opts.json) {
+		console.log(JSON.stringify(result, null, 2));
+		return;
+	}
+
+	if (result.fixedFiles.length > 0) {
+		console.log(`Rewrote imports in ${result.fixedFiles.length} file(s):`);
+		for (const file of result.fixedFiles) console.log(`  - ${file}`);
+		console.log('');
+	}
+
+	if (result.issues.length === 0) {
+		console.log(`Admin UI audit passed (${result.filesScanned} files scanned).`);
+		return;
+	}
+
+	console.error(`Admin UI audit found ${result.issues.length} issue(s):`);
+	for (const issue of result.issues) {
+		const suggestion = issue.suggested ? ` -> ${issue.suggested}` : '';
+		console.error(`- ${issue.file}: ${issue.message}${suggestion}`);
+	}
+
+	if (!opts.fix) {
+		console.error('\nRun with --fix to rewrite known copied import paths.');
+	}
+}
+
+async function main() {
+	const opts = parseArgs(process.argv);
+	if (opts.help) {
+		printHelp();
+		return;
+	}
+
+	const first = await audit(opts);
+	if (!opts.fix || first.fixedFiles.length === 0) {
+		printReport(first, opts);
+		process.exit(first.issues.length > 0 ? 1 : 0);
+	}
+
+	const second = await audit({ ...opts, fix: false });
+	const merged = {
+		filesScanned: second.filesScanned,
+		issues: second.issues,
+		fixedFiles: first.fixedFiles,
+	};
+	printReport(merged, opts);
+	process.exit(second.issues.length > 0 ? 1 : 0);
+}
+
+main().catch((error) => {
+	if (error instanceof Error) {
+		console.error(`admin-ui-starter-kit-audit: ${error.message}`);
+	} else {
+		console.error(error);
+	}
+	process.exit(2);
+});

package/scripts/install-skill.mjs

@@ -1,16 +1,15 @@
 #!/usr/bin/env node
 /**
- * install-skill — consumer-facing installer for the
- * `component-library-rules` skill that ships inside the
- * `admin-ui-starter-kit` npm package.
+ * install-skill — consumer-facing installer for the AI skills that ship
+ * inside the `admin-ui-starter-kit` npm package.
  *
  * Run from a consumer project (after `npm install admin-ui-starter-kit`):
  *
- *   npx admin-ui-starter-kit-install-skill [--target=claude|agents|both] [--force]
+ *   npx admin-ui-starter-kit-install-skill [--skill=name|all] [--target=claude|agents|both] [--force]
  *
  * Default behaviour: copies the skill into BOTH
- *   <cwd>/.claude/skills/component-library-rules/
- *   <cwd>/.agents/skills/component-library-rules/
+ *   <cwd>/.claude/skills/<skill-name>/
+ *   <cwd>/.agents/skills/<skill-name>/
  *
  * The script is idempotent. It refuses to run inside the library itself
  * (the maintainer has `scripts/publish-skill.mjs` for that workflow).
@@ -20,18 +19,16 @@ import path from 'node:path';
 import readline from 'node:readline';
 import { fileURLToPath } from 'node:url';
 
-const SKILL_NAME = 'component-library-rules';
+const SKILL_NAMES = ['component-library-rules', 'admin-ui-consumer-migration'];
 const PACKAGE_NAME = 'admin-ui-starter-kit';
 
 const __filename = fileURLToPath(import.meta.url);
 // scripts/install-skill.mjs lives at <pkg>/scripts/, so package root is one up.
 const PACKAGE_ROOT = path.resolve(path.dirname(__filename), '..');
-const SOURCE = path.join(PACKAGE_ROOT, '.agents', 'skills', SKILL_NAME);
-
 const CWD = process.cwd();
 
 function parseArgs(argv) {
-	const opts = { target: 'both', force: false, help: false };
+	const opts = { target: 'both', skill: 'all', force: false, help: false };
 	for (const arg of argv.slice(2)) {
 		if (arg === '--force' || arg === '-f') {
 			opts.force = true;
@@ -44,6 +41,15 @@ function parseArgs(argv) {
 				process.exit(2);
 			}
 			opts.target = value;
+		} else if (arg.startsWith('--skill=')) {
+			const value = arg.slice('--skill='.length);
+			if (value !== 'all' && !SKILL_NAMES.includes(value)) {
+				console.error(
+					`✖ Invalid --skill=${value}. Expected one of: all, ${SKILL_NAMES.join(', ')}.`,
+				);
+				process.exit(2);
+			}
+			opts.skill = value;
 		} else {
 			console.error(`✖ Unknown argument: ${arg}`);
 			opts.help = true;
@@ -55,8 +61,9 @@ function parseArgs(argv) {
 function printHelp() {
 	console.log(
 		`Usage: npx ${PACKAGE_NAME}-install-skill [options]\n\n` +
-			`Installs the "${SKILL_NAME}" skill into the current project.\n\n` +
+			`Installs ${PACKAGE_NAME} AI skills into the current project.\n\n` +
 			`Options:\n` +
+			`  --skill=all|${SKILL_NAMES.join('|')}   Which skill to install (default: all)\n` +
 			`  --target=claude|agents|both   Where to install (default: both)\n` +
 			`  --force, -f                   Overwrite existing skill dir without prompting\n` +
 			`  --help, -h                    Show this message\n`,
@@ -107,7 +114,7 @@ function confirm(question) {
 	});
 }
 
-async function installInto(targetDir, force) {
+async function installInto(skillName, sourceDir, targetDir, force) {
 	// Safety: the only thing we ever delete is the existing skill dir at the
 	// exact target path. We never touch the parent directory or siblings.
 	if (await exists(targetDir)) {
@@ -120,8 +127,8 @@ async function installInto(targetDir, force) {
 		}
 		await fs.rm(targetDir, { recursive: true, force: true });
 	}
-	const count = await copyDir(SOURCE, targetDir);
-	console.log(`  ✓ Installed ${SKILL_NAME} → ${targetDir} (${count} files)`);
+	const count = await copyDir(sourceDir, targetDir);
+	console.log(`  ✓ Installed ${skillName} → ${targetDir} (${count} files)`);
 	return count;
 }
 
@@ -143,31 +150,38 @@ async function main() {
 		process.exit(2);
 	}
 
-	if (!(await exists(SOURCE))) {
-		console.error(
-			`✖ Source skill not found at ${SOURCE}\n` +
-				`  This usually means the ${PACKAGE_NAME} package is missing the skill files.\n` +
-				`  Try reinstalling: npm install ${PACKAGE_NAME}@latest`,
-		);
-		process.exit(1);
-	}
+	const skillNames = opts.skill === 'all' ? SKILL_NAMES : [opts.skill];
 
-	const targets = [];
-	if (opts.target === 'claude' || opts.target === 'both') {
-		targets.push(path.join(CWD, '.claude', 'skills', SKILL_NAME));
-	}
-	if (opts.target === 'agents' || opts.target === 'both') {
-		targets.push(path.join(CWD, '.agents', 'skills', SKILL_NAME));
-	}
+	console.log(`Installing ${skillNames.length === 1 ? `"${skillNames[0]}"` : 'AI skills'} from ${PACKAGE_NAME}\n`);
 
-	console.log(`Installing "${SKILL_NAME}" from ${PACKAGE_NAME}\n`);
-	for (const target of targets) {
-		try {
-			await installInto(target, opts.force);
-		} catch (err) {
-			console.error(`  ✖ ${target}`);
-			console.error(`    ${err instanceof Error ? err.message : String(err)}`);
+	for (const skillName of skillNames) {
+		const source = path.join(PACKAGE_ROOT, '.agents', 'skills', skillName);
+		if (!(await exists(source))) {
+			console.error(
+				`✖ Source skill not found at ${source}\n` +
+					`  This usually means the ${PACKAGE_NAME} package is missing the skill files.\n` +
+					`  Try reinstalling: npm install ${PACKAGE_NAME}@latest`,
+			);
 			process.exitCode = 1;
+			continue;
+		}
+
+		const targets = [];
+		if (opts.target === 'claude' || opts.target === 'both') {
+			targets.push(path.join(CWD, '.claude', 'skills', skillName));
+		}
+		if (opts.target === 'agents' || opts.target === 'both') {
+			targets.push(path.join(CWD, '.agents', 'skills', skillName));
+		}
+
+		for (const target of targets) {
+			try {
+				await installInto(skillName, source, target, opts.force);
+			} catch (err) {
+				console.error(`  ✖ ${target}`);
+				console.error(`    ${err instanceof Error ? err.message : String(err)}`);
+				process.exitCode = 1;
+			}
 		}
 	}