admin-ui-starter-kit 0.1.4 → 0.4.3

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

@@ -28,8 +28,8 @@ component file.
 
 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`.
+3. Replace repeated action/list rows with `Item`; replace label/value facts with `MetadataList`.
+4. Replace form rows with `FormField` / `ControlledFormField`, and use package field primitives or comboboxes inside them.
 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
@@ -50,8 +50,13 @@ Use:
 ```tsx
 import { Button } from 'admin-ui-starter-kit/base/buttons';
 import { Text } from 'admin-ui-starter-kit/typography';
+import { Item } from 'admin-ui-starter-kit/base/item';
 import { MetadataList } from 'admin-ui-starter-kit/base/display/metadata';
+import { ControlledFormField, FormField, Input, PasswordInput, SlugField } from 'admin-ui-starter-kit/base/forms';
+import { EnhancedCombobox } from 'admin-ui-starter-kit/base/combobox';
+import { SchemaForm, type SchemaFormSchema, type SchemaFormValues } from 'admin-ui-starter-kit/features/schema-form';
 import { Comments } from 'admin-ui-starter-kit/features/comments';
+import { MediaLibraryDialog, MediaResourceGallery } from 'admin-ui-starter-kit/features/media-library';
 ```
 
 Do not use:
@@ -126,10 +131,279 @@ Review the diff before deleting local folders.
 | 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` |
+| Schema-driven settings/config forms | `admin-ui-starter-kit/features/schema-form` |
+| Generated read-only slug | `SlugField` from `admin-ui-starter-kit/base/forms` |
+| Password with reveal button | `PasswordInput` from `admin-ui-starter-kit/base/forms` |
+| Searchable selects | `admin-ui-starter-kit/base/combobox` |
 | Date pickers | `admin-ui-starter-kit/base/date-pickers` |
 | Tables | `admin-ui-starter-kit/base/table` |
 | Filters | `admin-ui-starter-kit/features/filters` |
 | Comments | `admin-ui-starter-kit/features/comments` |
+| Media picker / product gallery field | `admin-ui-starter-kit/features/media-library` |
 | 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` |
+
+## Selection rules
+
+Use `Item` first for repeated rows with identity, media, a title/description
+stack, a click target, or trailing actions. Use `MetadataList` only for
+label/value facts describing one entity. Use `FormField` /
+`ControlledFormField` for every editable label + control + hint/error row.
+
+Typography should come from `admin-ui-starter-kit/typography`: `Text`,
+`Heading`, `Label`, and `TextLink`. Do not keep local `text-xs`,
+`text-muted-foreground`, or `font-semibold` spans when a package typography
+primitive can express the same intent.
+
+For `react-hook-form`, `ControlledFormField` renders the error text. Pass the
+render-prop `invalid` value to the inner field or `EnhancedCombobox`; use the
+control-level `error` prop only when the control is not wrapped by
+`FormField`.
+
+## Forms And Field Primitives
+
+When building forms, use the package's row wrapper and field primitives together:
+`FormField` for presentational forms, `ControlledFormField` for
+`react-hook-form`, and field controls from `admin-ui-starter-kit/base/forms`.
+Searchable comboboxes come from `admin-ui-starter-kit/base/combobox`, but still
+belong inside the same form row wrappers.
+
+If the component index is available, read
+`.agents/skills/component-library-rules/references/components/base__forms.md`
+for the full props/examples reference before rebuilding local form controls.
+
+Field selection:
+
+- `Input` / `Textarea` — ordinary text.
+- `PasswordInput` — password values that need a show/hide icon button with
+  consistent sizing and aria labels.
+- `SlugField` — generated read-only slugs derived from another value. It wraps
+  package `Input`, slugifies `value`, and submits normally when `name` is set.
+- `DecimalInput`, `PercentageInput`, `MoneyInput`, `CurrencyInput`,
+  `WeightInput`, `DimensionsInput` — numeric or unit-aware values.
+- `Select` / `RichSelect` — finite option sets.
+- `EnhancedCombobox` — searchable, async, grouped, or creatable options.
+- `Switch`, `Checkbox`, `ToggleField`, `SwitchCard` — boolean state.
+- `PillRadioGroup`, `ListRadioGroup`, `CardRadioGroup`, `CardCheckboxGroup` —
+  richer single/multi-choice options.
+- `DateTimeInput`, `TimePicker`, `TagsInput`, `PhoneInput`,
+  `CoordinatesInput` — domain-specific values; do not rebuild them from raw
+  inputs.
+- `FileUpload`, `ImageUpload`, `AvatarUpload`, `Dropzone`, `MediaGallery`,
+  `UploadTray`, `UploadProgressList` — direct upload fields. Use
+  `features/media-library` when the user chooses from an asset library.
+- `KeyValueEditor`, `StringRepeater`, `ObjectRepeater`, `List`, and localized
+  fields — nested/repeated values; the repeater and localized families are the
+  RHF-coupled exceptions.
+
+Keep validation schemas, submission, route changes, translations, async option
+fetching, slug uniqueness checks, and slug conflict resolution in the consuming
+app/API.
+
+Presentational example:
+
+```tsx
+import { useState } from 'react';
+import { FormField, Input, PasswordInput, SlugField } from 'admin-ui-starter-kit/base/forms';
+
+export function ProductBasicsForm() {
+	const [title, setTitle] = useState('Summer Collection: Salt & Pepper Set');
+
+	return (
+		<div className="grid gap-4">
+			<FormField label="Title" required hint="Used to generate the public URL.">
+				<Input value={title} onChange={(event) => setTitle(event.target.value)} />
+			</FormField>
+
+			<FormField label="Slug" hint="Read-only value submitted with the form.">
+				<SlugField
+					name="slug"
+					value={title}
+					startAddon="/"
+					aria-label="Generated slug"
+				/>
+			</FormField>
+
+			<FormField label="Password">
+				<PasswordInput name="password" autoComplete="current-password" />
+			</FormField>
+		</div>
+	);
+}
+```
+
+`react-hook-form` example:
+
+```tsx
+import { ControlledFormField, Input } from 'admin-ui-starter-kit/base/forms';
+import { EnhancedCombobox } from 'admin-ui-starter-kit/base/combobox';
+
+<ControlledFormField name="email" control={form.control} label="Email">
+	{(field, _error, invalid) => (
+		<Input {...field} type="email" invalid={invalid} autoComplete="email" />
+	)}
+</ControlledFormField>
+
+<ControlledFormField name="collectionId" control={form.control} label="Collection">
+	{(field, _error, invalid) => (
+		<EnhancedCombobox
+			items={collections}
+			selectedValue={collections.find((item) => item.id === field.value) ?? null}
+			onSelectedValueChange={(item) => field.onChange(item?.id ?? null)}
+			searchValue={collectionSearch}
+			onSearchValueChange={setCollectionSearch}
+			getItemKey={(item) => item.id}
+			getItemLabel={(item) => item.name}
+			invalid={invalid}
+			strings={{ placeholder: 'Select collection' }}
+		/>
+	)}
+</ControlledFormField>
+```
+
+## Schema-Driven Forms
+
+Use `features/schema-form` when a consuming app already has backend-provided
+field definitions, tenant settings, integration configuration, or any admin
+schema that must render either as one cohesive form or as section cards. Do not
+use it for bespoke domain forms with hand-authored layout; those should stay on
+`FormField`, `ControlledFormField`, and the base field primitives.
+
+```tsx
+import { useState } from 'react';
+import {
+	SchemaForm,
+	type SchemaFormSchema,
+	type SchemaFormValues,
+} from 'admin-ui-starter-kit/features/schema-form';
+
+const schema: SchemaFormSchema = {
+	title: 'Store settings',
+	fields: [
+		{ key: 'storeName', label: 'Store name', required: true },
+		{ key: 'timezone', type: 'select', label: 'Timezone', options: timezones },
+		{ key: 'tax', type: 'decimal', label: 'Tax rate', width: 'half' },
+	],
+};
+
+export function StoreSettingsForm({ initialValues, serverErrors }) {
+	const [values, setValues] = useState<SchemaFormValues>(initialValues);
+
+	return (
+		<SchemaForm
+			schema={schema}
+			value={values}
+			errors={serverErrors}
+			layout="cards"
+			onValueChange={setValues}
+			onSubmit={(nextValues) => router.post(route('settings.update'), nextValues)}
+			strings={{ submitLabel: t('actions.save') }}
+		/>
+	);
+}
+```
+
+Migration rules:
+
+- Map app schema records into `SchemaFormSchema`; do not leak app ambient types
+  into the package import surface.
+- Keep validation libraries, server errors, API calls, route changes, and
+  translations in the app. Wire them through `validate`, `errors`, `onSubmit`,
+  `onError`, and `strings`.
+- Use `layout="form"` for one cohesive card and `layout="cards"` for separated
+  schema sections.
+- Use `renderField`, `renderSection`, or `type: 'custom'` for app-specific
+  controls, permission-aware rows, or framework-bound widgets.
+- If the form needs full `react-hook-form` controller semantics, keep it on
+  `ControlledFormField` and base fields or build an app-owned adapter around
+  `SchemaForm`; do not fork or mirror the package feature.
+
+## Media Library And API Wiring
+
+Use `features/media-library` for admin media picking, product media fields, CMS
+asset libraries, campaign files, upload staging, and metadata editing.
+
+```tsx
+import {
+	MediaLibrary,
+	MediaLibraryDialog,
+	MediaResourceGallery,
+	useMediaLibrary,
+	type MediaLibraryItem,
+	type MediaLibraryFetchParams,
+	type MediaLibraryAccessors,
+} from 'admin-ui-starter-kit/features/media-library';
+```
+
+Use `MediaResourceGallery` for the form field or resource summary already on the
+page. Its default `layout="field"` gives the product-gallery shape: cover tile,
+attached media tiles, inline add tile, reorder/remove hooks, and a simple
+`onAdd` callback that the app can wire to a picker. Use `layout="grid"` or
+`layout="list"` when filenames, position, size, and row actions need to remain
+visible.
+
+Use `MediaLibraryDialog` when the user needs to pick from a modal library. It is
+already backed by the package overlays; do not wrap it in another local dialog.
+Use `MediaLibrary` for embedded asset-management pages or settings panels.
+
+Keep every API and storage concern in the consuming app:
+
+- `fetcher(params: MediaLibraryFetchParams)` calls the app API and returns
+  `{ items, total }` or an item array.
+- `accessors` maps app-owned media records to the package shape without
+  reshaping backend responses. Provide `getId`, `getName`, `getType`, `getSrc`,
+  `getAlt`, `getSize`, `getWidth`, `getHeight`, `getDuration`,
+  `getCollection`, `getTags`, `getPublic`, `getUploadedAt`, and
+  `getUsageCount` as needed.
+- `onUpload(files, options, helpers)` uploads through the app API. Use
+  `helpers.setProgress(fileId, percent)` and
+  `helpers.setFileStatus(fileId, status, error)` when the transport reports
+  progress or failures.
+- `onItemUpdate(item, patch)` persists alt text, collection, tags, and public
+  visibility changes.
+- `onItemDelete(item)` deletes or detaches media through the app API.
+- `value` / `onValueChange` keep selection controlled by form state.
+- `onConfirm(items, ids)` commits a picker result to the app form or resource.
+
+Default type filters are `All`, `Images`, and `Videos`. Add files explicitly
+with `typeFilters={['all', 'image', 'video', 'file']}` when the product surface
+allows document assets.
+
+All user-facing text remains overrideable through `strings`. Use `slots` and
+`renderItem` / `renderDetail` for app-specific cards, empty states, detail
+fields, or toolbar actions instead of forking the feature.
+
+Example product media flow:
+
+```tsx
+const [mediaIds, setMediaIds] = useState<string[]>(product.mediaIds);
+const [pickerOpen, setPickerOpen] = useState(false);
+
+<MediaResourceGallery
+	items={productMedia}
+	primaryId={product.coverMediaId}
+	onPrimaryChange={(id) => productApi.setCover(id)}
+	onRemove={(id) => setMediaIds((current) => current.filter((value) => value !== id))}
+	onAdd={() => setPickerOpen(true)}
+/>;
+
+<MediaLibraryDialog
+	open={pickerOpen}
+	onOpenChange={setPickerOpen}
+	items={libraryItems}
+	value={mediaIds}
+	onValueChange={setMediaIds}
+	onConfirm={(_items, ids) => setMediaIds(ids)}
+	onUpload={(files, options, helpers) => mediaApi.upload(files, options, helpers)}
+	onItemUpdate={(item, patch) => mediaApi.update(item.id, patch)}
+	onItemDelete={(item) => mediaApi.delete(item.id)}
+	dialogTitle="Add media"
+	dialogDescription="Pick from the library, or upload new files"
+/>;
+```
+
+If the app uses Inertia, TanStack Query, React Router, Next.js, signed CDN URLs,
+or tenant-aware storage, wire those in `fetcher`, callbacks, and call-site link
+renderers. Do not add those dependencies to the package import path or create a
+local mirror of the media components.

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

@@ -11,14 +11,14 @@ This is a reusable component library. Code lives in many projects via this packa
 
 ## Goal & target distribution
 
-This codebase is on a path to becoming a **standalone, publishable npm package** that re-exports shadcn primitives, the `base/` wrappers, and the `composed/`/`features/` layers — centralized so every consuming app upgrades from one place.
+This codebase is on a path to becoming a **standalone, publishable npm package** that keeps shadcn primitives as an internal source layer and publicly re-exports the `base/` wrappers plus the `composed/`/`features/` layers — centralized so every consuming app upgrades from one place.
 
 That goal drives every other rule:
 - Components must be **framework-agnostic** by default (Inertia, Next.js, plain Vite, Remix, …).
 - Internal strings must be **overridable** so consumers wire their own i18n.
 - Visual tokens must be **theme-able** through CSS custom properties so consumers can rebrand.
 - Internal partials must be **exported and composable** so consumers can build custom layouts on top.
-- Direct imports of peer dependencies (`@inertiajs/*`, `@tanstack/react-query`, `next/*`, `vite-bundled-i18n/*`, `ziggy-js`, `react-router*`) belong **only** in opt-in adapter folders, never in the default export path.
+- Direct imports of framework/data/i18n peer dependencies (`@inertiajs/*`, `@tanstack/react-query`, `next/*`, `vite-bundled-i18n/*`, `ziggy-js`, `react-router*`) do **not** belong in this library. Consumers wire those integrations at their own call sites via callbacks, fetchers, render props, `strings`, and wrapper components.
 
 When in doubt, ask: "Would this work for a brand-new consumer who installed `admin-ui-starter-kit` from npm and has no idea what Inertia is?" If not, refactor.
 
@@ -115,7 +115,7 @@ 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.
-- **Tailwind v4 + shadcn token architecture** → tokens live in `src/App.css` under `@theme inline { … }` (and the `:root` / `.dark` blocks for the variable values themselves). Read the comment blocks at the top of `App.css` before editing. Do **not** move design tokens into runtime CSS or component-level `style={}` props.
+- **Tailwind v4 + shadcn token architecture** → `src/App.css` is the Tailwind/import entrypoint. Shadcn palette, radius, shadow, and dark/light tokens live in `src/css/themes/default.css`; typography scale, density, component knobs, and base resets live in `src/css/defaults.css`. Read the comment blocks in those CSS files before editing. Do **not** move design tokens into runtime CSS or component-level `style={}` props.
 
 ## 1. Never modify shadcn primitives directly
 
@@ -129,6 +129,11 @@ The bare `@/components/ui/<primitive>` path is allowed **only** for base wrapper
 
 Touching shadcn primitives directly breaks the abstraction layer and means the next shadcn upgrade overwrites your work.
 
+Raw shadcn primitives are not public package subpaths. Do not document
+`admin-ui-starter-kit/ui/<primitive>` imports unless the package export map is
+intentionally changed in the same work; today consumers use the matching
+`base/`, `layout/`, `composed/`, or `features/` entrypoint.
+
 **Package-owned non-shadcn "primitives".** A few units of UI in this library are large, package-owned, opinionated implementations (Mapbox/Leaflet adapter, Google Places autocomplete) that are **not** shadcn primitives. They live in `src/components/base/` directly (e.g. `base/map/map.tsx`, `base/map/place-autocomplete.tsx`), not in `ui/`. They follow the same framework-agnostic / token-driven / strings-overridable rules as everything else in `base/`. Don't recreate them in `ui/` — `ui/` is shadcn-only.
 
 ## 2. The component layer order is sacred
@@ -463,7 +468,7 @@ next reader doesn't think it was forgotten.
 - `muted` / `muted-foreground` — neutral grays
 
 ### Adding new variants
-If you need a new colour variant in `App.css` (e.g. a "premium" gold):
+If you need a new colour variant in `src/css/themes/default.css` (e.g. a "premium" gold):
 - Add the variable in BOTH the `:root` light and `.dark` dark scope
 - Add `--color-<name>: var(--<name>)` in `@theme`
 - **Comment it** with what it's for and where it's used
@@ -655,13 +660,13 @@ Two-line rule: if a consumer asks "how do I customize X" and the answer requires
 
 ## 14. Theming surface — beyond shadcn tokens
 
-Shadcn tokens (`--background`, `--foreground`, `--card`, etc.) are the foundation. Beyond them, expose component-level CSS variables in `App.css` `@theme` so consumers can rebrand without forking:
+Shadcn tokens (`--background`, `--foreground`, `--card`, etc.) are the foundation. Beyond them, expose component-level CSS variables in `src/css/defaults.css` under `@theme inline` or `:root` so consumers can rebrand without forking:
 
 - **Typography scale** — `--text-xxs`, `--text-xs`, `--text-sm`, `--text-base`, `--text-lg`. The `Text`/`Heading` components read from these, so a consumer can resize the entire library at `:root` for denser/sparser dashboards.
-- **Density** — `--row-py-tight`, `--row-py-default`, `--row-py-loose`. List rows in filters/global-search/comments/analytics consume these.
+- **Density** — `--row-py`. List rows in command, accordion, tags-input, global-search, and similar list/menu surfaces consume this through `py-(--row-py)`.
 - **Component-specific** — when a single component reasonably needs override (`--filter-chip-h`, `--popover-content-pad`), add a variable and document where it's read.
 
-Document each new variable in `App.css` with a comment listing the consuming components.
+Document each new variable in the owning CSS file with a comment listing the consuming components.
 
 ## 15. Hooks colocation
 
@@ -780,6 +785,7 @@ Published package imports use exact subpaths, not broad aggregates:
 - ❌ `admin-ui-starter-kit/base`
 - ❌ `admin-ui-starter-kit/composed`
 - ❌ `admin-ui-starter-kit/features`
+- ❌ `admin-ui-starter-kit/ui/tabs`
 - ❌ `admin-ui-starter-kit/base/display/metadata/metadata-list`
 
 The root package entrypoint (`admin-ui-starter-kit`) must stay optional-peer-free:
@@ -874,7 +880,7 @@ Base-layer references:
 
 Token-level references:
 
-- **`src/App.css`** — typography font-size variables (`--text-xxs/xs/sm/base/lg`), density tokens (`--row-py-tight/default/loose`), component knobs (`--popover-content-pad`). The `.text-*` utility overrides further down route Tailwind through these variables so consumers can override at `:root`.
+- **`src/App.css` + `src/css/themes/default.css` + `src/css/defaults.css`** — `App.css` is the import entrypoint; `themes/default.css` holds the shadcn palette/radius/shadow mapping; `defaults.css` holds typography font-size variables (`--text-xxs/xs/sm/base/lg`), the density token (`--row-py`), and component knobs (`--popover-content-pad`). Tailwind routes utilities through these variables so consumers can override at `:root`.
 - **`composed/analytics/analytics.strings.ts`** — strings file shape used across composed surfaces.
 
 If a new feature you're adding doesn't structurally resemble at least one of these, you're probably off-pattern. Stop and re-read the rule that applies.
@@ -984,7 +990,7 @@ See [`src/components/CONVENTIONS.md` §8](../../../src/components/CONVENTIONS.md
 - ❌ "I'll inline a custom popover header here." → Use `Text` + `Heading` + a `border-b` div, with proper paddings.
 - ❌ "The screenshot is too zoomed in to compare." → It's still your problem; fix it for the actual rendered DPI.
 - ❌ "I'll wrap the icon in a `bg-muted` square." → Plain icon usually reads better; only add a container when it's load-bearing.
-- ❌ "I'll bypass the design tokens with a hex." → Use semantic tokens; add a new variant in App.css with a comment if you genuinely need one.
+- ❌ "I'll bypass the design tokens with a hex." → Use semantic tokens; add a new variant in the owning theme/defaults CSS file with a comment if you genuinely need one.
 - ❌ "I'll hardcode 'Cancel' here, it's just temp." → It will not be temp. Use defaultStrings.
 - ❌ "Let me make this row super tight at `py-0.5`." → That's cramped. `py-1.5` minimum unless explicitly compact.
 - ❌ "I'll just `import { useQuery } from '@tanstack/react-query'`." → It's a peer-dep. Accept a `fetcher` prop. Adapter folders no longer exist; the consumer wires their query lib at the call site.

package/.agents/skills/component-library-rules/references/audit-followups.md

@@ -124,7 +124,7 @@ provider, two different defaults. Pick one (recommend `'sm'`).
 - `phone-input.tsx:305,344` — Use `--form-element-height` CSS
   variable; nothing else in the folder does. Either kill the variable
   usage and route through `formControlSizeClasses`, or document the
-  variable in `App.css` and standardise.
+  variable in `src/css/defaults.css` and standardise.
 
 ### [L] Raw `<button>` instead of `<Button>` (rule 5)
 
@@ -163,7 +163,7 @@ vs `/30`) drift in the same pass.
 ### [H] Drive every list-row from `--row-py` density token
 
 Three components (`base/command`, `global-search-result-row`, the
-density-token comment block in `App.css`) honour the token; ten others
+density-token comment block in `src/css/defaults.css`) honour the token; ten others
 inline `py-1.5` / `py-2`:
 
 - `base/navigation/side-nav.tsx:110,151`
@@ -206,7 +206,7 @@ pass.
 ### [M] Tone-token table (`--tone-bg-soft / -default / -strong`)
 
 `bg-success/{5,10,15,20}` is chosen ad-hoc per component. Codify three
-levels in `App.css` (`--tone-bg-soft / -default / -strong`) and have
+levels in `src/css/defaults.css` (`--tone-bg-soft / -default / -strong`) and have
 `IconBadge`, `Badge`, `notification-banner`, `metric.tsx` colorScheme,
 `ai-confirmation`, `dialog/drawer alert variants` read the same
 variable. Eliminates drift across ~10 components.
@@ -218,7 +218,7 @@ raw Tailwind palette classes (`bg-red-500`, `bg-orange-500`, …) for
 event "color" tokens (multi-series legend — legitimate exception
 territory). Same in `composed/cards/giftcard-card/types.ts:121-123`.
 
-Ship: introduce CSS variables in `App.css`
+Ship: introduce CSS variables in `src/css/themes/default.css`
 (`--event-color-red`, `--event-color-blue`, … or
 `--multi-series-N`), document the legend semantics, and reference them
 from the calendar / giftcard color maps so consumers can rebrand.

package/.agents/skills/component-library-rules/references/base-wrapper.md

@@ -2,6 +2,20 @@
 
 Open this when adding a new wrapper around an `@/components/ui/<primitive>` shadcn component.
 
+## Adding an internal shadcn primitive
+
+Install the raw primitive with:
+
+```bash
+npx shadcn@latest add <primitive>
+```
+
+The generated file lands in `src/components/ui/<primitive>.tsx`. Treat that
+file as shadcn-managed output: do not restyle it to match the library voice,
+and do not expose it as `admin-ui-starter-kit/ui/<primitive>`. Consumers get a
+public API only after you add or update a `base/`, `layout/`, `composed/`, or
+`features/` wrapper and wire the exact package export.
+
 ## When to wrap
 
 Wrap a shadcn primitive in `base/` when **any** of these are true:
@@ -109,7 +123,7 @@ Before adding a new wrapper, check if one exists:
 | `base/command/` | `ui/command` |
 | `base/popover/` | `ui/popover` |
 | `base/popover-menu/` | `popover` + `command` |
-| `base/navigation/` | `ui/dropdown-menu`, `ui/breadcrumb`, segmented `ui/tabs`, `ui/sidebar` |
+| `base/navigation/` | `ui/dropdown-menu`, `ui/breadcrumb`, segmented `ui/tabs` |
 | `base/forms/` | `ui/input`, `ui/select`, `ui/textarea`, `ui/checkbox`, `ui/switch`, `ui/radio-group`, `ui/slider` |
 | `base/date-pickers/` | `ui/calendar` |
 | `base/toaster/` | `ui/sonner` |
@@ -117,11 +131,17 @@ Before adding a new wrapper, check if one exists:
 | `base/table/` | `ui/table` |
 | `base/event-calendar/` | `ui/calendar` (richer compositions) |
 | `base/map/` | `ui/map` |
+| `base/carousel/` | `ui/carousel` |
+| `base/sheet/` | `ui/sheet` |
+| `base/sidebar/` | `ui/sidebar` |
 
 Currently NOT wrapped (consider adding when you encounter inlined usage in 2+ places):
-- `ui/sheet` — only `layout/sidebar` reaches into it
-- `ui/sidebar` — only `layout/sidebar` reaches into it
-- `ui/hover-card`, `ui/context-menu`, `ui/collapsible` — only used by other wrappers internally
+- `ui/alert-dialog`, `ui/drawer` — prefer `features/overlays` for the public API.
+- `ui/aspect-ratio`, `ui/direction`, `ui/field`, `ui/input-otp`, `ui/kbd`,
+  `ui/label`, `ui/menubar`, `ui/native-select`, `ui/navigation-menu`,
+  `ui/resizable` — installed as internal shadcn primitives; add a wrapper
+  before using them from non-`ui` layers.
+- `ui/hover-card`, `ui/context-menu`, `ui/collapsible` — only used by other wrappers internally.
 
 ## Don'ts