@1aboveio/skills 0.10.0

package/skills/fullstack/shadcn/cli.md

@@ -0,0 +1,411 @@
+# shadcn CLI Reference
+
+Configuration is read from `components.json`.
+
+> **IMPORTANT:** Always run commands using the project's package runner: `npx shadcn@latest`, `pnpm dlx shadcn@latest`, or `bunx --bun shadcn@latest`. Choose the right one from the project's lockfile or the `packageManager` key in `package.json` — `shadcn info` does not report it. Examples below use `npx shadcn@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 (dry-run, smart merge), search, view, docs, info, build, migrate, eject, registry, preset, mcp
+- Templates: next, vite, start, react-router, astro, laravel
+- Presets: named, code, URL formats and fields
+- Switching presets
+
+---
+
+## Commands
+
+### `init` — Initialize or create a project
+
+```bash
+npx shadcn@latest init [components...] [options]
+```
+
+Initializes shadcn/ui 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 (next, start, vite, react-router, laravel, astro)           | —       |
+| `--base <base>`         | `-b`  | Primitive library: `base`, `radix`, or `aria`                        | —       |
+| `--preset [name]`       | `-p`  | Preset configuration (named, code, or URL)                           | —       |
+| `--yes`                 | `-y`  | Skip confirmation prompt                                             | `true`  |
+| `--defaults`            | `-d`  | Use defaults (`--template=next --preset=base-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` |
+| `--css-variables`       |       | Use CSS variables for theming                                        | `true`  |
+| `--no-css-variables`    |       | Do not use CSS variables for theming                                 | —       |
+| `--rtl` / `--no-rtl`    |       | Enable / disable RTL support                                         | —       |
+| `--pointer`             |       | Enable pointer cursor for buttons                                    | —       |
+| `--no-pointer`          |       | Disable pointer cursor for buttons                                   | —       |
+| `--reinstall`           |       | Re-install existing UI components                                    | `false` |
+| `--no-reinstall`        |       | Do not re-install existing UI components                             | —       |
+| `--monorepo`            |       | Scaffold a monorepo project                                          | —       |
+| `--no-monorepo`         |       | Skip the monorepo prompt                                             | —       |
+
+`npx shadcn@latest create` is an alias for `npx shadcn@latest init`.
+
+> `--template` takes the plain framework name. There is no `next-monorepo` template *value* — pass `--monorepo` alongside `--template next` and the CLI selects the monorepo template directory itself.
+
+### `apply` — Apply a preset to an existing project
+
+```bash
+npx shadcn@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)         | —       |
+| `--only [parts]`    | —     | Apply only parts of a preset: `theme`, `font`      | —       |
+| `--yes`             | `-y`  | Skip confirmation prompt                           | `false` |
+| `--cwd <cwd>`       | `-c`  | Working directory                                  | current |
+| `--silent`          | `-s`  | Mute output                                        | `false` |
+
+Use `--only theme` / `--only font` to re-theme without touching component files — the narrow alternative to the full overwrite/merge/skip decision below.
+
+`[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 `ui.shadcn.com/create`.
+
+### `add` — Add components
+
+> **IMPORTANT:** To compare local components against upstream or to preview changes, ALWAYS use `npx shadcn@latest add <component> --dry-run`, `--diff`, or `--view`. NEVER fetch raw files from GitHub or other sources manually. The CLI handles registry resolution, file paths, and CSS diffing automatically.
+
+```bash
+npx shadcn@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` |
+| `--dry-run`     |       | Preview all changes without writing files                                                                            | `false` |
+| `--diff [path]` |       | Show diffs. Without a path, shows the first 5 files. With a path, shows that file only (implies `--dry-run`)         | —       |
+| `--view [path]` |       | Show file contents. Without a path, shows the first 5 files. With a path, shows that file only (implies `--dry-run`) | —       |
+
+#### Dry-Run Mode
+
+Use `--dry-run` to preview what `add` would do without writing any files. `--diff` and `--view` both imply `--dry-run`.
+
+```bash
+# Preview all changes.
+npx shadcn@latest add button --dry-run
+
+# Show diffs for all files (top 5).
+npx shadcn@latest add button --diff
+
+# Show the diff for a specific file.
+npx shadcn@latest add button --diff button.tsx
+
+# Show contents for all files (top 5).
+npx shadcn@latest add button --view
+
+# Show the full content of a specific file.
+npx shadcn@latest add button --view button.tsx
+
+# Works with URLs too.
+npx shadcn@latest add https://api.npoint.io/abc123 --dry-run
+
+# CSS diffs.
+npx shadcn@latest add button --diff globals.css
+```
+
+**When to use dry-run:**
+
+- When the user asks "what files will this add?" or "what will this change?" — use `--dry-run`.
+- Before overwriting existing components — use `--diff` to preview the changes first.
+- When the user wants to inspect component source code without installing — use `--view`.
+- When checking what CSS changes would be made to `globals.css` — use `--diff globals.css`.
+- When the user asks to review or audit third-party registry code before installing — use `--view` to inspect the source.
+
+> **`npx shadcn@latest add --dry-run` vs `npx shadcn@latest view`:** Prefer `npx shadcn@latest add --dry-run/--diff/--view` over `npx shadcn@latest view` when the user wants to preview changes to their project. `npx shadcn@latest view` only shows raw registry metadata. `npx shadcn@latest add --dry-run` shows exactly what would happen in the user's project: resolved file paths, diffs against existing files, and CSS updates. Use `npx shadcn@latest view` only when the user wants to browse registry info without a project context.
+
+#### Smart Merge from Upstream
+
+When the user asks to update a component from upstream while keeping their local changes, use `--dry-run` and `--diff` to merge intelligently. **Never fetch raw files from GitHub — always use the CLI**, which resolves the registry, the file paths, and the CSS diff for you.
+
+1. Run `npx shadcn@latest add <component> --dry-run` to see every file that would be affected.
+2. For each file, run `npx shadcn@latest add <component> --diff <file>` to see upstream vs local.
+3. Decide per file from the diff:
+   - No local changes → safe to overwrite.
+   - Has local changes → read the local file, then apply the upstream updates while preserving the local modifications.
+   - User says "just update everything" → `--overwrite`, but confirm first.
+4. **Never use `--overwrite` without explicit approval.** It is the one flag here that destroys work, and the customizations it discards are usually invisible in the diff summary.
+
+#### Installing everything up front
+
+The house setup installs the full library at init (`npx shadcn@latest add --all`) rather than adding components on demand, so feature work never blocks on a missing component. Two things follow from that, and both bite later rather than at install time:
+
+**`--all` is not an update path.** Re-running it with `--overwrite` to "refresh" the library discards every local customization at once, silently and across ~60 files. When upstream moves, update the components you have actually edited, one at a time, via [smart merge](#smart-merge-from-upstream). For untouched components an overwrite is safe — but establish which are untouched from the diff, not from memory.
+
+**The dependency footprint is permanent and larger than the component count suggests.** Unused component *files* are inert — a bundler only ships what is imported — but their npm dependencies are not: they stay in `package.json`, the lockfile, install time, and the audit surface whether or not anything imports them. On `base-nova` the components that each drag in their own runtime library are:
+
+| Component | Brings |
+|---|---|
+| `chart` | `recharts` |
+| `calendar` | `react-day-picker`, `date-fns` |
+| `carousel` | `embla-carousel-react` |
+| `command` | `cmdk` |
+| `resizable` | `react-resizable-panels` |
+| `input-otp` | `input-otp` |
+| `sonner` | `sonner`, `next-themes` |
+
+Everything else resolves to `@base-ui/react`, which the base already requires — including `drawer`, which on a radix base would instead pull `vaul`. So the extra surface is roughly the seven rows above, not sixty. Expect dependency-bot traffic for libraries no feature uses; that is the accepted cost of the setup, not a sign something went wrong.
+
+Land the `--all` install as its own commit. Sixty components nobody hand-picked are impossible to review meaningfully inside a feature diff, and keeping them separate preserves the ability to tell a deliberate component choice from the bulk install.
+
+#### Working with third-party registries
+
+Two habits that prevent most registry damage, both of which cost far less than the cleanup:
+
+**Ask which registry when the user doesn't name one.** "Add a login block" is ambiguous across `@shadcn`, `@tailark`, `@magicui` and the rest. Guessing installs a different design system into the project, and because the result compiles and looks plausible, the mistake usually isn't caught until review — by which point it has been styled around. Never pick a registry on the user's behalf.
+
+**Read every file a registry adds.** Registry code is community-published, not pre-verified, so treat `add` as "downloaded" rather than "correct". The recurring problems:
+
+- **Hardcoded import paths.** The CLI rewrites imports for its own UI files, but third-party items often ship `@/components/ui/...`, which silently misses a project whose alias is `@workspace/ui/components`. Check `config.aliases` and rewrite.
+- **The wrong icon library.** Most registries assume `lucide-react`. If `config.iconLibrary` is anything else, `npx shadcn@latest migrate icons --from lucide --to <lib>` converts them; swapping by hand is where icon names get mistranslated.
+- **Undeclared dependencies.** An item's `dependencies` list is only as good as its author — a file can import a package the registry never declares, and the gap surfaces as a build error after an install that reported success.
+- **Composition that violates this skill's rules** — a `SelectItem` outside a `SelectGroup`, an error in a `FieldDescription`, sizing classes on icons.
+
+Use `--view` to audit the source *before* installing when the registry is unfamiliar.
+
+### `search` — Search registries
+
+```bash
+npx shadcn@latest search [registries...] [options]
+```
+
+Fuzzy search across registries. Also aliased as `npx shadcn@latest list`. Without `-q`, lists all items. **Registries are optional** — omit them and the CLI searches every registry configured in `components.json`. Accepts namespaces, GitHub sources, and URLs.
+
+| Flag                | Short | Description                                            | Default |
+| ------------------- | ----- | ------------------------------------------------------ | ------- |
+| `--query <query>`   | `-q`  | Search query                                           | —       |
+| `--type <type>`     | `-t`  | Filter by item type (`ui`, `block`, `hook`, …). Comma-separated for multiple | — |
+| `--limit <number>`  | `-l`  | Max items per registry                                 | `100`   |
+| `--offset <number>` | `-o`  | Items to skip                                          | `0`     |
+| `--json`            |       | Output as JSON                                         | `false` |
+| `--cwd <cwd>`       | `-c`  | Working directory                                      | current |
+
+### `view` — View item details
+
+```bash
+npx shadcn@latest view <items...> [options]
+```
+
+Displays item info including file contents. Example: `npx shadcn@latest view @shadcn/button`.
+
+### `docs` — Get component documentation URLs
+
+```bash
+npx shadcn@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.
+
+| Flag              | Short | Description                                                    | Default        |
+| ----------------- | ----- | -------------------------------------------------------------- | -------------- |
+| `--base <base>`   | `-b`  | Resolve URLs for `base`, `radix`, or `aria` instead of the project base | project base |
+| `--json`          |       | Output as JSON                                                 | `false`        |
+| `--cwd <cwd>`     | `-c`  | Working directory                                              | current        |
+
+URLs are **base-scoped** — the base is a path segment in both the docs and the examples URL. Example output for `npx shadcn@latest docs input button`:
+
+```
+input
+  - docs      https://ui.shadcn.com/docs/components/radix/input
+  - examples  https://ui.shadcn.com/code/apps/v4/registry/bases/radix/examples/input-example.tsx
+
+button
+  - docs      https://ui.shadcn.com/docs/components/radix/button
+  - examples  https://ui.shadcn.com/code/apps/v4/registry/bases/radix/examples/button-example.tsx
+```
+
+Some components include an `api` link to the underlying library — e.g. `https://base-ui.com/react/components/select.md` for base, `https://react-aria.adobe.com/Button#api` for aria, `cmdk` for the command component.
+
+### `diff` — Check for updates
+
+Do not use this command. Use `npx shadcn@latest add --diff` instead.
+
+### `info` — Project information
+
+```bash
+npx shadcn@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 |
+| ------------- | ----- | ----------------- | ------- |
+| `--json`      |       | Output as JSON    | `false` |
+| `--cwd <cwd>` | `-c`  | Working directory | current |
+
+`--json` returns five top-level blocks: `project`, `config`, `preset`, `components`, `links`. **Field names below are exact — read them from the right block.**
+
+**`project` — detected from the filesystem:**
+
+| Field              | Type      | Meaning                                                            |
+| ------------------ | --------- | ------------------------------------------------------------------ |
+| `framework`        | `string`  | Display name of the detected framework (`Next.js`, `Vite`, `Manual`, …) |
+| `frameworkName`    | `string`  | Machine name (`next`, `vite`, `react-router`, `start`, `manual`)   |
+| `frameworkVersion` | `string`  | Framework version (e.g. `15.2.4`), or `null`                       |
+| `srcDirectory`     | `boolean` | Whether the project uses a `src/` directory                        |
+| `rsc`              | `boolean` | Whether React Server Components are enabled                        |
+| `typescript`       | `boolean` | Whether the project uses TypeScript                                |
+| `tailwindVersion`  | `string`  | `"v3"` or `"v4"`                                                   |
+| `tailwindConfig`   | `string`  | Path to the Tailwind config file (`null` on v4)                    |
+| `tailwindCss`      | `string`  | Path to the global CSS file                                        |
+| `importAlias`      | `string`  | Import alias prefix (e.g. `@`, `~`)                                |
+
+> There is **no `packageManager` field** in `info` output. The CLI detects the package manager from the lockfile for its own installs; to pick a runner yourself, read the lockfile or `packageManager` in `package.json`.
+
+**`config` — from `components.json`:**
+
+| Field                | Type      | Meaning                                                                                    |
+| -------------------- | --------- | ------------------------------------------------------------------------------------------ |
+| `style`              | `string`  | Combined `<base>-<preset>` (e.g. `radix-nova`, `base-lyra`, `aria-vega`)                   |
+| `base`               | `string`  | Primitive library (`radix`, `base`, or `aria`), derived from `style` — determines component APIs |
+| `rsc`                | `boolean` | RSC flag from config                                                                       |
+| `typescript`         | `boolean` | TypeScript flag                                                                            |
+| `iconLibrary`        | `string`  | Icon library key (`lucide`, `tabler`, `hugeicons`, `phosphor`, `remixicon`)                |
+| `rtl`                | `boolean` | RTL support flag                                                                           |
+| `menuColor`          | `string`  | `default`, `inverted`, `default-translucent`, `inverted-translucent`, or `null`            |
+| `menuAccent`         | `string`  | `subtle`, `bold`, or `null`                                                                |
+| `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.hooks`      | `string`  | Hooks alias (e.g. `@/hooks`)                                                               |
+| `resolvedPaths`      | `object`  | Absolute paths per alias, plus `cwd`, `tailwindConfig`, `tailwindCss`                      |
+| `registries`         | `object`  | Configured registries, including the built-in `@shadcn` (`https://ui.shadcn.com/r/styles/{style}/{name}.json`) |
+
+**`preset`, `components`, `links`:**
+
+- `preset` — `{ code, fallbacks, values }`. `code` is the current project's preset code; `values` holds the resolved `style`, `baseColor`, `theme`, `chartColor`, `iconLibrary`, `font`, `fontHeading`, `radius`, `menuAccent`, `menuColor`.
+- `components` — the list of installed registry items. **Check this before running `add`.**
+- `links` — templated URLs (`docs`, `components`, `ui`, `examples`, `schema`) with a `[component]` placeholder. For resolved URLs, use `npx shadcn@latest docs <component>` instead.
+
+### `build` — Build a custom registry
+
+```bash
+npx shadcn@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      |
+
+### `migrate` — Run a codemod
+
+```bash
+npx shadcn@latest migrate [migration] [path] [options]
+```
+
+Rewrites existing source files. `[path]` optionally narrows the scope to a path or glob.
+
+| Flag                | Short | Description                                     | Default |
+| ------------------- | ----- | ----------------------------------------------- | ------- |
+| `--list`            | `-l`  | List all migrations                             | `false` |
+| `--from <library>`  | `-f`  | Icon library to migrate from (`icons` only)     | —       |
+| `--to <library>`    | `-t`  | Icon library to migrate to (`icons` only)       | —       |
+| `--yes`             | `-y`  | Skip confirmation prompt                        | `false` |
+| `--cwd <cwd>`       | `-c`  | Working directory                               | current |
+
+Available migrations (`npx shadcn@latest migrate --list`):
+
+| Migration | What it does                                                     |
+| --------- | ---------------------------------------------------------------- |
+| `icons`   | Switch components to a different icon library (`--from` / `--to`) |
+| `radix`   | Migrate individual `@radix-ui/react-*` packages to unified `radix-ui` |
+| `rtl`     | Add RTL (right-to-left) support to components                    |
+
+Prefer `migrate icons` over hand-editing imports when swapping icon libraries across a codebase.
+
+### `eject` — Remove the shadcn runtime dependency
+
+```bash
+npx shadcn@latest eject [options]
+```
+
+Inlines `shadcn/tailwind.css` and drops the `shadcn` package dependency. One-way — confirm with the user first. Flags: `--yes` / `-y`, `--silent` / `-s`, `--cwd` / `-c`.
+
+### `registry` — Manage registries
+
+```bash
+npx shadcn@latest registry add [registries...]   # @namespace, or @namespace=url
+npx shadcn@latest registry validate [registry]
+```
+
+`registry add` writes entries into `components.json` for you — prefer it over hand-editing the `registries` object. A bare `@namespace` is looked up in the community index; `@namespace=https://…/{name}.json` sets an explicit URL. `registry validate` checks a registry's items against the schema.
+
+### `preset` — Inspect preset codes
+
+```bash
+npx shadcn@latest preset decode <code>    # show the values a code encodes
+npx shadcn@latest preset resolve          # the current project's preset (alias: info)
+npx shadcn@latest preset url <code>       # https://ui.shadcn.com/create?preset=<code>
+npx shadcn@latest preset open <code>      # open that URL in the browser
+```
+
+`decode` and `resolve` accept `--json`. Preset codes stay opaque to *you* — use these commands rather than decoding, fetching, or hand-parsing a code.
+
+### `mcp` — MCP server
+
+```bash
+npx shadcn@latest mcp                                  # run the server (stdio)
+npx shadcn@latest mcp init --client <claude|cursor|vscode|codex|opencode>
+```
+
+See [mcp.md](./mcp.md) for the tool list.
+
+---
+
+## Templates
+
+| Value          | Framework      | Monorepo support |
+| -------------- | -------------- | ---------------- |
+| `next`         | Next.js        | Yes              |
+| `vite`         | Vite           | Yes              |
+| `start`        | TanStack Start | Yes              |
+| `react-router` | React Router   | Yes              |
+| `astro`        | Astro          | Yes              |
+| `laravel`      | Laravel        | No               |
+
+All templates support monorepo scaffolding via the `--monorepo` flag. When passed, the CLI uses a monorepo-specific template directory (e.g. `next-monorepo`, `vite-monorepo`). When neither `--monorepo` nor `--no-monorepo` is passed, the CLI prompts interactively. Laravel does not support monorepo scaffolding.
+
+---
+
+## Presets
+
+Three ways to specify a preset via `--preset`:
+
+1. **Named:** `--preset nova` or `--preset lyra`. The full set is `nova`, `vega`, `maia`, `lyra`, `mira`, `luma`, `sera`, `rhea`. Also accepted base-qualified: `base-nova`, `radix-lyra`, `aria-vega`.
+2. **Code:** `--preset a2r6bw` (version-prefixed base62 string, e.g. `a2r6bw` or `b0`)
+3. **URL:** `--preset "https://ui.shadcn.com/init?base=radix&style=nova&iconLibrary=lucide&..."` — the `/init` endpoint requires a complete parameter set; the shareable form the CLI itself emits is `https://ui.shadcn.com/create?preset=<code>` (see `preset url`).
+
+> **IMPORTANT:** Never try to decode, fetch, or resolve preset codes by hand or by fetching URLs. Preset codes are opaque — pass them directly to `npx shadcn@latest init --preset <code>` and let the CLI handle resolution. If you need to *see* what a code encodes, run `npx shadcn@latest preset decode <code>`.
+> Use `npx shadcn@latest apply --preset <code>` when overwriting an existing project's preset.
+
+A preset is only the *theme* half. The **base** (`base` / `radix` / `aria`) is a separate axis, set by `--base` at init and stored inside `components.json`'s `style` field as `<base>-<preset>` (e.g. `radix-nova`). Codes do not encode the base.
+
+## Switching Presets
+
+Ask the user first: **overwrite**, **merge**, or **skip** existing components?
+
+- **Overwrite / Re-install** → `npx shadcn@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@latest init --preset <code> --force --no-reinstall`, then run `npx shadcn@latest info` to get the list of installed components and use the [smart merge workflow](#smart-merge-from-upstream) to update them one by one, preserving local changes. Use when the user has customized components.
+- **Skip** → `npx shadcn@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` vs `radix`) 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.

package/skills/fullstack/shadcn/customization.md

@@ -0,0 +1,224 @@
+# Customization & Theming
+
+Components reference semantic CSS variable tokens. Change the variables to change every component.
+
+## Contents
+
+- How it works (CSS variables → Tailwind utilities → components)
+- Color variables and OKLCH format
+- Dark mode setup
+- Changing the theme (presets, CSS variables)
+- Adding custom colors (Tailwind v3 and v4)
+- Border radius
+- Customizing components (variants, className, wrappers)
+- Checking for updates
+
+---
+
+## How It Works
+
+1. CSS variables defined in `:root` (light) and `.dark` (dark mode).
+2. Tailwind maps them to utilities: `bg-primary`, `text-muted-foreground`, etc.
+3. Components use these utilities — changing a variable changes all components that reference it.
+
+---
+
+## Color Variables
+
+Most colors follow the `name` / `name-foreground` convention — the base variable is the background, `-foreground` is the text/icons on it. This is the complete set a preset defines (32 variables); anything not on this list doesn't exist, and a Tailwind utility built from a non-existent token silently produces no styling.
+
+| Variable                                 | Purpose                                       |
+| ---------------------------------------- | --------------------------------------------- |
+| `--background` / `--foreground`          | Page background and default text              |
+| `--card` / `--card-foreground`           | Card surfaces                                 |
+| `--popover` / `--popover-foreground`     | Floating surfaces — Popover, Dropdown, Select, Tooltip content |
+| `--primary` / `--primary-foreground`     | Primary buttons and actions                   |
+| `--secondary` / `--secondary-foreground` | Secondary actions                             |
+| `--muted` / `--muted-foreground`         | Muted surfaces and secondary text             |
+| `--accent` / `--accent-foreground`       | Hover and accent states                       |
+| `--destructive`                          | Error and destructive actions — **no `-foreground` pair** |
+| `--border`                               | Default border color                          |
+| `--input`                                | Form input borders                            |
+| `--ring`                                 | Focus ring color                              |
+| `--chart-1` … `--chart-5`                | Chart/data visualization                      |
+| `--sidebar`, `--sidebar-foreground`, `--sidebar-primary`, `--sidebar-primary-foreground`, `--sidebar-accent`, `--sidebar-accent-foreground`, `--sidebar-border`, `--sidebar-ring` | Sidebar-specific colors |
+| `--radius`                               | Base border radius (see below)                |
+
+**`--destructive` is deliberately unpaired.** The destructive variants are tinted rather than solid — `bg-destructive/10 text-destructive` — so there's no "text on a solid destructive fill" to name. `text-destructive-foreground` is not a real utility; write `text-destructive` on a tinted or transparent background instead.
+
+**There is no `--surface`, `--success`, or `--warning`.** If a design needs them, add them as custom variables (below) rather than assuming they're already in the theme.
+
+Colors use OKLCH: `--primary: oklch(0.205 0 0)` where values are lightness (0–1), chroma (0 = gray), and hue (0–360).
+
+---
+
+## Dark Mode
+
+Class-based toggle via `.dark` on the root element. In Next.js, use `next-themes`:
+
+```tsx
+import { ThemeProvider } from "next-themes"
+
+<ThemeProvider attribute="class" defaultTheme="system" enableSystem>
+  {children}
+</ThemeProvider>
+```
+
+---
+
+## Changing the Theme
+
+```bash
+# Apply a preset code from ui.shadcn.com.
+npx shadcn@latest apply --preset a2r6bw
+
+# Positional shorthand also works.
+npx shadcn@latest apply a2r6bw
+
+# Switch to a named preset and overwrite existing components.
+npx shadcn@latest apply --preset nova
+
+# Re-theme only — leaves component files untouched. Narrower than the overwrite/merge/skip choice.
+npx shadcn@latest apply --preset a2r6bw --only theme
+npx shadcn@latest apply --preset a2r6bw --only font
+
+# Preserve existing components instead.
+npx shadcn@latest init --preset nova --force --no-reinstall
+
+# Use a custom theme URL (the /init endpoint needs a complete parameter set).
+npx shadcn@latest apply --preset "https://ui.shadcn.com/init?base=radix&style=nova&theme=blue&iconLibrary=lucide&..."
+
+# See what a code encodes, or what the project currently uses.
+npx shadcn@latest preset decode a2r6bw
+npx shadcn@latest preset resolve
+```
+
+Named presets: `nova`, `vega`, `maia`, `lyra`, `mira`, `luma`, `sera`, `rhea`.
+
+Or edit CSS variables directly in `globals.css`.
+
+---
+
+## Adding Custom Colors
+
+Add variables to the file at `project.tailwindCss` (absolute path: `config.resolvedPaths.tailwindCss`) from `npx shadcn@latest info` — typically `globals.css`. Never create a new CSS file for this.
+
+```css
+/* 1. Define in the global CSS file. */
+:root {
+  --warning: oklch(0.84 0.16 84);
+  --warning-foreground: oklch(0.28 0.07 46);
+}
+.dark {
+  --warning: oklch(0.41 0.11 46);
+  --warning-foreground: oklch(0.99 0.02 95);
+}
+```
+
+```css
+/* 2a. Register with Tailwind v4 (@theme inline). */
+@theme inline {
+  --color-warning: var(--warning);
+  --color-warning-foreground: var(--warning-foreground);
+}
+```
+
+When `tailwindVersion` is `"v3"` (check via `npx shadcn@latest info`), register in `tailwind.config.js` instead:
+
+```js
+// 2b. Register with Tailwind v3 (tailwind.config.js).
+module.exports = {
+  theme: {
+    extend: {
+      colors: {
+        warning: "oklch(var(--warning) / <alpha-value>)",
+        "warning-foreground":
+          "oklch(var(--warning-foreground) / <alpha-value>)",
+      },
+    },
+  },
+}
+```
+
+```tsx
+// 3. Use in components.
+<div className="bg-warning text-warning-foreground">Warning</div>
+```
+
+---
+
+## Border Radius
+
+`--radius` controls border radius globally. Components derive values from it (`rounded-lg` = `var(--radius)`, `rounded-md` = `calc(var(--radius) - 2px)`).
+
+---
+
+## Customizing Components
+
+See also: [rules/styling.md](./rules/styling.md) for Incorrect/Correct examples.
+
+Prefer these approaches in order:
+
+### 1. Built-in variants
+
+```tsx
+<Button variant="outline" size="sm">
+  Click
+</Button>
+```
+
+### 2. Tailwind classes via `className`
+
+```tsx
+<Card className="mx-auto max-w-md">...</Card>
+```
+
+### 3. Add a new variant
+
+Edit the component source to add a variant via `cva`:
+
+```tsx
+// components/ui/button.tsx
+warning: "bg-warning text-warning-foreground hover:bg-warning/90",
+```
+
+### 4. Wrapper components
+
+Compose shadcn/ui primitives into higher-level components:
+
+```tsx
+export function ConfirmDialog({ title, description, onConfirm, children }) {
+  return (
+    <AlertDialog>
+      <AlertDialogTrigger asChild>{children}</AlertDialogTrigger>
+      <AlertDialogContent>
+        <AlertDialogHeader>
+          <AlertDialogTitle>{title}</AlertDialogTitle>
+          <AlertDialogDescription>{description}</AlertDialogDescription>
+        </AlertDialogHeader>
+        <AlertDialogFooter>
+          <AlertDialogCancel>Cancel</AlertDialogCancel>
+          <AlertDialogAction onClick={onConfirm}>Confirm</AlertDialogAction>
+        </AlertDialogFooter>
+      </AlertDialogContent>
+    </AlertDialog>
+  )
+}
+```
+
+---
+
+## Checking for Updates
+
+```bash
+npx shadcn@latest add button --diff
+```
+
+To preview exactly what would change before updating, use `--dry-run` and `--diff`:
+
+```bash
+npx shadcn@latest add button --dry-run        # see all affected files
+npx shadcn@latest add button --diff button.tsx # see the diff for a specific file
+```
+
+See [Smart Merge from Upstream](./cli.md#smart-merge-from-upstream) for the full smart merge workflow.