openadmin-dev 0.7.8__tar.gz → 0.7.11__tar.gz

{openadmin_dev-0.7.8 → openadmin_dev-0.7.11}/.github/actions/format/action.yml

@@ -6,5 +6,8 @@ runs:
     - uses: astral-sh/setup-uv@v4
       with:
         enable-cache: true
+    - uses: oven-sh/setup-bun@v2
+    - shell: bash
+      run: cd client && bun install --frozen-lockfile
     - shell: bash
       run: make check/format

{openadmin_dev-0.7.8 → openadmin_dev-0.7.11}/.github/actions/lint/action.yml

@@ -6,5 +6,8 @@ runs:
     - uses: astral-sh/setup-uv@v4
       with:
         enable-cache: true
+    - uses: oven-sh/setup-bun@v2
+    - shell: bash
+      run: cd client && bun install --frozen-lockfile
     - shell: bash
       run: make check/lint

{openadmin_dev-0.7.8 → openadmin_dev-0.7.11}/Makefile

@@ -3,19 +3,24 @@ fix/license:
 	@ uv run reuse annotate --license AGPL-3.0-or-later --copyright "OpenAdmin" --recursive --skip-unrecognised openadmin/
 	@ uv run reuse annotate --license AGPL-3.0-or-later --copyright "OpenAdmin" --recursive --skip-unrecognised tests/
 	@ uv run reuse annotate --license AGPL-3.0-or-later --copyright "OpenAdmin" --recursive --skip-unrecognised examples/
+	@ uv run reuse annotate --license AGPL-3.0-or-later --copyright "OpenAdmin" --recursive --skip-unrecognised $$(find client/src -mindepth 1 -maxdepth 1 ! -name assets)
 
 fix/format:
+	@ cd client && bun run fix:format
 	@ uv run ruff format .
 
 fix/lint:
+	@ cd client && bun run fix:lint
 	@ uv run ruff check --fix .
 
 fix: fix/license fix/format fix/lint
 
 check/format:
+	@ cd client && bun run check:format
 	@ uv run ruff format --check .
 
 check/lint:
+	@ cd client && bun run check:lint
 	@ uv run ruff check .
 
 check/typing:
@@ -42,4 +47,5 @@ check/test:
 check: check/format check/lint check/typing check/cves check/security check/unused check/spell check/license check/test
 
 dev/run:
+	@ cd client && bun run build
 	@ PYTHONPATH=. uv run fastapi dev examples/main.py --host 0.0.0.0 --port $${PORT:-8000} --reload

{openadmin_dev-0.7.8 → openadmin_dev-0.7.11}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: openadmin-dev
-Version: 0.7.8
+Version: 0.7.11
 Summary: Add your description here
 Project-URL: Homepage, https://github.com/openadmin-team/openadmin-py
 Project-URL: Issues, https://github.com/openadmin-team/openadmin-py/issues
@@ -11,6 +11,7 @@ Classifier: Operating System :: OS Independent
 Classifier: Programming Language :: Python :: 3
 Requires-Python: >=3.14
 Requires-Dist: fastapi[standard]>=0.136.3
+Requires-Dist: typing-extensions>=4.12.0
 Description-Content-Type: text/markdown
 
 <!-- <div align="center">

{openadmin_dev-0.7.8 → openadmin_dev-0.7.11}/REUSE.toml

@@ -12,6 +12,7 @@ path = [
     "LICENSE",
     "**/__pycache__",
     "docs/**",
+    "client/**",
 ]
 SPDX-FileCopyrightText = "OpenAdmin"
 SPDX-License-Identifier = "AGPL-3.0-or-later"

openadmin_dev-0.7.11/client/.claude/skills/shadcn-vue/SKILL.md

@@ -0,0 +1,231 @@
+---
+name: shadcn-vue
+description: Manages shadcn-vue components and projects — adding, searching, fixing, debugging, styling, and composing UI. Provides project context, component docs, and usage examples. Applies when working with shadcn-vue, component registries, presets, --preset codes, or any project with a components.json file. Also triggers for "shadcn-vue init", "create an app with --preset", or "switch to --preset".
+user-invocable: false
+allowed-tools: Bash(npx shadcn-vue@latest *), Bash(pnpm dlx shadcn-vue@latest *), Bash(bunx --bun shadcn-vue@latest *)
+---
+
+# shadcn-vue
+
+A framework for building ui, components and design systems. Components are added as source code to the user's project via the CLI.
+
+> **IMPORTANT:** Run all CLI commands using the project's package runner: `npx shadcn-vue@latest`, `pnpm dlx shadcn-vue@latest`, or `bunx --bun shadcn-vue@latest` — based on the project's `packageManager`. Examples below use `npx shadcn-vue@latest` but substitute the correct runner for the project.
+
+## Current Project Context
+
+```json
+!`npx shadcn-vue@latest info --json`
+```
+
+The JSON above contains the project config and installed components. Use `npx shadcn-vue@latest docs <component>` to get documentation and example URLs for any component.
+
+## Principles
+
+1. **Use existing components first.** Use `npx shadcn-vue@latest search` to check registries before writing custom UI. Check community registries too.
+2. **Compose, don't reinvent.** Settings page = Tabs + Card + form controls. Dashboard = Sidebar + Card + Chart + Table.
+3. **Use built-in variants before custom styles.** `variant="outline"`, `size="sm"`, etc.
+4. **Use semantic colors.** `bg-primary`, `text-muted-foreground` — never raw values like `bg-blue-500`.
+
+## Critical Rules
+
+These rules are **always enforced**. Each links to a file with Incorrect/Correct code pairs.
+
+### Styling & Tailwind → [styling.md](./rules/styling.md)
+
+- **`class` for layout, not styling.** Never override component colors or typography.
+- **No `space-x-*` or `space-y-*`.** Use `flex` with `gap-*`. For vertical stacks, `flex flex-col gap-*`.
+- **Use `size-*` when width and height are equal.** `size-10` not `w-10 h-10`.
+- **Use `truncate` shorthand.** Not `overflow-hidden text-ellipsis whitespace-nowrap`.
+- **No manual `dark:` color overrides.** Use semantic tokens (`bg-background`, `text-muted-foreground`).
+- **Use `cn()` for conditional classes.** Don't write manual template literal ternaries.
+- **No manual `z-index` on overlay components.** Dialog, Sheet, Popover, etc. handle their own stacking.
+
+### Forms & Inputs → [forms.md](./rules/forms.md)
+
+- **Forms use `FieldGroup` + `Field`.** Never use raw `div` with `space-y-*` or `grid gap-*` for form layout.
+- **`InputGroup` uses `InputGroupInput`/`InputGroupTextarea`.** Never raw `Input`/`Textarea` inside `InputGroup`.
+- **Buttons inside inputs use `InputGroup` + `InputGroupAddon`.**
+- **Option sets (2–7 choices) use `ToggleGroup`.** Don't loop `Button` with manual active state.
+- **`FieldSet` + `FieldLegend` for grouping related checkboxes/radios.** Don't use a `div` with a heading.
+- **Field validation uses `data-invalid` + `aria-invalid`.** `data-invalid` on `Field`, `aria-invalid` on the control. For disabled: `data-disabled` on `Field`, `disabled` on the control.
+
+### Component Structure → [composition.md](./rules/composition.md)
+
+- **Items always inside their Group.** `SelectItem` → `SelectGroup`. `DropdownMenuItem` → `DropdownMenuGroup`. `CommandItem` → `CommandGroup`.
+- **Dialog, Sheet, and Drawer always need a Title.** `DialogTitle`, `SheetTitle`, `DrawerTitle` required for accessibility. Use `class="sr-only"` if visually hidden.
+- **Use full Card composition.** `CardHeader`/`CardTitle`/`CardDescription`/`CardContent`/`CardFooter`. Don't dump everything in `CardContent`.
+- **Button has no `isPending`/`isLoading`.** Compose with `Spinner` + `data-icon` + `disabled`.
+- **`TabsTrigger` must be inside `TabsList`.** Never render triggers directly in `Tabs`.
+- **`Avatar` always needs `AvatarFallback`.** For when the image fails to load.
+
+### Use Components, Not Custom Markup → [composition.md](./rules/composition.md)
+
+- **Use existing components before custom markup.** Check if a component exists before writing a styled `div`.
+- **Callouts use `Alert`.** Don't build custom styled divs.
+- **Empty states use `Empty`.** Don't build custom empty state markup.
+- **Toast via `vue-sonner`.** Use `toast()` from `vue-sonner`.
+- **Use `Separator`** instead of `<hr>` or `<div class="border-t">`.
+- **Use `Skeleton`** for loading placeholders. No custom `animate-pulse` divs.
+- **Use `Badge`** instead of custom styled spans.
+
+### Icons → [icons.md](./rules/icons.md)
+
+- **Icons in `Button` use `data-icon`.** `data-icon="inline-start"` or `data-icon="inline-end"` on the icon.
+- **No sizing classes on icons inside components.** Components handle icon sizing via CSS. No `size-4` or `w-4 h-4`.
+- **Pass icons as objects, not string keys.** `:icon="CheckIcon"`, not a string lookup.
+
+### CLI
+
+- **Apply preset codes directly with the CLI.** Use `npx shadcn-vue@latest apply <code>` for existing projects, or `npx shadcn-vue@latest init --preset <code>` when initializing.
+
+## Key Patterns
+
+These are the most common patterns that differentiate correct shadcn-vue code. For edge cases, see the linked rule files above.
+
+```html
+<!-- Form layout: FieldGroup + Field, not div + Label. -->
+<FieldGroup>
+  <Field>
+    <FieldLabel for="email">Email</FieldLabel>
+    <Input id="email" />
+  </Field>
+</FieldGroup>
+
+<!-- Validation: data-invalid on Field, aria-invalid on the control. -->
+<Field data-invalid>
+  <FieldLabel>Email</FieldLabel>
+  <Input aria-invalid />
+  <FieldDescription>Invalid email.</FieldDescription>
+</Field>
+
+<!-- Icons in buttons: data-icon, no sizing classes. -->
+<Button>
+  <SearchIcon data-icon="inline-start" />
+  Search
+</Button>
+
+<!-- Spacing: gap-*, not space-y-*. -->
+<div class="flex flex-col gap-4">  <!-- correct -->
+<div class="space-y-4">           <!-- wrong -->
+
+<!-- Equal dimensions: size-*, not w-* h-*. -->
+<Avatar class="size-10">   <!-- correct -->
+<Avatar class="w-10 h-10"> <!-- wrong -->
+
+<!-- Status colors: Badge variants or semantic tokens, not raw colors. -->
+<Badge variant="secondary">+20.1%</Badge>    <!-- correct -->
+<span class="text-emerald-600">+20.1%</span> <!-- wrong -->
+```
+
+## Component Selection
+
+| Need                       | Use                                                                                                 |
+| -------------------------- | --------------------------------------------------------------------------------------------------- |
+| Button/action              | `Button` with appropriate variant                                                                   |
+| Form inputs                | `Input`, `Select`, `Combobox`, `Switch`, `Checkbox`, `RadioGroup`, `Textarea`, `InputOTP`, `Slider` |
+| Toggle between 2–7 options | `ToggleGroup` + `ToggleGroupItem`                                                                   |
+| Data display               | `Table`, `Card`, `Badge`, `Avatar`                                                                  |
+| Navigation                 | `Sidebar`, `NavigationMenu`, `Breadcrumb`, `Tabs`, `Pagination`                                     |
+| Overlays                   | `Dialog` (modal), `Sheet` (side panel), `Drawer` (bottom sheet), `AlertDialog` (confirmation)       |
+| Feedback                   | `vue-sonner` (toast), `Alert`, `Progress`, `Skeleton`, `Spinner`                                   |
+| Command palette            | `Command` inside `Dialog`                                                                           |
+| Charts                     | `Chart` (wraps Unovis)                                                                              |
+| Layout                     | `Card`, `Separator`, `Resizable`, `ScrollArea`, `Accordion`, `Collapsible`                          |
+| Empty states               | `Empty`                                                                                             |
+| Menus                      | `DropdownMenu`, `ContextMenu`, `Menubar`                                                            |
+| Tooltips/info              | `Tooltip`, `HoverCard`, `Popover`                                                                   |
+
+## Key Fields
+
+The injected project context contains these key fields:
+
+- **`aliases`** → use the actual alias prefix for imports (e.g. `@/`, `~/`), never hardcode.
+- **`tailwindVersion`** → `"v4"` uses `@theme inline` blocks; `"v3"` uses `tailwind.config.js`.
+- **`tailwindCssFile`** → the global CSS file where custom CSS variables are defined. Always edit this file, never create a new one.
+- **`style`** → component visual treatment (e.g. `nova`, `vega`).
+- **`base`** → primitive library (`reka`). Affects component APIs and available props.
+- **`iconLibrary`** → determines icon imports. Use `@lucide/vue` for `lucide`, `@tabler/icons-vue` for `tabler`, etc. Never assume `@lucide/vue`.
+- **`resolvedPaths`** → exact file-system destinations for components, utils, hooks, etc.
+- **`framework`** → routing and file conventions (e.g. Nuxt vs Vite SPA).
+- **`packageManager`** → use this for any non-shadcn-vue dependency installs (e.g. `pnpm add date-fns` vs `npm install date-fns`).
+
+See [cli.md — `info` command](./cli.md) for the full field reference.
+
+## Component Docs, Examples, and Usage
+
+Run `npx shadcn-vue@latest docs <component>` to get the URLs for a component's documentation, examples, and API reference. Fetch these URLs to get the actual content.
+
+```bash
+npx shadcn-vue@latest docs button dialog select
+```
+
+**When creating, fixing, debugging, or using a component, always run `npx shadcn-vue@latest docs` and fetch the URLs first.** This ensures you're working with the correct API and usage patterns rather than guessing.
+
+## Workflow
+
+1. **Get project context** — already injected above. Run `npx shadcn-vue@latest info` again if you need to refresh.
+2. **Check installed components first** — before running `add`, always check the `components` list from project context or list the `resolvedPaths.ui` directory. Don't import components that haven't been added, and don't re-add ones already installed.
+3. **Find components** — `npx shadcn-vue@latest search`.
+4. **Get docs and examples** — run `npx shadcn-vue@latest docs <component>` to get URLs, then fetch them. Use `npx shadcn-vue@latest view` to browse registry items you haven't installed. To preview changes to installed components, use `npx shadcn-vue@latest add --diff`.
+5. **Install or update** — `npx shadcn-vue@latest add`. When updating existing components, use `--dry-run` and `--diff` to preview changes first (see [Updating Components](#updating-components) below).
+6. **Fix imports in third-party components** — After adding components from community registries, check the added non-UI files for hardcoded import paths like `@/components/ui/...`. These won't match the project's actual aliases. Use `npx shadcn-vue@latest info` to get the correct `ui` alias (e.g. `@workspace/ui/components`) and rewrite the imports accordingly. The CLI rewrites imports for its own UI files, but third-party registry components may use default paths that don't match the project.
+7. **Review added components** — After adding a component or block from any registry, **always read the added files and verify they are correct**. Check for missing sub-components (e.g. `SelectItem` without `SelectGroup`), missing imports, incorrect composition, or violations of the [Critical Rules](#critical-rules). Also replace any icon imports with the project's `iconLibrary` from the project context (e.g. if the registry item uses `@lucide/vue` but the project uses `hugeicons`, swap the imports and icon names accordingly). Fix all issues before moving on.
+8. **Registry must be explicit** — When the user asks to add a block or component, **do not guess the registry**. If no registry is specified (e.g. user says "add a login block" without specifying `@shadcn`, etc.), ask which registry to use. Never default to a registry on behalf of the user.
+9. **Switching presets** — Ask the user first: **overwrite**, **merge**, or **skip**?
+   - **Overwrite**: `npx shadcn-vue@latest apply <code>`. Overwrites detected components, fonts, and CSS variables.
+   - **Merge**: `npx shadcn-vue@latest init --preset <code> --force --no-reinstall`, then run `npx shadcn-vue@latest info` to list installed components, then for each installed component use `--dry-run` and `--diff` to [smart merge](#updating-components) it individually.
+   - **Skip**: `npx shadcn-vue@latest init --preset <code> --force --no-reinstall`. Only updates config and CSS, leaves components as-is.
+   - **Important**: Always run preset commands inside the user's project directory. `apply` only works in an existing project with a `components.json` file. The CLI automatically preserves the current base (`reka`) from `components.json`. If you must use a scratch/temp directory (e.g. for `--dry-run` comparisons), pass `--base <current-base>` explicitly — preset codes do not encode the base.
+
+## Updating Components
+
+When the user asks to update a component from upstream while keeping their local changes, use `--dry-run` and `--diff` to intelligently merge. **NEVER fetch raw files from GitHub manually — always use the CLI.**
+
+1. Run `npx shadcn-vue@latest add <component> --dry-run` to see all files that would be affected.
+2. For each file, run `npx shadcn-vue@latest add <component> --diff <file>` to see what changed upstream vs local.
+3. Decide per file based on the diff:
+   - No local changes → safe to overwrite.
+   - Has local changes → read the local file, analyze the diff, and apply upstream updates while preserving local modifications.
+   - User says "just update everything" → use `--overwrite`, but confirm first.
+4. **Never use `--overwrite` without the user's explicit approval.**
+
+## Quick Reference
+
+```bash
+# Create a new project.
+npx shadcn-vue@latest init --name my-app --preset nova
+npx shadcn-vue@latest init --name my-app --preset a2r6bw --template vite
+
+# Initialize existing project.
+npx shadcn-vue@latest init --preset nova
+npx shadcn-vue@latest init --defaults  # shortcut: --template=nuxt --preset=nova (base style implied)
+
+# Apply a preset to an existing project.
+npx shadcn-vue@latest apply a2r6bw
+
+# Add components.
+npx shadcn-vue@latest add button card dialog
+npx shadcn-vue@latest add --all
+
+# Search registries.
+npx shadcn-vue@latest search @shadcn -q "sidebar"
+
+# Get component docs and example URLs.
+npx shadcn-vue@latest docs button dialog select
+
+# View registry item details (for items not yet installed).
+npx shadcn-vue@latest view @shadcn/button
+```
+
+**Named presets:** `nova`, `vega`, `maia`, `lyra`, `mira`, `luma`
+**Templates:** `nuxt`, `vite`, `astro` and `laravel`
+**Preset codes:** Version-prefixed base62 strings (e.g. `a2r6bw`), from [shadcn-vue.com](https://shadcn-vue.com).
+
+## Detailed References
+
+- [rules/forms.md](./rules/forms.md) — FieldGroup, Field, InputGroup, ToggleGroup, FieldSet, validation states
+- [rules/composition.md](./rules/composition.md) — Groups, overlays, Card, Tabs, Avatar, Alert, Empty, Toast, Separator, Skeleton, Badge, Button loading
+- [rules/icons.md](./rules/icons.md) — data-icon, icon sizing, passing icons as objects
+- [rules/styling.md](./rules/styling.md) — Semantic colors, variants, class, spacing, size, truncate, dark mode, cn(), z-index
+- [cli.md](./cli.md) — Commands, flags, presets, templates
+- [customization.md](./customization.md) — Theming, CSS variables, extending components

openadmin_dev-0.7.11/client/.claude/skills/shadcn-vue/cli.md

@@ -0,0 +1,225 @@
+# shadcn-vue CLI Reference
+
+Configuration is read from `components.json`.
+
+> **IMPORTANT:** Always run commands using the project's package runner: `npx shadcn-vue@latest`, `pnpm dlx shadcn-vue@latest`, or `bunx --bun shadcn-vue@latest`. Check `packageManager` from project context to choose the right one. Examples below use `npx shadcn-vue@latest` but substitute the correct runner for the project.
+> **IMPORTANT:** Only use the flags documented below. Do not invent or guess flags — if a flag isn't listed here, it doesn't exist. The CLI auto-detects the package manager from the project's lockfile; there is no `--package-manager` flag.
+
+## Contents
+
+- Commands: init, apply, add (smart merge), search, view, docs, info, build
+- Templates: nuxt, vite, astro, laravel
+- Presets: named, code, URL formats and fields
+- Switching presets
+
+---
+
+## Commands
+
+### `init` — Initialize or create a project
+
+```bash
+npx shadcn-vue@latest init [components...] [options]
+```
+
+Initializes shadcn-vue in an existing project or creates a new project (when `--name` is provided). Optionally installs components in the same step.
+
+| Flag                    | Short | Description                                         | Default |
+| ----------------------- | ----- | --------------------------------------------------- | ------- |
+| `--template <template>` | `-t`  | Template (nuxt, vite, astro, laravel)               | —       |
+| `--preset [name]`       | `-p`  | Preset configuration (named, code, or URL)          | —       |
+| `--yes`                 | `-y`  | Skip confirmation prompt                            | `true`  |
+| `--defaults`            | `-d`  | Use defaults (`--template=nuxt --preset=nova`) | `false` |
+| `--force`               | `-f`  | Force overwrite existing configuration              | `false` |
+| `--cwd <cwd>`           | `-c`  | Working directory                                   | current |
+| `--name <name>`         | `-n`  | Name for new project                                | —       |
+| `--silent`              | `-s`  | Mute output                                         | `false` |
+| `--rtl`                 |       | Enable RTL support                                  | —       |
+| `--reinstall`           |       | Re-install existing UI components                   | `false` |
+
+`npx shadcn-vue@latest create` is an alias for `npx shadcn-vue@latest init`.
+
+### `apply` — Apply a preset to an existing project
+
+```bash
+npx shadcn-vue@latest apply [preset] [options]
+```
+
+Applies a preset to an existing project, overwriting preset-driven config, fonts, CSS variables, and detected UI components.
+
+| Flag                | Short | Description                                | Default |
+| ------------------- | ----- | ------------------------------------------ | ------- |
+| `--preset <preset>` | —     | Preset configuration (named, code, or URL) | —       |
+| `--yes`             | `-y`  | Skip confirmation prompt                   | `false` |
+| `--cwd <cwd>`       | `-c`  | Working directory                          | current |
+| `--silent`          | `-s`  | Mute output                                | `false` |
+
+`[preset]` is a shorthand for `--preset <preset>`. If both are provided, they must match.
+If no preset is provided, the CLI offers to open the custom preset builder on `shadcn-vue.com/create`.
+
+### `add` — Add components
+
+> **IMPORTANT:** NEVER fetch raw files from GitHub or other sources manually. The CLI handles registry resolution, file paths, and CSS diffing automatically.
+
+```bash
+npx shadcn-vue@latest add [components...] [options]
+```
+
+Accepts component names, registry-prefixed names (`@magicui/shimmer-button`), URLs, or local paths.
+
+| Flag            | Short | Description                                                                                                          | Default |
+| --------------- | ----- | -------------------------------------------------------------------------------------------------------------------- | ------- |
+| `--yes`         | `-y`  | Skip confirmation prompt                                                                                             | `false` |
+| `--overwrite`   | `-o`  | Overwrite existing files                                                                                             | `false` |
+| `--cwd <cwd>`   | `-c`  | Working directory                                                                                                    | current |
+| `--all`         | `-a`  | Add all available components                                                                                         | `false` |
+| `--path <path>` | `-p`  | Target path for the component                                                                                        | —       |
+| `--silent`      | `-s`  | Mute output                                                                                                          | `false` |
+
+#### Smart Merge from Upstream
+
+See [Updating Components in SKILL.md](./SKILL.md#updating-components) for the full workflow.
+
+### `search` — Search registries
+
+```bash
+npx shadcn-vue@latest search <registries...> [options]
+```
+
+Fuzzy search across registries. Also aliased as `npx shadcn-vue@latest list`. Without `-q`, lists all items.
+
+| Flag                | Short | Description            | Default |
+| ------------------- | ----- | ---------------------- | ------- |
+| `--query <query>`   | `-q`  | Search query           | —       |
+| `--limit <number>`  | `-l`  | Max items per registry | `100`   |
+| `--offset <number>` | `-o`  | Items to skip          | `0`     |
+| `--cwd <cwd>`       | `-c`  | Working directory      | current |
+
+### `view` — View item details
+
+```bash
+npx shadcn-vue@latest view <items...> [options]
+```
+
+Displays item info including file contents. Example: `npx shadcn-vue@latest view @shadcn/button`.
+
+### `docs` — Get component documentation URLs
+
+```bash
+npx shadcn-vue@latest docs <components...> [options]
+```
+
+Outputs resolved URLs for component documentation, examples, and API references. Accepts one or more component names. Fetch the URLs to get the actual content.
+
+Example output for `npx shadcn-vue@latest docs input button`:
+
+```text
+input
+  docs      https://shadcn-vue.com/docs/components/input
+  examples  https://raw.githubusercontent.com/.../examples/InputExample.vue
+
+button
+  docs      https://shadcn-vue.com/docs/components/button
+  examples  https://raw.githubusercontent.com/.../examples/ButtonExample.vue
+```
+
+Some components include an `api` link to the underlying library (e.g. `reka-ui` for the primitive components).
+
+### `diff` — Check for updates
+
+Do not use this command. Use `npx shadcn-vue@latest add --diff` instead.
+
+### `info` — Project information
+
+```bash
+npx shadcn-vue@latest info [options]
+```
+
+Displays project info and `components.json` configuration. Run this first to discover the project's framework, aliases, Tailwind version, and resolved paths.
+
+| Flag          | Short | Description       | Default |
+| ------------- | ----- | ----------------- | ------- |
+| `--cwd <cwd>` | `-c`  | Working directory | current |
+
+**Project Info fields:**
+
+| Field                | Type      | Meaning                                                 |
+| -------------------- | --------- | ------------------------------------------------------- |
+| `framework`          | `string`  | Detected framework (`nuxt`, `vite`, `astro`, `laravel`) |
+| `frameworkVersion`   | `string`  | Framework version (e.g. `3.15.0`)                       |
+| `isSrcDir`           | `boolean` | Whether the project uses a `src/` directory             |
+| `isTs`               | `boolean` | Whether the project uses TypeScript                     |
+| `tailwindVersion`    | `string`  | `"v3"` or `"v4"`                                        |
+| `tailwindConfigFile` | `string`  | Path to the Tailwind config file                        |
+| `tailwindCssFile`    | `string`  | Path to the global CSS file                             |
+| `aliasPrefix`        | `string`  | Import alias prefix (e.g. `@`, `~`, `@/`)               |
+| `packageManager`     | `string`  | Detected package manager (`npm`, `pnpm`, `yarn`, `bun`) |
+
+**Components.json fields:**
+
+| Field                | Type      | Meaning                                                                                     |
+| -------------------- | --------- | --------------------------------------------------------------------------------------------|
+| `base`               | `string`  | Primitive library (`reka`) — determines component APIs and available props                  |
+| `style`              | `string`  | Visual style (e.g. `nova`, `vega`)                                                          |
+| `typescript`         | `boolean` | TypeScript flag                                                                             |
+| `tailwind.config`    | `string`  | Tailwind config path                                                                        |
+| `tailwind.css`       | `string`  | Global CSS path — this is where custom CSS variables go                                     |
+| `iconLibrary`        | `string`  | Icon library — determines icon import package (e.g. `@lucide/vue`, `@tabler/icons-vue`) |
+| `aliases.components` | `string`  | Component import alias (e.g. `@/components`)                                                |
+| `aliases.utils`      | `string`  | Utils import alias (e.g. `@/lib/utils`)                                                     |
+| `aliases.ui`         | `string`  | UI component alias (e.g. `@/components/ui`)                                                 |
+| `aliases.lib`        | `string`  | Lib alias (e.g. `@/lib`)                                                                    |
+| `aliases.composables`| `string`  | Composables/Hooks alias (e.g. `@/composables`)                                              |
+| `resolvedPaths`      | `object`  | Absolute file-system paths for each alias                                                   |
+| `registries`         | `object`  | Configured custom registries                                                                |
+
+**Links fields:**
+
+The `info` output includes a **Links** section with templated URLs for component docs, source, and examples. For resolved URLs, use `npx shadcn-vue@latest docs <component>` instead.
+
+### `build` — Build a custom registry
+
+```bash
+npx shadcn-vue@latest build [registry] [options]
+```
+
+Builds `registry.json` into individual JSON files for distribution. Default input: `./registry.json`, default output: `./public/r`.
+
+| Flag              | Short | Description       | Default      |
+| ----------------- | ----- | ----------------- | ------------ |
+| `--output <path>` | `-o`  | Output directory  | `./public/r` |
+| `--cwd <cwd>`     | `-c`  | Working directory | current      |
+
+---
+
+## Templates
+
+| Value   | Framework |
+| ------- | --------- |
+| `nuxt`  | Nuxt      |
+| `vite`  | Vite      |
+| `astro` | Astro     |
+| `laravel` | Laravel |
+
+---
+
+## Presets
+
+Three ways to specify a preset via `--preset`:
+
+1. **Named:** `--preset nova` or `--preset lyra`
+2. **Code:** `--preset a2r6bw` (version-prefixed base62 string, e.g. `a2r6bw`)
+3. **URL:** `--preset "https://shadcn-vue.com/init?base=reka&style=nova&..."`
+
+> **IMPORTANT:** Never try to decode, fetch, or resolve preset codes manually. Preset codes are opaque — pass them directly to `npx shadcn-vue@latest init --preset <code>` and let the CLI handle resolution.
+> Use `npx shadcn-vue@latest apply --preset <code>` when overwriting an existing project's preset.
+
+## Switching Presets
+
+Ask the user first: **overwrite**, **merge**, or **skip** existing components?
+
+- **Overwrite / Re-install** → `npx shadcn-vue@latest apply --preset <code>`. Overwrites all detected component files with the new preset styles. Use when the user hasn't customized components.
+- **Merge** → `npx shadcn-vue@latest init --preset <code> --force --no-reinstall`, then run `npx shadcn-vue@latest info` to get the list of installed components and use the [smart merge workflow](./SKILL.md#updating-components) to update them one by one, preserving local changes. Use when the user has customized components.
+- **Skip** → `npx shadcn-vue@latest init --preset <code> --force --no-reinstall`. Only updates config and CSS variables, leaves existing components as-is.
+
+Always run preset commands inside the user's project directory. `apply` only works in an existing project with a `components.json` file. The CLI automatically preserves the current base (`base`) from `components.json`. If you must use a scratch/temp directory (e.g. for `--dry-run` comparisons), pass `--base <current-base>` explicitly — preset codes do not encode the base.