admin-ui-starter-kit 0.1.1 → 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.
@@ -784,6 +794,11 @@ from `admin-ui-starter-kit/base/display/metadata` so consumers do not need to
 load the broader `base/display` barrel. Never document file-level paths such as
 `admin-ui-starter-kit/base/display/metadata/metadata-list`.
 
+The package `exports` map must list every public family as an exact key:
+`./base/buttons`, `./features/comments`, `./layout/page`, etc. Do not use
+wildcard exports such as `./base/*`, and do not use null wildcard blockers such
+as `./base/*/*`; bundlers can treat those patterns inconsistently.
+
 Base UI-backed triggers use Base UI's `render` prop, not Radix's `asChild`.
 For dropdown menus, write:
 

package/.agents/skills/component-library-rules/references/import-paths.md

@@ -41,6 +41,12 @@ Do not use or document broad `admin-ui-starter-kit/base`,
 They are intentionally not exported so optional peers stay isolated to the exact
 component family that needs them.
 
+`package.json` must publish those component families as explicit exact keys,
+not wildcard package exports. For example, publish `./base/buttons` and
+`./features/comments`, not `./base/*` or `./features/*`. Do not use null
+wildcard blockers such as `./base/*/*`; exact exports already keep undocumented
+nested paths private and avoid bundler resolver drift.
+
 Most public boundaries are first-level families. A nested subfamily is public
 only when it has an explicit `package.json` export and `vite.lib.config.ts`
 entry. Current intentional nested subfamily:

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
 
@@ -117,8 +119,11 @@ Hard rules (full detail in the skill):
 
 - **Entry**: `src/preview/PreviewApp.tsx` (showcase) and the public
   `package.json` `exports` map (`.`, `./ui-provider`,
-  `./typography`, `./base/*`, `./composed/*`, `./features/*`,
-  `./layout`, `./layout/*`, `./lib/strings`, `./lib/utils`).
+  `./typography`, exact `./base/<family>`, exact
+  `./composed/<family>`, exact `./features/<feature>`, `./layout`,
+  exact `./layout/<family>`, `./lib/strings`, `./lib/utils`).
+  The exports map must use exact keys, not wildcard/null blocker
+  patterns.
 - **`<UIProvider>`** (`@/lib/ui-provider`) — the **only** library-level
   provider. Holds opinionated display defaults (`money.defaultCurrency`,
   `dates.weekStartsOn`, `badge.defaultSize`, `card.defaultPadding`, …).

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
@@ -40,6 +45,10 @@ Only documented nested subfamily entrypoints are public. For example,
 `admin-ui-starter-kit/base/display/metadata` so consumers do not need the
 broader `base/display` barrel or its optional peers.
 
+The package publishes exact export keys, not wildcard package exports. If an
+import path is not documented or listed in `package.json` `exports`, treat it as
+private even when a declaration file happens to exist under `dist/`.
+
 The root entrypoint is intentionally small:
 
 ```tsx
@@ -136,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
@@ -112,8 +117,8 @@ You cannot delete or overwrite a published version. Always dry-run first.
 | --- | --- |
 | `npm publish` says "private package" | Remove `"private": true` from `package.json` |
 | `npm publish` says "name not available" | Someone took the name; pick a new one |
-| Consumers report "module not found" for `admin-ui-starter-kit/foo` | Add `./foo` to the `exports` map AND `vite.lib.config.ts` entries; rebuild and republish |
-| Consumers report "module not found" for a nested component path | Only explicitly exported nested subfamilies are public. Add an exact `exports` entry plus `vite.lib.config.ts` entry, or document the first-level family import. |
+| Consumers report "module not found" for `admin-ui-starter-kit/foo` | Add an exact `./foo` entry to the `exports` map AND `vite.lib.config.ts`; rebuild and republish |
+| Consumers report "module not found" for a nested component path | Only explicitly exported nested subfamilies are public. Add an exact `exports` entry plus `vite.lib.config.ts` entry, or document the first-level family import. Do not add wildcard or null-blocker exports. |
 | Consumers must upgrade `lucide-react` | Expected for apps still on lucide v0; this package has a lucide v1 peer. |
 | Published bundle has stale code | Confirm `prepublishOnly` ran; check `dist/` mtime; bump patch and republish |
 | `peer dep warning: <pkg> not installed` for an optional peer | Verify the entry is in `peerDependenciesMeta.optional` block; consumer can ignore |