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

package/dist/schema/index.js

@@ -1,2 +1,2 @@
-export{B as configJsonSchema,d as configSchema,t as iconsSchema,A as presetSchema,c as rawConfigSchema,y as registriesIndexSchema,z as registriesSchema,u as registryBaseColorSchema,a as registryConfigItemSchema,b as registryConfigSchema,r as registryIndexSchema,o as registryItemCommonSchema,k as registryItemCssSchema,i as registryItemCssVarsSchema,l as registryItemEnvVarsSchema,g as registryItemFileSchema,m as registryItemFontSchema,n as registryItemFontVariantSchema,p as registryItemSchema,h as registryItemTailwindSchema,j as registryItemThemePrimarySchema,f as registryItemTypeSchema,v as registryResolvedItemsTreeSchema,q as registrySchema,w as searchResultItemSchema,x as searchResultsSchema,s as stylesSchema,e as workspaceConfigSchema}from'../chunk-TIYHWTW7.js';//# sourceMappingURL=index.js.map
+export{w as configJsonSchema,b as configSchema,r as iconsSchema,v as presetSchema,a as rawConfigSchema,p as registryIndexSchema,m as registryItemCommonSchema,i as registryItemCssSchema,g as registryItemCssVarsSchema,j as registryItemEnvVarsSchema,e as registryItemFileSchema,k as registryItemFontSchema,l as registryItemFontVariantSchema,n as registryItemSchema,f as registryItemTailwindSchema,h as registryItemThemePrimarySchema,d as registryItemTypeSchema,s as registryResolvedItemsTreeSchema,o as registrySchema,t as searchResultItemSchema,u as searchResultsSchema,q as stylesSchema,c as workspaceConfigSchema}from'../chunk-Y7WZRQWW.js';//# sourceMappingURL=index.js.map
 //# sourceMappingURL=index.js.map

package/dist/skills/createui/SKILL.md

@@ -0,0 +1,212 @@
+---
+name: createui
+description: Manages Create UI components and projects — adding, searching, viewing, theming, composing, and contributing UI. Provides project context, component patterns, and Create UI semantic tokens. Use when working with the createui CLI (init/add/create/diff/view/search/migrate/mcp), a components.json file, the @createui registry, authoring components with Create UI tokens and themes, or contributing to the Create UI monorepo.
+user-invocable: false
+allowed-tools: Bash(npx @create-ui/cli *), Bash(pnpm createui *), Bash(pnpm dlx @create-ui/cli *)
+---
+
+# Create UI
+
+Create UI is a design code system: **one unified styling system + many themes**. Components are added as source code into the user's project via the `createui` CLI, and styled with Create UI's own semantic tokens.
+
+It evolved from the shadcn/ui architecture (registry + components-as-source) but is its own system — its own CLI (`createui`), its own registry (`@createui`), and its own tokens and themes. There is no style/base split.
+
+> **IMPORTANT:** Run published CLI commands with `npx @create-ui/cli <command>` (or `pnpm dlx @create-ui/cli <command>`). Inside this monorepo, contributors use `pnpm createui <command>` against the local registry — see [contributing.md](./contributing.md).
+
+## Current Project Context
+
+Run the `info` command to read the project's config and installed components:
+
+```bash
+npx @create-ui/cli info
+```
+
+`info` prints project info plus the contents of `components.json` (config, aliases, `tailwind.css` path, `iconLibrary`, registries). Run it before adding or editing components so imports, the icon library, and `"use client"` advice match the real project. (There is no `--json` flag.)
+
+## Two Audiences
+
+- **Using Create UI in your app** — install components with the CLI, then compose them with the patterns and rules below.
+- **Contributing to this monorepo** — authoring components, the registry build, dev/test scripts → see [contributing.md](./contributing.md).
+
+## Principles
+
+1. **Use existing components first.** Search the registry before writing custom UI: `npx @create-ui/cli search @createui -q "sidebar"`.
+2. **Compose, don't reinvent.** Settings page = Tabs + Card + Field controls. Dashboard = Sidebar + Card + Chart + Table.
+3. **Use built-in props before custom classes.** `variant`, `appearance`, `size`, `shape` on `Button`; `size` on `Field` — reach for these before `className`.
+4. **Use semantic tokens, never raw values.** `bg-static`, `text-body`, `bg-primary-base` — never `bg-blue-500` or hardcoded hex.
+
+## Critical Rules
+
+These rules are **always enforced**. Each links to a file with Incorrect/Correct code pairs.
+
+### Styling & Tailwind → [styling.md](./rules/styling.md)
+
+- **Use Create UI semantic tokens.** Surfaces `bg-static` / `bg-weak`, text `text-body` / `text-placeholder`, primary `bg-primary-base`. Never raw colors.
+- **`className` for layout, not styling.** Don't override a component's colors or typography.
+- **No `space-x-*` / `space-y-*`.** Use `flex` + `gap-*` (`flex flex-col gap-4` for vertical stacks).
+- **Use `size-*` when width equals height.** `size-10`, not `w-10 h-10`.
+- **Focus is `outline-*`, never `ring-*`.** Components use `outline-2 outline-transparent` + `focus-visible:outline-primary-700`.
+- **Semantic spacing classes only when Figma references a token.** `var(--component/sm,8px)` → `gap-component-sm`; a static `space-space-4` → `gap-4`.
+- **Use `cn()` for conditional classes.** Not manual template-literal ternaries.
+
+### Forms & Inputs → [forms.md](./rules/forms.md)
+
+- **Forms use `FieldGroup` + `Field`.** Never raw `div` + `space-y-*` for form layout.
+- **`Field` owns size; children inherit it.** Set `size` on `Field` (`xs` | `sm` | `md`); `Input`, `Select`, etc. read it via context — never downgrade a child.
+- **`InputGroup` uses `InputGroupControl` / `InputGroupTextarea`.** Never a raw `Input` / `Textarea` inside `InputGroup`.
+- **Option sets (2–7 choices) use `ToggleGroup`** with `type="single"` / `"multiple"`. Don't loop `Button` with manual active state.
+- **`FieldSet` + `FieldLegend` group related checkboxes/radios.** Not a `div` with a heading.
+- **Validation: `data-invalid` on `Field`, `aria-invalid` on the control.** 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`.
+- **Use `asChild` for custom triggers.** Polymorphism is `asChild` + Radix `Slot` — `<Button asChild><Link href="/x">Docs</Link></Button>`.
+- **`Button` HAS a real `loading` prop.** `<Button loading>Saving…</Button>` renders a Spinner and blocks interaction — don't compose your own.
+- **Use the right `Button` API.** `variant` (`primary` / `danger` / `success` / `neutral-solid` / …) + `appearance` (`solid` / `outline` / `ghost` / `soft`). There is no `variant="outline"`/`"destructive"`/`"secondary"`.
+- **Dialog / Sheet / Drawer need a Title.** `DialogTitle` etc. for accessibility (`className="sr-only"` if hidden).
+- **Use full Card composition.** `CardHeader` / `CardTitle` / `CardDescription` / `CardContent` / `CardFooter`.
+- **`Avatar` always needs `AvatarFallback`.**
+- **Prefer components over custom markup.** Callouts → `Alert`; empty states → `Empty`; dividers → `Separator`; loading → `Skeleton`; tags → `Badge`; toasts → `toast()` from `sonner`.
+
+### Icons → [icons.md](./rules/icons.md)
+
+- **Icons in `Button` go through props.** `leadingIcon` / `trailingIcon` (and `iconOnly` for icon-only buttons) — no `data-icon`.
+- **No sizing classes on icons inside components.** The component sets icon size via CVA — no `size-4` / `w-4 h-4`.
+- **Pass icons as components, not string keys.** `icon={CheckIcon}`, never `icon="check"`.
+- **Match the project's `iconLibrary`.** Default `lucide` → `lucide-react`. After adding a component, swap any registry icon imports to the project's library.
+
+## Key Patterns
+
+The most common idioms that differentiate correct Create UI code. For edge cases, see the linked rule files above.
+
+```tsx
+import { Button } from "@/components/ui/button"
+import { Field, FieldGroup, FieldLabel, FieldDescription } from "@/components/ui/field"
+import { Input } from "@/components/ui/input"
+import { ArrowRightIcon, SearchIcon } from "lucide-react"
+import Link from "next/link"
+
+// Button: appearance + icon props + loading. No variant="outline", no data-icon.
+<Button appearance="outline" leadingIcon={<SearchIcon />}>Search</Button>
+<Button loading>Saving…</Button>
+<Button asChild appearance="ghost" trailingIcon={<ArrowRightIcon />}>
+  <Link href="/docs">Docs</Link>
+</Button>
+
+// Forms: FieldGroup + Field. Field owns size; Input inherits it.
+<FieldGroup>
+  <Field size="md">
+    <FieldLabel htmlFor="email">Email</FieldLabel>
+    <Input id="email" type="email" />
+    <FieldDescription>We'll never share it.</FieldDescription>
+  </Field>
+</FieldGroup>
+
+// Spacing: gap-component-sm only when Figma uses a token; otherwise gap-4.
+<div className="flex flex-col gap-4">…</div>
+
+// Conditional classes via cn().
+<div className={cn("rounded-lg p-4", isActive && "bg-weak")} />
+```
+
+## Component Selection
+
+| Need                       | Use                                                                                                                    |
+| -------------------------- | --------------------------------------------------------------------------------------------------------------------- |
+| Button / action            | `Button` (`variant` + `appearance`), `ButtonGroup`, `CloseButton`, `SocialLoginButton`                                 |
+| Form inputs                | `Input`, `Textarea`, `Select`, `NativeSelect`, `Combobox`, `Switch`, `Checkbox`, `Radio`, `RadioGroup`, `InputOTP`, `InputStepper`, `Slider`, `Calendar` |
+| Toggle between 2–7 options | `ToggleGroup` + `ToggleGroupItem`, or `SegmentedControl`                                                               |
+| Inputs with affordances    | `InputGroup` + `InputGroupAddon`, `PasswordStrength`                                                                   |
+| Data display               | `Table`, `Card`, `Item`, `Badge`, `StatusBadge`, `Chip`, `Avatar`, `CountryFlag`, `Kbd`                               |
+| Navigation                 | `Sidebar`, `NavigationMenu`, `Breadcrumb`, `Tabs`, `TabMenu`, `Pagination`, `TextLink`                                |
+| Overlays                   | `Dialog` (modal), `Sheet` (side panel), `Drawer` (bottom sheet), `AlertDialog` (confirmation), `Popover`              |
+| Feedback                   | `sonner` (toast), `Alert`, `AlertBanner`, `InlineAlert`, `Progress`, `Skeleton`, `Spinner`                            |
+| Command palette            | `Command` inside `Dialog`                                                                                              |
+| Charts                     | `Chart` (wraps Recharts)                                                                                               |
+| Layout                     | `Card`, `Separator`, `Resizable`, `ScrollArea`, `Accordion`, `Collapsible`, `AspectRatio`, `Carousel`                 |
+| Empty states               | `Empty`                                                                                                                |
+| Menus                      | `DropdownMenu`, `ContextMenu`, `Menubar`                                                                               |
+| Tooltips / info            | `Tooltip`, `InfoTooltip`, `HoverCard`, `Popover`                                                                       |
+
+## Key Fields (components.json)
+
+`info` surfaces these fields — read them before writing imports or advising on directives:
+
+- **`aliases`** — the import prefixes (`components`, `utils`, `ui`, `lib`, `hooks`). Use the actual aliases (e.g. `@/components/ui`, `@/lib/utils`), never hardcode.
+- **`rsc`** — when `true`, components using `useState`, `useEffect`, event handlers, or browser APIs need `"use client"` at the top.
+- **`tsx`** — whether components are emitted as `.tsx` (default `true`).
+- **`tailwind.css`** — the global CSS file where tokens are defined. Edit this file; never create a new one.
+- **`iconLibrary`** — drives icon imports (default `lucide` → `lucide-react`). Never assume.
+- **`menuColor`** (`default` | `inverted`) / **`menuAccent`** (`subtle` | `bold`) — menu surface treatment.
+- **`registries`** — extra registries beyond `@createui`, e.g. `{ "@acme": "https://acme.com/r/{name}.json" }`.
+
+See [cli.md — `info`](./cli.md) and [customization.md](./customization.md) for the full reference.
+
+## Workflow
+
+1. **Get project context** — `npx @create-ui/cli info`.
+2. **Check installed components first** — before `add`, check the `components` list from `info` or list the `ui` alias directory. Don't import un-added components, and don't re-add installed ones.
+3. **Find components** — `npx @create-ui/cli search @createui -q "<query>"`.
+4. **Inspect before adding** — `npx @create-ui/cli view @createui/<name>` to see an item's metadata and files; `npx @create-ui/cli diff <name>` to see what changed upstream for an installed one.
+5. **Add** — `npx @create-ui/cli add <name>`.
+6. **Review added files** — read them and verify composition (e.g. `SelectItem` inside `SelectGroup`), imports, and adherence to the Critical Rules. **Replace any icon imports with the project's `iconLibrary`** (e.g. registry `lucide-react` → the project's library), adjusting icon names accordingly.
+7. **Registry must be explicit** — if the user doesn't say which registry, ask. Don't default on their behalf.
+
+## Updating Components
+
+To keep local edits while pulling upstream changes, use the `diff` command — **never fetch raw files manually.**
+
+1. `npx @create-ui/cli diff` — list installed components that have updates.
+2. `npx @create-ui/cli diff <name>` — show what changed upstream for that component.
+3. Decide per component: no local changes → re-add; has local changes → read the local file, study the diff, apply upstream changes while preserving your edits.
+4. `npx @create-ui/cli add <name> --overwrite` replaces files — **only with the user's explicit approval.**
+
+## Quick Reference
+
+```bash
+# Initialize an existing project (writes components.json, installs deps).
+npx @create-ui/cli init
+npx @create-ui/cli init --theme indigo --neutral gray --font-variant v1
+
+# Scaffold a new project (or run with no name to build a custom design system in the browser).
+npx @create-ui/cli create my-app --template next
+npx @create-ui/cli create
+
+# Add components.
+npx @create-ui/cli add button card dialog
+npx @create-ui/cli add @createui/select
+npx @create-ui/cli add --all
+
+# Inspect the registry.
+npx @create-ui/cli search @createui -q "sidebar"
+npx @create-ui/cli view @createui/button
+npx @create-ui/cli diff button
+
+# Migrate (e.g. consolidate radix imports, or switch icon library).
+npx @create-ui/cli migrate --list
+
+# Set up the MCP server for your client.
+npx @create-ui/cli mcp init --client claude
+```
+
+**Primary themes:** indigo (default), blue, lime, green, red, orange, yellow, cyan
+**Neutral themes:** gray (default), slate, zinc, base, stone
+**Templates:** `next`, `start`, `vite` (plus `next-monorepo` for `init`)
+
+## Detailed References
+
+- [cli.md](./cli.md) — every command and flag (init, create, add, diff, view, search, migrate, info, build, mcp, registry).
+- [mcp.md](./mcp.md) — the MCP server, `mcp init` clients, and the available MCP tools.
+- [customization.md](./customization.md) — theming, the `--color-*` / semantic tokens, radius, and dark mode.
+- [contributing.md](./contributing.md) — working inside the monorepo: dev/test scripts, the registry build, authoring components.
+- [rules/styling.md](./rules/styling.md) — semantic tokens, `className` scope, spacing, `size-*`, `outline-*` focus, `cn()`.
+- [rules/forms.md](./rules/forms.md) — `FieldGroup`, `Field` size cascade, `InputGroup`, `ToggleGroup`, `FieldSet`, validation states.
+- [rules/composition.md](./rules/composition.md) — Groups, overlays, Card, Tabs, Avatar, Alert, Empty, Separator, Skeleton, Badge, `Button` loading.
+- [rules/icons.md](./rules/icons.md) — `leadingIcon` / `trailingIcon`, icon sizing, passing icons as components.
+
+## Resources
+
+- Home: https://createui.co
+- Docs: https://createui.co/docs
+- Registry: https://createui.co/r

package/dist/skills/createui/agents/openai.yml

@@ -0,0 +1,5 @@
+interface:
+  display_name: "Create UI"
+  short_description: "Manages Create UI components — adding, searching, updating, styling, and composing UI from the @createui registry."
+  icon_small: "./assets/createui-control-small.png"
+  icon_large: "./assets/createui.png"

package/dist/skills/createui/cli.md

@@ -0,0 +1,309 @@
+# Create UI CLI Reference
+
+Configuration is read from `components.json`.
+
+The CLI is published as **`@create-ui/cli`** and exposes the **`createui`** bin.
+
+- **In a user project (published):** `npx @create-ui/cli <command>` — or install it globally with `pnpm add -g @create-ui/cli` and then run `createui <command>`.
+- **Inside this monorepo (contributors):** `pnpm createui <command>`, which runs the local build against `http://localhost:4000/r` and requires `pnpm v4:dev` to be running. To test against a target app, use `pnpm createui add -c ~/path/to/app`.
+
+Examples below use `npx @create-ui/cli <command>`; substitute `pnpm createui <command>` when working in the monorepo.
+
+> **IMPORTANT:** Only use the flags documented below. Do not invent or guess flags — if a flag isn't listed here, it doesn't exist.
+
+## Contents
+
+- Commands: init, create, add, diff, view, search, migrate, info, build, mcp, registry
+- The three "build" things: `create` vs `build` vs `pnpm registry:build`
+- Templates: next, vite, start, next-monorepo
+- Registry & namespaces: builtin `@createui`, `REGISTRY_URL`, custom registries
+
+---
+
+## Commands
+
+Program name `createui`. Description: "add items from registries to your project". Print the version with `-v, --version`.
+
+### `init` — Initialize your project and install dependencies
+
+```bash
+npx @create-ui/cli init [components...] [options]
+```
+
+Initializes Create UI in an existing project: writes `components.json`, installs dependencies, and applies the base style and theme. Optionally installs the listed components (names, URLs, or local paths) in the same step.
+
+| Flag                     | Short | Description                                                       | Default |
+| ------------------------ | ----- | --------------------------------------------------------------- | ------- |
+| `--template <template>`  | `-t`  | Template: `next`, `start`, `vite`, `next-monorepo`              | —       |
+| `--theme <theme>`        |       | Primary color theme: `indigo`, `blue`, `lime`, `green`, `red`, `orange`, `yellow`, `cyan` | —       |
+| `--neutral <neutral>`    |       | Neutral color theme: `gray`, `slate`, `zinc`, `base`, `stone`   | —       |
+| `--font-variant <v>`     |       | Font variant: `v1`                                              | —       |
+| `--base-color <color>`   | `-b`  | DEPRECATED — use `--theme` instead                             | —       |
+| `--yes`                  | `-y`  | Skip confirmation prompt                                        | `true`  |
+| `--defaults`             | `-d`  | Use default configuration                                       | `false` |
+| `--force`                | `-f`  | Force overwrite of existing config                             | `false` |
+| `--cwd <cwd>`            | `-c`  | Working directory                                              | current |
+| `--silent`               | `-s`  | Mute output                                                    | `false` |
+| `--src-dir`              |       | Use the `src` directory                                       | —       |
+| `--no-src-dir`           |       | Do not use the `src` directory                               | —       |
+| `--css-variables`        |       | Use CSS variables for theming                                | `true`  |
+| `--no-css-variables`     |       | Do not use CSS variables for theming                        | —       |
+| `--no-base-style`        |       | Do not install the base Create UI style                      | —       |
+
+Pick a theme with `--theme` and `--neutral`; these are swappable token sets layered on the one Create UI system (there is no style/base split to choose).
+
+### `create` — Create a new project with Create UI
+
+```bash
+npx @create-ui/cli create [name] [options]
+```
+
+Scaffolds a brand-new project. With no arguments it prints "Build your own createui." and opens **https://createui.co/create** in the browser so you can build a custom design system, then choose a framework.
+
+| Flag                    | Short | Description                                   | Default |
+| ----------------------- | ----- | --------------------------------------------- | ------- |
+| `--template <template>` | `-t`  | Template: `next`, `start`, `vite`             | —       |
+| `--preset [name]`       | `-p`  | Use a preset configuration (interactive list if no name) | —       |
+| `--cwd <cwd>`           | `-c`  | Working directory                             | current |
+| `--src-dir`             |       | Use the `src` directory                       | —       |
+| `--no-src-dir`          |       | Do not use the `src` directory                | —       |
+| `--yes`                 | `-y`  | Skip confirmation prompt                      | `true`  |
+
+`create` scaffolds a **project**; it is not an alias for `init`. To set up Create UI inside an existing project, use `init`.
+
+### `add` — Add a component to your project
+
+```bash
+npx @create-ui/cli add [components...] [options]
+```
+
+Accepts bare names (`button`), namespaced names (`@createui/button`), full URLs, and 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`  | The path to add the component to       | —       |
+| `--silent`            | `-s`  | Mute output                            | `false` |
+| `--src-dir`           |       | Use the `src` directory                | —       |
+| `--no-src-dir`        |       | Do not use the `src` directory         | —       |
+| `--css-variables`     |       | Use CSS variables for theming          | `true`  |
+| `--no-css-variables`  |       | Do not use CSS variables for theming   | —       |
+
+```bash
+# Add by name.
+npx @create-ui/cli add button
+
+# Add a namespaced item.
+npx @create-ui/cli add @createui/select
+
+# Add from a URL or a local path.
+npx @create-ui/cli add https://createui.co/r/button.json
+```
+
+To check whether installed components are out of date, use the `diff` command (below).
+
+### `diff` — Check for updates against the registry
+
+```bash
+npx @create-ui/cli diff [component] [options]
+```
+
+With no argument, lists the components that have updates available. With a component name, shows what changed upstream.
+
+| Flag          | Short | Description              | Default |
+| ------------- | ----- | ------------------------ | ------- |
+| `--yes`       | `-y`  | Skip confirmation prompt | `false` |
+| `--cwd <cwd>` | `-c`  | Working directory        | current |
+
+### `view` — View items from the registry
+
+```bash
+npx @create-ui/cli view <items...> [options]
+```
+
+Prints item metadata plus file contents (as JSON). Items are names or URLs, e.g. `@createui/button`.
+
+| Flag          | Short | Description       | Default |
+| ------------- | ----- | ----------------- | ------- |
+| `--cwd <cwd>` | `-c`  | Working directory | current |
+
+### `search` (alias: `list`) — Search items from registries
+
+```bash
+npx @create-ui/cli search <registries...> [options]
+npx @create-ui/cli list <registries...> [options]
+```
+
+Searches one or more registries. Registry names must start with `@` (e.g. `@createui`). Without `-q`, lists 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 |
+
+```bash
+# List everything in the built-in registry.
+npx @create-ui/cli search @createui
+
+# Fuzzy search.
+npx @create-ui/cli search @createui -q dialog
+```
+
+### `migrate` — Run a migration
+
+```bash
+npx @create-ui/cli migrate [migration] [options]
+```
+
+Available migrations:
+
+- `icons` — migrate to a different icon library.
+- `radix` — migrate to `radix-ui`, consolidating `@radix-ui/react-*` imports into the unified `radix-ui` package.
+
+| Flag          | Short | Description              | Default |
+| ------------- | ----- | ------------------------ | ------- |
+| `--list`      | `-l`  | List available migrations | —       |
+| `--yes`       | `-y`  | Skip confirmation prompt | —       |
+| `--cwd <cwd>` | `-c`  | Working directory        | current |
+
+### `info` — Get information about your project
+
+```bash
+npx @create-ui/cli info [options]
+```
+
+Prints project information plus the contents of `components.json`. Run this first to discover the project's framework, aliases, resolved paths, and the global CSS file (the `tailwind.css` path is where custom tokens go).
+
+| Flag          | Short | Description       | Default |
+| ------------- | ----- | ----------------- | ------- |
+| `--cwd <cwd>` | `-c`  | Working directory | current |
+
+### `build` — Build components for a Create UI registry [EXPERIMENTAL]
+
+```bash
+npx @create-ui/cli build [registry] [options]
+```
+
+For users **publishing their own registry**: compiles a `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      |
+
+This is distinct from the monorepo's `pnpm registry:build` — see the note below.
+
+### `mcp` — MCP server and configuration commands
+
+```bash
+# Start the stdio MCP server.
+npx @create-ui/cli mcp
+
+# Initialize MCP configuration for a client.
+npx @create-ui/cli mcp init --client <client>
+```
+
+Running `createui mcp` starts the stdio MCP server. The `mcp init` subcommand writes the MCP config for a client.
+
+| Subcommand / Flag       | Description                                                        | Default |
+| ----------------------- | ----------------------------------------------------------------- | ------- |
+| `mcp` `--cwd <cwd>`     | Working directory                                                 | current |
+| `mcp init --client <c>` | Client to configure: `claude`, `cursor`, `vscode`, `codex`, `opencode` | —       |
+
+See [mcp.md](./mcp.md) for the MCP server details, the available tools, and per-client config paths.
+
+### `registry` — Manage registries
+
+```bash
+npx @create-ui/cli registry add [registries...] [options]
+```
+
+The `registry add` subcommand adds registries to `components.json`. Pass a name (`@acme`) or a `name=url` pair where the URL contains `{name}`.
+
+| Flag          | Short | Description       | Default |
+| ------------- | ----- | ----------------- | ------- |
+| `--cwd <cwd>` | `-c`  | Working directory | current |
+| `--silent`    | `-s`  | Mute output       | `false` |
+
+```bash
+npx @create-ui/cli registry add @acme=https://acme.com/r/{name}.json
+```
+
+> The legacy `registry:build` and `registry:mcp` commands still exist, but prefer `registry build` and `mcp`.
+
+---
+
+## The three "build" things
+
+These are easy to confuse — they do different jobs:
+
+| Command                                 | What it does                                                                                  |
+| --------------------------------------- | --------------------------------------------------------------------------------------------- |
+| `createui create`                       | Scaffolds a new **project**. With no args, opens https://createui.co/create to build a custom design system. |
+| `createui build`                        | Compiles a **user's own** `registry.json` → `./public/r` so they can publish components.       |
+| `pnpm registry:build` (monorepo only)   | Rebuilds **this repo's** component registry. Different tool, contributors only — see [contributing.md](./contributing.md). |
+
+---
+
+## Templates
+
+The `init` `--template` option accepts:
+
+| Value           | Framework             |
+| --------------- | --------------------- |
+| `next`          | Next.js               |
+| `vite`          | Vite                  |
+| `start`         | TanStack Start        |
+| `next-monorepo` | Next.js (monorepo)    |
+
+---
+
+## Registry & namespaces
+
+The built-in registry namespace is **`@createui`**, which resolves item names to:
+
+```
+https://createui.co/r/{name}.json
+```
+
+So `@createui/button` resolves to `https://createui.co/r/button.json`.
+
+### Overriding the base registry URL
+
+The only registry environment variable is **`REGISTRY_URL`**. It defaults to `https://createui.co/r`; the `@createui` namespace appends `/{name}.json`. Override it to point the CLI at a different registry host:
+
+```bash
+REGISTRY_URL=https://staging.example.com/r npx @create-ui/cli add button
+```
+
+### Custom registries in `components.json`
+
+Configure additional registries under the `"registries"` key. Names must start with `@`, and every URL must contain `{name}`.
+
+```json
+{
+  "registries": {
+    "@acme": "https://acme.com/r/{name}.json",
+    "@private": {
+      "url": "https://registry.internal.example.com/r/{name}.json",
+      "headers": { "Authorization": "Bearer ${MY_TOKEN}" },
+      "params": { "team": "${TEAM_ID}" }
+    }
+  }
+}
+```
+
+- **String form** (`@acme`) is a bare templated URL.
+- **Object form** (`@private`) adds `headers` and/or `params`.
+- `${VAR}` placeholders in the URL, headers, and params are resolved from environment variables.
+
+Once configured, add items by namespace:
+
+```bash
+npx @create-ui/cli add @acme/marketing-hero
+```