@create-ui/cli 0.1.0-beta.1 → 0.5.0

package/dist/skills/createui/contributing.md

@@ -0,0 +1,213 @@
+# Contributing to the Create UI Monorepo
+
+This guide is for contributors working **inside** the Create UI monorepo — adding or editing
+registry components, the CLI, or the documentation site. If you only want to consume Create UI in
+your own app, see [`cli.md`](./cli.md) instead.
+
+## Contents
+
+- [Monorepo layout](#monorepo-layout)
+- [Dev, build & quality commands](#dev-build--quality-commands)
+- [Tests](#tests)
+- [The registry](#the-registry)
+- [Authoring a component](#authoring-a-component)
+- [Scaffolding & validation](#scaffolding--validation)
+- [Testing the CLI locally](#testing-the-cli-locally)
+- [Website: three-layer architecture](#website-three-layer-architecture)
+- [Component rules recap](#component-rules-recap)
+- [Commit convention](#commit-convention)
+
+## Monorepo layout
+
+Create UI is a **pnpm 9.0.6 + Turbo** monorepo with two workspaces:
+
+| Workspace | What it is | Stack |
+|---|---|---|
+| `apps/v4` | Documentation site & component showcase | Next.js 16 (App Router), React 19, Tailwind CSS v4 |
+| `packages/createui` | The `createui` CLI published to npm | Commander.js, tsup (ESM-only) |
+
+The site is also where the **registry** lives (`apps/v4/registry/`). The CLI reads that registry —
+in the monorepo it points at the local dev server (`http://localhost:4000/r`).
+
+## Dev, build & quality commands
+
+Run all commands from the repo root. Package manager is **pnpm** — do not use npm or yarn.
+
+```bash
+# Develop
+pnpm dev            # everything, in parallel via Turbo
+pnpm v4:dev         # docs/showcase site only (port 4000)
+pnpm createui:dev   # CLI only, in watch mode
+
+# Build
+pnpm build          # all workspaces
+pnpm v4:build       # site only
+pnpm createui:build # CLI only
+
+# Quality
+pnpm check          # lint + typecheck + format:check (run this before opening a PR)
+pnpm lint           # ESLint
+pnpm lint:fix       # ESLint with --fix
+pnpm typecheck      # TypeScript
+pnpm format:write   # Prettier write
+pnpm format:check   # Prettier check
+```
+
+## Tests
+
+The test suite needs the v4 dev server running; `pnpm test` handles that for you.
+
+```bash
+pnpm test       # starts the v4 dev server, then runs Vitest
+pnpm test:dev   # runs Vitest against an already-running server (no startup)
+```
+
+## The registry
+
+Every UI component is defined under `apps/v4/registry/` and served to users through the CLI.
+
+```
+apps/v4/registry/
+  ui/         core UI components (button, select, dialog, …)
+  examples/   demos shown in the docs
+  blocks/     larger composed blocks
+  hooks/      custom React hooks
+  lib/        utilities (e.g. cn())
+  internal/   internal-only components (not exposed to users)
+  components/  shared registry components
+```
+
+Each subdirectory has a `_registry.ts` that exports a metadata array, and every array is aggregated
+in `apps/v4/registry/registry.ts`.
+
+In-repo registry entries **omit `content`** — `pnpm registry:build` injects each file's source when
+it generates `apps/v4/public/r/<name>.json`. Real entry shapes:
+
+```ts
+// apps/v4/registry/ui/_registry.ts
+{
+  name: "button",
+  type: "registry:ui",
+  dependencies: ["class-variance-authority", "radix-ui"],
+  files: [{ path: "ui/button.tsx", type: "registry:ui" }],
+}
+
+{
+  name: "select",
+  type: "registry:ui",
+  registryDependencies: ["field", "dropdown-menu"],
+  files: [{ path: "ui/select.tsx", type: "registry:ui" }],
+}
+```
+
+The `type` values, file objects (`{ path, type, content?, target? }`), and item fields are defined by
+the registry-item schema (`$schema: https://createui.co/schema/registry-item.json`). Use
+`dependencies` for npm packages and `registryDependencies` for other registry items the component
+needs.
+
+## Authoring a component
+
+1. Create `apps/v4/registry/ui/<name>.tsx`:
+   - use **`cva`** for variants and **`cn()`** (from `@/registry/lib/utils`) to merge classes
+   - put `data-slot="<name>"` on the root element
+   - support polymorphism with **`asChild`** via the Radix `Slot`
+   - type props as `React.ComponentProps<"el"> & VariantProps<typeof variants> & { … }`
+   - use a **named export** (`export { Name }`)
+2. Add an entry to `apps/v4/registry/ui/_registry.ts` (shape above).
+3. Add a demo under `apps/v4/registry/examples/<name>-demo.tsx` and register it in
+   `apps/v4/registry/examples/_registry.ts`.
+4. Run **`pnpm registry:build`** to rebuild the registry (it also runs `lint:fix` + format and
+   regenerates the `public/r/*.json` files).
+
+> Filenames are **kebab-case**; exports are PascalCase named exports. There is **no** `pnpm tokens:build` —
+> tokens live in `apps/v4/styles/globals.css` and are edited directly.
+
+## Scaffolding & validation
+
+```bash
+pnpm scaffold <name>              # create a component + example + registry entry
+pnpm scaffold <name> --existing   # generate an example from an existing component (parses CVA)
+pnpm scaffold <name> --dry-run    # preview output without writing files
+pnpm scaffold <name> --force      # overwrite existing files
+
+pnpm validate:registries          # validate every _registry.ts against the schema
+```
+
+## Testing the CLI locally
+
+The root `pnpm createui` script runs the **local CLI build** against `http://localhost:4000/r`, so
+start the site first:
+
+```bash
+pnpm v4:dev                          # serves the local registry at http://localhost:4000/r
+pnpm createui add -c ~/path/to/app   # run the local CLI against a target app
+```
+
+`-c` (`--cwd`) points at the project you want to add components to.
+
+## Website: three-layer architecture
+
+Site work follows a strict three-layer model:
+
+```
+registry/ui/            primitives — SACROSANCT, never edited by site work
+  ↓ composed by
+components/site/         shared composites (reused across ≥2 route groups)
+  ↓ composed by
+app/(group)/_components/ route-local composites (used by one route group)
+```
+
+A new composite belongs in `components/site/` only if it is reused across **two or more** route
+groups; otherwise it lives in the route group's `_components/`. If a primitive is missing, **ask
+first** — never edit `registry/ui/` to make a page work.
+
+The authoritative website guides live in **`mds/website/`** — start at
+[`mds/website/BRIEF.md`](../../mds/website/BRIEF.md) (it is written in Turkish). Consult those guides
+for any website task; do not duplicate them here.
+
+## Component rules recap
+
+These conventions keep every component consistent (see [`rules/styling.md`](./rules/styling.md),
+[`rules/composition.md`](./rules/composition.md), and [`rules/icons.md`](./rules/icons.md) for the
+full rules):
+
+- **`data-slot`** on the root element (and on meaningful sub-parts) for semantic styling hooks.
+- **`cn()`** for all class merging — never string-concatenate classes.
+- **`cva`** for variant-based styling; hoist the variants object out of the component.
+- **Semantic tokens** for color: `bg-primary-base`, `text-error-base`, `bg-weak`, `text-body` —
+  never `bg-background` / `text-foreground`-style names.
+- **Radix UI** primitives for accessibility; polymorphism via **`asChild`** + Radix `Slot` only.
+- **Focus is `outline-*`**, never `ring-*` (e.g. `focus-visible:outline-primary-700`).
+- Intersection prop types: `React.ComponentProps<"button"> & VariantProps<…> & { … }`.
+- **kebab-case** filenames, **named** exports.
+
+A correct root element looks like:
+
+```tsx
+// Incorrect — ring focus, shadcn-style token, anonymous default export
+<button className={`${base} focus-visible:ring-2 bg-primary`}>{children}</button>
+
+// Correct — data-slot, cn(), outline focus, semantic token
+<Comp
+  data-slot="button"
+  className={cn(buttonVariants({ variant, appearance, size, className }))}
+  {...props}
+/>
+```
+
+When you reference a component in an example, **read its source** at
+`apps/v4/registry/ui/<name>.tsx` first — never guess props. For instance, `Button` takes
+`variant` (`primary` | `neutral-solid` | `neutral-light` | `danger` | `success` | `inverse-solid` |
+`inverse-light`), `appearance` (`solid` | `outline` | `ghost` | `soft`), `size`, `shape`, `loading`,
+`iconOnly`, `leadingIcon`, `trailingIcon`, and `asChild` — there is no `variant="outline"` or
+`variant="destructive"`.
+
+## Commit convention
+
+Conventional commits: `category(scope): message`.
+
+Categories: `feat`, `fix`, `refactor`, `docs`, `build`, `test`, `ci`, `chore`.
+
+```
+feat(components): add loading prop to the button component
+```

package/dist/skills/createui/customization.md

@@ -0,0 +1,284 @@
+# Customization & Theming
+
+Create UI is **one styling system with many themes**. Components reference semantic CSS variable tokens; change the tokens (or swap the theme) and every component follows. Values are **HEX**, never OKLCH.
+
+## Contents
+
+- How it works (CSS variables → Tailwind utilities → components)
+- Token families (surfaces, text, primary scale, status, shadows, focus, radius)
+- shadcn → Create UI token map (for migrants)
+- Semantic spacing & typography tokens
+- Theming (primary themes, neutral themes, font variants)
+- Dark mode setup
+- Adding a custom color / changing radius
+- Customizing components (props, className, variants, wrappers)
+- Checking for updates
+
+---
+
+## How It Works
+
+1. CSS variables are defined in `:root` (light) and overridden under `.dark` (dark mode), as **HEX** values.
+2. Tailwind v4 auto-generates utilities from those `--color-*` / `--spacing-*` / `--radius-*` variables (`bg-weakest`, `text-body`, `gap-component-sm`, …).
+3. Components consume those utilities — change a variable, or swap the active theme, and every component that references it updates.
+
+There is no OKLCH, no `--primary`/`--muted` convention, and no parallel style/base stack. One system, layered themes.
+
+---
+
+## Token Families
+
+Create UI uses **semantic** token names. Backgrounds, borders, and text share a weak→strong scale; status colors and the primary scale have their own families.
+
+### Surfaces
+
+| Utility | Purpose |
+| --- | --- |
+| `bg-weakest` … `bg-strongest` | Neutral surface scale (`weakest`, `weak`, `light`, `medium`, `heavy`, `strong`, `strongest`) |
+| `bg-static` | Page/card surface that swaps with theme (white in light, black in dark) |
+| `bg-static-white` / `bg-static-black` | Surfaces that never swap |
+| `border-weakest` … `border-strongest` | Border scale (use `border-light` / `border-medium` for inputs and dividers) |
+
+### Text
+
+| Utility | Purpose |
+| --- | --- |
+| `text-body` | Default body text |
+| `text-placeholder` | Hints, secondary, muted text |
+| `text-disabled` | Disabled text |
+| `text-strongest` | High-contrast headings |
+| `text-static` / `text-static-white` | Text that never swaps with theme |
+
+### Primary scale
+
+`bg-primary-50` … `bg-primary-950`, plus `bg-primary-base` (= `bg-primary-500`), `text-primary-base`, and the alphas `bg-primary-alpha-16` / `bg-primary-alpha-48` (subtle/hover tints). Focus uses `outline-primary-500` / `outline-primary-700`.
+
+### Status families
+
+Each of `error`, `success`, `warning`, `info` has a `-base` plus a `-weakest` … `-strongest` scale, e.g. `bg-error-base`, `text-error-base`, `outline-error-strongest`, `bg-success-base`, `bg-info-base`. **Prefer the semantic status tokens** in your own code. The shipped Button implements its danger/success variants with the raw `red-*` / `green-*` scales (e.g. `bg-red-600`, `bg-red-alpha-16`) — that is the implementation detail, not a pattern you need to copy.
+
+### Shadows
+
+Neutral elevation: `shadow-neutral-{2xs,xs,sm,md,lg,…}`. Component state shadows: `shadow-component-{primary,neutral,error,success,info,inverted}-{default,hover,focused}`. Text shadows: `text-shadow-{2xs,xs,…}`.
+
+### Focus
+
+Focus is an **outline**, never a ring. The pattern is a transparent base outline that becomes visible on focus:
+
+```tsx
+"outline-2 outline-transparent focus-visible:outline-primary-700"
+```
+
+Use `outline-primary-700` (or `outline-strongest` / `outline-strong`) for focus. Never use `ring-*`.
+
+### Radius
+
+`--radius-none/xs/sm/md/lg/xl/2xl/3xl/4xl/5xl/full` back the `rounded-sm`/`rounded-md`/`rounded-lg`/`rounded-xl`/`rounded-2xl` utilities. Radius is set per component (e.g. Button maps each size to a radius via compound variants).
+
+---
+
+## shadcn → Create UI Token Map
+
+If you are migrating markup written against shadcn token names, translate them:
+
+| shadcn | Create UI |
+| --- | --- |
+| `bg-background` | `bg-static` |
+| `bg-card` | `bg-static` (or `bg-weakest` for subtle surfaces) |
+| `text-foreground` | `text-body` |
+| `text-muted-foreground` | `text-placeholder` |
+| `bg-primary` | `bg-primary-base` (or `bg-primary-500`) |
+| `text-primary-foreground` | `text-white` (on solid primary) |
+| `border-border` / `border-input` | `border-light` or `border-medium` |
+| `bg-muted` | `bg-weak` |
+| `bg-destructive` | `bg-error-base` |
+| `text-destructive` | `text-error-base` |
+| `bg-accent` | `bg-primary-alpha-16` |
+| `ring-ring` (focus) | `outline-primary-700` (primary) / `outline-strong` (neutral) |
+
+---
+
+## Semantic Spacing & Typography Tokens
+
+Tailwind v4 also auto-generates spacing and typography utilities from `--spacing-*` and the typography tokens. These **mirror Figma's semantic variables**.
+
+### Spacing
+
+| Family | Utilities |
+| --- | --- |
+| component | `gap-component-none`, `gap-component-xs`, `gap-component-sm`, `p-component-md`, `gap-component-lg`, `p-component-xl`, `px-component-none` |
+| layout | `gap-layout-xs`, `p-layout-sm`, `gap-layout-md`, `p-layout-lg`, `p-layout-xl` |
+
+**Figma-token rule:** use a semantic spacing class **only when Figma references a semantic token** (e.g. `var(--component/sm,8px)` → `gap-component-sm`). When Figma shows a static value (`space-space-4`), use the standard Tailwind class (`gap-4`). Prefer `px-component-none` over `px-0` when it is an intentional "no padding" override of a token.
+
+### Typography
+
+`text-display-{lg,xl}`, `text-heading-h1` … `text-heading-h6`, `text-body-{xs,sm,md,lg,xl}`, `text-paragraph-{xs…xl}`, `text-ui-{xs,sm,md,lg,xl}`, `text-ui-overline-*`, `text-ui-caption-*`, `text-numeric-{xs…xl}`.
+
+Spacing and typography tokens **auto-scale across breakpoints** — never add `md:` / `xl:` prefixes to `gap-component-sm`, `text-heading-h2`, and the like.
+
+---
+
+## Theming
+
+One system, many themes. A theme is a swappable **token set** (a `registry:theme` item carrying a `primary` 50…950 palette), layered on the single foundation — it is not a style/base split and not a preset color.
+
+- **Primary themes (8):** `indigo` (default), `blue`, `lime`, `green`, `red`, `orange`, `yellow`, `cyan`
+- **Neutral themes (5):** `gray` (default), `slate`, `zinc`, `base`, `stone`
+- **Font variants:** `v1` (Geist + JetBrains Mono)
+
+Pick a theme at init, interactively or via flags:
+
+```bash
+npx @create-ui/cli init --theme blue --neutral slate --font-variant v1
+```
+
+`init` applies the choice by adding the matching registry items (`theme-<primary>`, `neutral-<neutral>`, `font-variant-<v>`). There is **no `apply` command** and **no preset codes** — to change theme later, re-run `init` with new flags or edit the token variables in your global CSS.
+
+---
+
+## Dark Mode
+
+Toggle the `.dark` class on the root element; tokens swap automatically. In Next.js, use `next-themes`:
+
+```tsx
+import { ThemeProvider } from "next-themes"
+
+<ThemeProvider attribute="class" defaultTheme="system" enableSystem>
+  {children}
+</ThemeProvider>
+```
+
+Because every color is a token that already has a `.dark` override, **never write manual `dark:` color overrides** on components — let the tokens do the work.
+
+---
+
+## Adding a Custom Color / Changing Radius
+
+Edit the project's global CSS file — the `tailwind.css` path reported by `createui info` (typically `app/globals.css`). **Never create a new CSS file** for this.
+
+Define the HEX scale under `:root` (and `.dark`), then expose it to Tailwind in the same file:
+
+```css
+/* app/globals.css */
+:root {
+  --color-brand-50: #eef6ff;
+  --color-brand-500: #2f7bff;
+  --color-brand-900: #14315f;
+  --radius-lg: 0.75rem; /* override radius */
+}
+
+.dark {
+  --color-brand-500: #5a96ff;
+}
+```
+
+Tailwind v4 auto-generates the utilities (`bg-brand-500`, `text-brand-900`, …) from those `--color-*` variables:
+
+```tsx
+<div className="bg-brand-50 text-brand-900">Brand surface</div>
+```
+
+To restyle existing components, override the semantic tokens themselves (e.g. redefine the `primary` scale or a status family) rather than adding new ones. (There is no token build step to run — editing the CSS is the whole change.)
+
+---
+
+## Customizing Components
+
+See also: [rules/styling.md](./rules/styling.md) for Incorrect/Correct examples.
+
+Prefer these approaches, in order.
+
+### 1. Built-in props
+
+Reach for the component's own API first. For example, `Button` exposes `variant`, `appearance`, `size`, `shape`, `loading`, `iconOnly`, `leadingIcon`, `trailingIcon`, and `asChild`:
+
+```tsx
+import { Button } from "@/components/ui/button"
+
+<Button appearance="outline" size="sm">Save</Button>
+<Button variant="danger">Delete</Button>
+<Button loading>Saving…</Button>
+```
+
+### 2. Tailwind classes via `className`
+
+Use `className` for layout and spacing, not for re-coloring the variant:
+
+```tsx
+import { cn } from "@/lib/utils"
+import { Card } from "@/components/ui/card"
+
+<Card className={cn("mx-auto max-w-md")}>...</Card>
+```
+
+### 3. Add a CVA variant in the source
+
+If you need a new look, add it to the component's `cva` config in the source, using real Create UI tokens:
+
+```tsx
+// components/ui/button.tsx — add to the buttonVariants config
+warning: "bg-warning-base text-static-white hover:bg-warning-strong",
+```
+
+### 4. Wrapper components
+
+Compose Create UI primitives into higher-level components. Verify each primitive's props (`Button` has `variant="danger"`, not `variant="destructive"`):
+
+```tsx
+import { Button } from "@/components/ui/button"
+import {
+  Dialog,
+  DialogClose,
+  DialogContent,
+  DialogDescription,
+  DialogFooter,
+  DialogHeader,
+  DialogTitle,
+  DialogTrigger,
+} from "@/components/ui/dialog"
+
+export function ConfirmDialog({ title, description, onConfirm, children }) {
+  return (
+    <Dialog>
+      <DialogTrigger asChild>{children}</DialogTrigger>
+      <DialogContent>
+        <DialogHeader>
+          <DialogTitle>{title}</DialogTitle>
+          <DialogDescription>{description}</DialogDescription>
+        </DialogHeader>
+        <DialogFooter>
+          <DialogClose asChild>
+            <Button appearance="outline">Cancel</Button>
+          </DialogClose>
+          <Button variant="danger" onClick={onConfirm}>
+            Confirm
+          </Button>
+        </DialogFooter>
+      </DialogContent>
+    </Dialog>
+  )
+}
+```
+
+---
+
+## Checking for Updates
+
+To see which installed components differ from the registry, use the `diff` command:
+
+```bash
+# List components that have updates available.
+npx @create-ui/cli diff
+
+# Show what changed upstream for one component.
+npx @create-ui/cli diff button
+```
+
+When you re-add a component, pass `--overwrite` to replace local files:
+
+```bash
+npx @create-ui/cli add button --overwrite
+```
+
+See [Updating Components in SKILL.md](./SKILL.md#updating-components) for the full workflow.

package/dist/skills/createui/evals/evals.json

@@ -0,0 +1,47 @@
+{
+  "skill_name": "createui",
+  "evals": [
+    {
+      "id": 1,
+      "prompt": "I'm building a Next.js app with Create UI (lucide icons). Create a settings form component with fields for: full name, email address, and notification preferences (email, SMS, push notifications as on/off toggles). Add validation states for required fields.",
+      "expected_output": "A React component using FieldGroup, Field, Switch, data-invalid/aria-invalid validation, gap-* spacing, and Create UI semantic tokens.",
+      "files": [],
+      "expectations": [
+        "Uses FieldGroup and Field components for form layout instead of a raw div with space-y",
+        "Uses Switch for independent on/off notification toggles (not looping Button with manual active state)",
+        "Uses data-invalid on Field and aria-invalid on the input control for validation states",
+        "Uses gap-* (e.g. gap-4, gap-6) instead of space-y-* or space-x-* for spacing",
+        "Uses Create UI semantic tokens (e.g. bg-static, text-body, text-placeholder, text-error-base) — never shadcn tokens like bg-background/text-muted-foreground or raw colors like bg-red-500",
+        "No manual dark: color overrides (tokens swap via the .dark class)"
+      ]
+    },
+    {
+      "id": 2,
+      "prompt": "Create a dialog component for editing a user profile. It should have the user's avatar at the top, input fields for name and bio, and Save/Cancel buttons with appropriate icons. Using Create UI with lucide icons.",
+      "expected_output": "A React component with DialogTitle, Avatar+AvatarFallback, Button with leadingIcon/trailingIcon props, no icon sizing classes, asChild for custom triggers.",
+      "files": [],
+      "expectations": [
+        "Includes DialogTitle for accessibility (visible or with an sr-only class)",
+        "Avatar component includes AvatarFallback",
+        "Icons on buttons are passed via the leadingIcon/trailingIcon props (never a data-icon attribute, which does not exist in Create UI)",
+        "No sizing classes on icons inside components (no size-4, w-4, h-4, etc.) — the component sizes icons via CVA",
+        "Uses the Button loading prop for the pending Save state instead of manually composing a Spinner",
+        "Uses asChild for custom triggers (Radix Slot)"
+      ]
+    },
+    {
+      "id": 3,
+      "prompt": "Create a dashboard component that shows 4 stat cards in a grid. Each card has a title, large number, a percentage-change badge, and a loading skeleton state. Using Create UI with lucide icons.",
+      "expected_output": "A React component with full Card composition, Skeleton for loading, a Badge/StatusBadge for the change, Create UI semantic tokens, and gap-* spacing.",
+      "files": [],
+      "expectations": [
+        "Uses full Card composition with CardHeader, CardTitle, CardContent (not dumping everything into CardContent)",
+        "Uses the Skeleton component for loading placeholders instead of custom animate-pulse divs",
+        "Uses a Badge or StatusBadge for the percentage change instead of custom styled spans",
+        "Uses Create UI semantic tokens (e.g. text-body, text-strongest, text-success-base) instead of shadcn tokens or raw colors like bg-green-500",
+        "Uses gap-* instead of space-y-* or space-x-* for spacing",
+        "Uses size-* when width and height are equal instead of separate w-* h-*"
+      ]
+    }
+  ]
+}

package/dist/skills/createui/mcp.md

@@ -0,0 +1,151 @@
+# Create UI MCP Server
+
+The Create UI MCP server lets AI assistants browse, search, and install components from registries through the Model Context Protocol.
+
+## Contents
+
+- [Setup](#setup)
+- [Available Tools](#available-tools)
+- [Configuring Registries](#configuring-registries)
+- [Usage Examples](#usage-examples)
+
+## Setup
+
+Start the MCP stdio server with:
+
+```bash
+npx @create-ui/cli mcp
+```
+
+To write the configuration file for your MCP client, run:
+
+```bash
+npx @create-ui/cli mcp init --client claude
+```
+
+Supported clients and the config path each one writes:
+
+| Client | Config path |
+| --- | --- |
+| `claude` | `.mcp.json` |
+| `cursor` | `.cursor/mcp.json` |
+| `vscode` | `.vscode/mcp.json` |
+| `codex` | `.codex/config.toml` |
+| `opencode` | `opencode.json` |
+
+The generated config always runs `npx createui@latest mcp`. For example, the `claude` client writes:
+
+```json
+{
+  "mcpServers": {
+    "createui": {
+      "command": "npx",
+      "args": ["createui@latest", "mcp"]
+    }
+  }
+}
+```
+
+## Available Tools
+
+The MCP server exposes seven tools:
+
+### get_project_registries
+
+Returns the registries configured in the current project's `components.json`.
+
+**Inputs:** none
+
+### list_items_in_registries
+
+Lists all items available in the specified registries.
+
+**Inputs:**
+- `registries` (string[]) — registry namespaces to query
+- `limit` (number, optional)
+- `offset` (number, optional)
+
+### search_items_in_registries
+
+Searches for items across registries by query string.
+
+**Inputs:**
+- `registries` (string[])
+- `query` (string)
+- `limit` (number, optional)
+- `offset` (number, optional)
+
+### view_items_in_registries
+
+Returns detailed information about specific items.
+
+**Inputs:**
+- `items` (string[]) — e.g. `@createui/button`
+
+### get_item_examples_from_registries
+
+Finds example and demo code for items.
+
+**Inputs:**
+- `registries` (string[])
+- `query` (string)
+
+### get_add_command_for_items
+
+Returns the `add` command for the specified items.
+
+**Inputs:**
+- `items` (string[])
+
+### get_audit_checklist
+
+Returns a checklist to verify after adding components.
+
+**Inputs:** none
+
+> **Tip:** The MCP server has no equivalent for inspecting project configuration. To print the resolved aliases, framework, and Tailwind setup, run the `info` command directly: `npx @create-ui/cli info`.
+
+## Configuring Registries
+
+Configure additional registries under the `registries` field in `components.json`:
+
+```json
+{
+  "registries": {
+    "@acme": "https://acme.com/r/{name}.json",
+    "@private": {
+      "url": "https://api.company.com/r/{name}.json",
+      "headers": {
+        "Authorization": "Bearer ${MY_TOKEN}"
+      }
+    }
+  }
+}
+```
+
+- Registry namespaces must start with `@`.
+- A registry can be a plain URL string (`@acme`) or an object with `url`, `headers`, and `params` (`@private`).
+- URL templates contain a `{name}` placeholder that is replaced with the item name.
+- `${VAR}` expands from environment variables, which is useful for tokens and secrets.
+
+The `@createui` registry is always built-in and available without any configuration.
+
+## Usage Examples
+
+Browse the Create UI registry:
+
+```
+Show me all available components in @createui
+```
+
+Search for a component:
+
+```
+Search for a date picker in @createui
+```
+
+Install a component:
+
+```
+Add the button and card components from @createui
+```