diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
new file mode 100644
index 00000000..9f68e7d5
--- /dev/null
+++ b/CONTRIBUTING.md
@@ -0,0 +1,74 @@
+# Contributing to solid-ui
+
+Thank you for helping improve Solid UI, the docs site, and `solidui-cli`.
+
+## Repository layout
+
+| Path | Purpose |
+| ---- | ------- |
+| `apps/docs` | solid-ui.com — registry source, MDX docs, examples |
+| `packages/cli` | `solidui-cli` published to npm |
+
+## Local setup
+
+```bash
+pnpm install
+```
+
+If `pnpm install` fails on older Corepack pnpm, use Node 22+ and `corepack prepare pnpm@9 --activate`, or install dependencies per-package.
+
+### Docs app
+
+```bash
+pnpm --filter docs dev
+```
+
+### CLI
+
+```bash
+cd packages/cli
+pnpm install
+pnpm build
+node dist/index.js --help
+```
+
+## Registry changes
+
+1. Edit files under `apps/docs/src/registry/` (`ui/`, `example/`, `block/`).
+2. Register entries in `registry-ui.ts`, `registry-examples.ts`, or `registry-blocks.ts`.
+3. Rebuild published JSON:
+
+```bash
+pnpm --filter docs build:registry
+```
+
+4. Commit both source **and** `apps/docs/public/registry/**` if your PR includes registry output (maintainers may run this on release).
+
+### Promoting examples to CLI-installable components
+
+- `solidui-cli add` only lists `type: "ui"` in `registry/index.json`.
+- If the docs site uses a pattern in production (e.g. `mode-toggle`), add `registry/ui/<name>.tsx` and an entry in `registry-ui.ts` with `registryDependencies` as needed.
+
+### Blocks
+
+- Define in `registry-blocks.ts` with SolidStart-friendly `target` paths (`src/routes/...`, `src/components/...`).
+- Install via `solidui-cli add-block <name>` (after registry build).
+
+## Pull requests
+
+- Target `main` unless maintainers direct you to `dev` (Tailwind v4 migration).
+- One feature per PR when possible (CLI change vs component fix vs docs).
+- Link related issues (e.g. #229 sidebar / Tailwind).
+
+## Claiming work (V4 checklist)
+
+See [issue #199](https://github.com/stefan-karger/solid-ui/issues/199). Comment on the issue or open a draft PR with the component name you are implementing to avoid duplicate effort.
+
+## Fork testing the CLI against your registry
+
+```bash
+cd packages/cli && pnpm build
+SOLIDUI_REGISTRY_URL=https://your-preview.example.com node dist/index.js add mode-toggle
+```
+
+Deploy `apps/docs/public/registry` to that host or run docs locally and point the env var at `http://localhost:3000`.
diff --git a/CONTRIBUTION-PLAN.md b/CONTRIBUTION-PLAN.md
new file mode 100644
index 00000000..f8d5b022
--- /dev/null
+++ b/CONTRIBUTION-PLAN.md
@@ -0,0 +1,39 @@
+# solid-ui contribution execution plan
+
+Branch: `feat/cli-dx-and-registry` (fork: AMDphreak/solid-ui)
+
+## Quick wins
+
+- [x] `SOLIDUI_REGISTRY_URL` env var in CLI `registry.ts`
+- [x] Docs/cli copy fixes (`componentDir`, `components.json` → `ui.config.json`)
+- [x] `init --with-color-mode` (+ `COLOR_MODE.md` snippets for SolidStart / Vite)
+- [x] `init -y`, `init --with-tailwind` (+ postcss.config.cjs)
+- [x] `docs/dark-mode/tauri.mdx` + link from overview
+- [x] `mode-toggle` UI component (merged from prior PR branch)
+
+## Medium
+
+- [x] `solidui-cli add-block <name>` + SolidStart-friendly block targets
+- [x] `solidui-cli update [components...]` with overwrite
+- [x] Sidebar: v3-compatible `w-[var(--*)]` classes + docs callout
+
+## Strategic
+
+- [x] `CONTRIBUTING.md`
+- [x] `apps/docs/public/llms.txt`
+- [x] Tailwind v3/v4 callout in CLI `COLOR_MODE.md`, sidebar docs, CONTRIBUTING
+
+## Skipped (per user)
+
+- UnoCSS support
+- cva → tailwind-variants migration
+- Full shadcn block parity in one PR
+- Separate `command-palette` ui (`command` already exports `CommandDialog`)
+
+## Resume in a new chat
+
+```text
+Continue solid-ui fork AMDphreak/solid-ui branch feat/cli-dx-and-registry.
+Read CONTRIBUTION-PLAN.md. Run pnpm --filter docs build:registry, commit public/registry,
+pnpm --filter solidui-cli build, push branch, open/update PR to stefan-karger/solid-ui.
+```
diff --git a/apps/docs/public/llms.txt b/apps/docs/public/llms.txt
new file mode 100644
index 00000000..412fdd59
--- /dev/null
+++ b/apps/docs/public/llms.txt
@@ -0,0 +1,33 @@
+# solid-ui
+
+> Unofficial SolidJS port of shadcn/ui — copy-paste components (Kobalte, corvu, Tailwind).
+
+## Docs
+
+- Site: https://www.solid-ui.com
+- Introduction: https://www.solid-ui.com/docs/introduction
+- CLI: https://www.solid-ui.com/docs/cli
+- Installation (SolidStart): https://www.solid-ui.com/docs/installation/solid-start
+- Dark mode (SolidStart): https://www.solid-ui.com/docs/dark-mode/solid-start
+- Registry index: https://www.solid-ui.com/registry/index.json
+
+## CLI
+
+```bash
+npx solidui-cli@latest init
+npx solidui-cli@latest init -y --with-color-mode --with-tailwind
+npx solidui-cli@latest add button mode-toggle
+npx solidui-cli@latest add-block sidebar-01
+npx solidui-cli@latest update button
+```
+
+Environment: `SOLIDUI_REGISTRY_URL` overrides the registry host.
+
+## Stack
+
+- SolidJS, Kobalte, corvu, Tailwind CSS
+- CLI scaffolds Tailwind v3 (`tailwind.config.cjs`); docs app may use Tailwind v4
+
+## Repository
+
+https://github.com/stefan-karger/solid-ui
diff --git a/apps/docs/src/components/mode-toggle.tsx b/apps/docs/src/components/mode-toggle.tsx
index 6b4cbe33..072f3fb1 100644
--- a/apps/docs/src/components/mode-toggle.tsx
+++ b/apps/docs/src/components/mode-toggle.tsx
@@ -1,38 +1 @@
-import { useColorMode } from "@kobalte/core"
-
-import { IconLaptop, IconMoon, IconSun } from "~/components/icons"
-import { Button } from "~/registry/ui/button"
-import {
-  DropdownMenu,
-  DropdownMenuContent,
-  DropdownMenuItem,
-  DropdownMenuTrigger
-} from "~/registry/ui/dropdown-menu"
-
-export function ModeToggle() {
-  const { setColorMode } = useColorMode()
-
-  return (
-    <DropdownMenu>
-      <DropdownMenuTrigger as={Button<"button">} variant="ghost" size="sm" class="w-9 px-0">
-        <IconSun class="size-6 rotate-0 scale-100 transition-all dark:-rotate-90 dark:scale-0" />
-        <IconMoon class="absolute size-6 rotate-90 scale-0 transition-all dark:rotate-0 dark:scale-100" />
-        <span class="sr-only">Toggle theme</span>
-      </DropdownMenuTrigger>
-      <DropdownMenuContent>
-        <DropdownMenuItem onSelect={() => setColorMode("light")}>
-          <IconSun class="mr-2 size-4" />
-          <span>Light</span>
-        </DropdownMenuItem>
-        <DropdownMenuItem onSelect={() => setColorMode("dark")}>
-          <IconMoon class="mr-2 size-4" />
-          <span>Dark</span>
-        </DropdownMenuItem>
-        <DropdownMenuItem onSelect={() => setColorMode("system")}>
-          <IconLaptop class="mr-2 size-4" />
-          <span>System</span>
-        </DropdownMenuItem>
-      </DropdownMenuContent>
-    </DropdownMenu>
-  )
-}
+export { ModeToggle } from "~/registry/ui/mode-toggle"
diff --git a/apps/docs/src/registry/example/mode-toggle.tsx b/apps/docs/src/registry/example/mode-toggle.tsx
index 6bb6ebe4..7911f924 100644
--- a/apps/docs/src/registry/example/mode-toggle.tsx
+++ b/apps/docs/src/registry/example/mode-toggle.tsx
@@ -1,38 +1 @@
-import { useColorMode } from "@kobalte/core"
-
-import { IconLaptop, IconMoon, IconSun } from "~/components/icons"
-import { Button } from "~/registry/ui/button"
-import {
-  DropdownMenu,
-  DropdownMenuContent,
-  DropdownMenuItem,
-  DropdownMenuTrigger
-} from "~/registry/ui/dropdown-menu"
-
-export default function ModeToggle() {
-  const { setColorMode } = useColorMode()
-
-  return (
-    <DropdownMenu>
-      <DropdownMenuTrigger as={Button<"button">} variant="ghost" size="sm" class="w-9 px-0">
-        <IconSun class="size-6 rotate-0 scale-100 transition-all dark:-rotate-90 dark:scale-0" />
-        <IconMoon class="absolute size-6 rotate-90 scale-0 transition-all dark:rotate-0 dark:scale-100" />
-        <span class="sr-only">Toggle theme</span>
-      </DropdownMenuTrigger>
-      <DropdownMenuContent>
-        <DropdownMenuItem onSelect={() => setColorMode("light")}>
-          <IconSun class="mr-2 size-4" />
-          <span>Light</span>
-        </DropdownMenuItem>
-        <DropdownMenuItem onSelect={() => setColorMode("dark")}>
-          <IconMoon class="mr-2 size-4" />
-          <span>Dark</span>
-        </DropdownMenuItem>
-        <DropdownMenuItem onSelect={() => setColorMode("system")}>
-          <IconLaptop class="mr-2 size-4" />
-          <span>System</span>
-        </DropdownMenuItem>
-      </DropdownMenuContent>
-    </DropdownMenu>
-  )
-}
+export { ModeToggle as default } from "~/registry/ui/mode-toggle"
diff --git a/apps/docs/src/registry/registry-blocks.ts b/apps/docs/src/registry/registry-blocks.ts
index c9281e2c..b6235404 100644
--- a/apps/docs/src/registry/registry-blocks.ts
+++ b/apps/docs/src/registry/registry-blocks.ts
@@ -10,19 +10,22 @@ export const blocks: Registry = [
       {
         path: "block/sidebar-01/index.tsx",
         type: "page",
-        target: "app/dashboard/page.tsx"
+        target: "src/routes/dashboard/index.tsx"
       },
       {
         path: "block/sidebar-01/components/app-sidebar.tsx",
-        type: "component"
+        type: "component",
+        target: "src/components/dashboard/app-sidebar.tsx"
       },
       {
         path: "block/sidebar-01/components/search-form.tsx",
-        type: "component"
+        type: "component",
+        target: "src/components/dashboard/search-form.tsx"
       },
       {
         path: "block/sidebar-01/components/version-switcher.tsx",
-        type: "component"
+        type: "component",
+        target: "src/components/dashboard/version-switcher.tsx"
       }
     ]
   },
@@ -32,7 +35,8 @@ export const blocks: Registry = [
     files: [
       {
         path: "block/demo-sidebar.tsx",
-        type: "component"
+        type: "component",
+        target: "src/components/demo-sidebar.tsx"
       }
     ]
   }
diff --git a/apps/docs/src/registry/registry-ui.ts b/apps/docs/src/registry/registry-ui.ts
index 0bcc7563..2f99e812 100644
--- a/apps/docs/src/registry/registry-ui.ts
+++ b/apps/docs/src/registry/registry-ui.ts
@@ -313,6 +313,18 @@ export const ui: Registry = [
       }
     ]
   },
+  {
+    name: "mode-toggle",
+    type: "ui",
+    dependencies: ["@kobalte/core", "lucide-solid"],
+    registryDependencies: ["button", "dropdown-menu"],
+    files: [
+      {
+        path: "ui/mode-toggle.tsx",
+        type: "ui"
+      }
+    ]
+  },
   {
     name: "navigation-menu",
     type: "ui",
diff --git a/apps/docs/src/registry/ui/mode-toggle.tsx b/apps/docs/src/registry/ui/mode-toggle.tsx
new file mode 100644
index 00000000..d5538ce7
--- /dev/null
+++ b/apps/docs/src/registry/ui/mode-toggle.tsx
@@ -0,0 +1,38 @@
+import { useColorMode } from "@kobalte/core"
+import { Laptop, Moon, Sun } from "lucide-solid"
+
+import { Button } from "~/registry/ui/button"
+import {
+  DropdownMenu,
+  DropdownMenuContent,
+  DropdownMenuItem,
+  DropdownMenuTrigger
+} from "~/registry/ui/dropdown-menu"
+
+export function ModeToggle() {
+  const { setColorMode } = useColorMode()
+
+  return (
+    <DropdownMenu>
+      <DropdownMenuTrigger as={Button<"button">} variant="ghost" size="sm" class="w-9 px-0">
+        <Sun class="size-6 rotate-0 scale-100 transition-all dark:-rotate-90 dark:scale-0" />
+        <Moon class="absolute size-6 rotate-90 scale-0 transition-all dark:rotate-0 dark:scale-100" />
+        <span class="sr-only">Toggle theme</span>
+      </DropdownMenuTrigger>
+      <DropdownMenuContent>
+        <DropdownMenuItem onSelect={() => setColorMode("light")}>
+          <Sun class="mr-2 size-4" />
+          <span>Light</span>
+        </DropdownMenuItem>
+        <DropdownMenuItem onSelect={() => setColorMode("dark")}>
+          <Moon class="mr-2 size-4" />
+          <span>Dark</span>
+        </DropdownMenuItem>
+        <DropdownMenuItem onSelect={() => setColorMode("system")}>
+          <Laptop class="mr-2 size-4" />
+          <span>System</span>
+        </DropdownMenuItem>
+      </DropdownMenuContent>
+    </DropdownMenu>
+  )
+}
diff --git a/apps/docs/src/registry/ui/sidebar.tsx b/apps/docs/src/registry/ui/sidebar.tsx
index c2e05d4e..ce309c2d 100644
--- a/apps/docs/src/registry/ui/sidebar.tsx
+++ b/apps/docs/src/registry/ui/sidebar.tsx
@@ -183,7 +183,7 @@ const Sidebar: Component<SidebarProps> = (rawProps) => {
       <Match when={local.collapsible === "none"}>
         <div
           class={cn(
-            "test w-(--sidebar-width) flex h-full flex-col bg-sidebar text-sidebar-foreground",
+            "flex h-full w-[var(--sidebar-width)] flex-col bg-sidebar text-sidebar-foreground",
             local.class
           )}
           {...others}
@@ -196,7 +196,7 @@ const Sidebar: Component<SidebarProps> = (rawProps) => {
           <SheetContent
             data-sidebar="sidebar"
             data-mobile="true"
-            class="w-(--sidebar-width) bg-sidebar p-0 text-sidebar-foreground [&>button]:hidden"
+            class="w-[var(--sidebar-width)] bg-sidebar p-0 text-sidebar-foreground [&>button]:hidden"
             style={{
               "--sidebar-width": SIDEBAR_WIDTH_MOBILE
             }}
@@ -217,24 +217,24 @@ const Sidebar: Component<SidebarProps> = (rawProps) => {
           {/* This is what handles the sidebar gap on desktop */}
           <div
             class={cn(
-              "w-(--sidebar-width) relative h-svh bg-transparent transition-[width] duration-200 ease-linear",
+              "w-[var(--sidebar-width)] relative h-svh bg-transparent transition-[width] duration-200 ease-linear",
               "group-data-[collapsible=offcanvas]:w-0",
               "group-data-[side=right]:rotate-180",
               local.variant === "floating" || local.variant === "inset"
-                ? "group-data-[collapsible=icon]:w-[calc(var(--sidebar-width-icon)_+_theme(spacing.4))]"
-                : "group-data-[collapsible=icon]:w-(--sidebar-width-icon)"
+                ? "group-data-[collapsible=icon]:w-[calc(var(--sidebar-width-icon)+1rem)]"
+                : "group-data-[collapsible=icon]:w-[var(--sidebar-width-icon)]"
             )}
           />
           <div
             class={cn(
-              "w-(--sidebar-width) fixed inset-y-0 z-10 hidden h-svh transition-[left,right,width] duration-200 ease-linear md:flex",
+              "w-[var(--sidebar-width)] fixed inset-y-0 z-10 hidden h-svh transition-[left,right,width] duration-200 ease-linear md:flex",
               local.side === "left"
                 ? "left-0 group-data-[collapsible=offcanvas]:left-[calc(var(--sidebar-width)*-1)]"
                 : "right-0 group-data-[collapsible=offcanvas]:right-[calc(var(--sidebar-width)*-1)]",
               // Adjust the padding for floating and inset variants.
               local.variant === "floating" || local.variant === "inset"
-                ? "p-2 group-data-[collapsible=icon]:w-[calc(var(--sidebar-width-icon)_+_theme(spacing.4)_+2px)]"
-                : "group-data-[collapsible=icon]:w-(--sidebar-width-icon) group-data-[side=left]:border-r group-data-[side=right]:border-l",
+                ? "p-2 group-data-[collapsible=icon]:w-[calc(var(--sidebar-width-icon)+1rem+2px)]"
+                : "group-data-[collapsible=icon]:w-[var(--sidebar-width-icon)] group-data-[side=left]:border-r group-data-[side=right]:border-l",
               local.class
             )}
             {...others}
@@ -602,7 +602,7 @@ const SidebarMenuSkeleton: Component<SidebarMenuSkeletonProps> = (rawProps) => {
     >
       {local.showIcon && <Skeleton class="size-4 rounded-md" data-sidebar="menu-skeleton-icon" />}
       <Skeleton
-        class="max-w-(--skeleton-width) h-4 flex-1"
+        class="max-w-[var(--skeleton-width)] h-4 flex-1"
         data-sidebar="menu-skeleton-text"
         style={{
           "--skeleton-width": width()
diff --git a/apps/docs/src/routes/(app)/docs/cli.mdx b/apps/docs/src/routes/(app)/docs/cli.mdx
index 01efc60b..f56f291b 100644
--- a/apps/docs/src/routes/(app)/docs/cli.mdx
+++ b/apps/docs/src/routes/(app)/docs/cli.mdx
@@ -1,38 +1,48 @@
 <MDXHeader title="CLI" description="Use the CLI to add components to your project." />
 
-## init
+## Environment
 
-Use the `init` command to initialize configuration and dependencies for a new project.
+| Variable | Description |
+| -------- | ----------- |
+| `SOLIDUI_REGISTRY_URL` | Override registry host (default `https://www.solid-ui.com`). Use when testing a fork or a pinned docs deploy. |
 
-The `init` command installs dependencies, adds the `cn` util, configures `tailwind.config.cjs`, and CSS variables for the project.
+## init
 
 ```bash
 npx solidui-cli@latest init
 ```
 
-It also creates a `ui.config.json` file which houses all Solid UI configurations. Feel free to change where you would like your components to be stored by modifying the `componentDir` property.
+Flags:
+
+- `-y, --yes` — use default paths and TypeScript without prompts
+- `--with-color-mode` — install `@kobalte/core` and write `COLOR_MODE.md` setup snippets
+- `--with-tailwind` — install `tailwindcss`, `postcss`, `autoprefixer` (dev) and create `postcss.config.cjs` if missing
+
+Creates `ui.config.json` with `aliases.components` (default `~/components/ui`) and `aliases.utils` (default `~/lib/utils`).
 
 ## add
 
-Use the `add` command to add components and dependencies to your project.
+```bash
+npx solidui-cli@latest add button mode-toggle
+```
+
+- `-o, --overwrite` — replace existing component files
+- `-y, --yes` — treat as overwrite when files exist (skip confirm)
+- `-a, --all` — install every UI component (large)
+
+## add-block
 
 ```bash
-npx solidui-cli@latest add [component]
+npx solidui-cli@latest add-block sidebar-01
 ```
 
-You will be presented with a list of components to choose from:
-
-```txt
-Which components would you like to add? › Space to select. A to toggle all.
-Enter to submit.
-
-◯  accordion
-◯  avatar
-◯  badge
-◯  button
-◯  callout
-◯  card
-◯  charts
-◯  checkbox
-◯  dialog
+Installs multi-file layouts using `target` paths from the registry (e.g. SolidStart `src/routes/...`). UI `registryDependencies` are installed automatically.
+
+## update
+
+```bash
+npx solidui-cli@latest update button
+npx solidui-cli@latest update --all
 ```
+
+Re-fetches components from the registry and overwrites files (same as `add` with overwrite).
diff --git a/apps/docs/src/routes/(app)/docs/components/sidebar.mdx b/apps/docs/src/routes/(app)/docs/components/sidebar.mdx
index 27e3085f..5d8e9c90 100644
--- a/apps/docs/src/routes/(app)/docs/components/sidebar.mdx
+++ b/apps/docs/src/routes/(app)/docs/components/sidebar.mdx
@@ -29,6 +29,16 @@ Customizable.
 npx solidui-cli@latest add sidebar
 ```
 
+For the full example layout (SolidStart paths):
+
+```bash
+npx solidui-cli@latest add-block sidebar-01
+```
+
+<Callout type="note">
+  `solidui-cli init` scaffolds **Tailwind CSS v3**. The sidebar component uses `w-[var(--sidebar-width)]` and other v3-compatible arbitrary values. The solid-ui.com docs app runs Tailwind v4 separately.
+</Callout>
+
 <Step>Add the following colors to your CSS file</Step>
 
 ```css title="app.css"
diff --git a/apps/docs/src/routes/(app)/docs/dark-mode/overview.mdx b/apps/docs/src/routes/(app)/docs/dark-mode/overview.mdx
index 6d248d74..5b184d91 100644
--- a/apps/docs/src/routes/(app)/docs/dark-mode/overview.mdx
+++ b/apps/docs/src/routes/(app)/docs/dark-mode/overview.mdx
@@ -27,6 +27,19 @@
     </svg>
     <p className="font-medium mt-2">Vite</p>
   </LinkedCard>
+  <LinkedCard href="/docs/dark-mode/tauri">
+    <svg
+      role="img"
+      viewBox="0 0 24 24"
+      xmlns="http://www.w3.org/2000/svg"
+      className="w-10 h-10"
+      fill="currentColor"
+    >
+      <title>Tauri</title>
+      <path d="M12 2l2.4 7.4h7.6l-6 4.6 2.3 7-6.3-4.6-6.3 4.6 2.3-7-6-4.6h7.6z" />
+    </svg>
+    <p className="font-medium mt-2">Tauri</p>
+  </LinkedCard>
   <LinkedCard href="/docs/dark-mode/astro">
     <svg
       role="img"
diff --git a/apps/docs/src/routes/(app)/docs/dark-mode/solid-start.mdx b/apps/docs/src/routes/(app)/docs/dark-mode/solid-start.mdx
index f3cfc177..0c16f6e4 100644
--- a/apps/docs/src/routes/(app)/docs/dark-mode/solid-start.mdx
+++ b/apps/docs/src/routes/(app)/docs/dark-mode/solid-start.mdx
@@ -46,17 +46,19 @@ export default function App() {
 }
 ```
 
-### Add needed components
+### Add a mode toggle
 
-Make sure you have the `button` and `dropdown-menu` components installed.
+Install the mode toggle (pulls in `button` and `dropdown-menu` automatically) and place it in your layout.
 
 ```bash
-npx solidui-cli@latest add button dropdown-menu
+npx solidui-cli@latest add mode-toggle
 ```
 
-### Add a mode toggle
+```tsx
+import { ModeToggle } from "~/components/ui/mode-toggle"
+```
 
-Place a mode toggle on your site to toggle between light and dark mode.
+Place a mode toggle on your site to toggle between light, dark, and system mode.
 
 <ComponentPreview name="mode-toggle" />
 
diff --git a/apps/docs/src/routes/(app)/docs/dark-mode/tauri.mdx b/apps/docs/src/routes/(app)/docs/dark-mode/tauri.mdx
new file mode 100644
index 00000000..fc7f01c3
--- /dev/null
+++ b/apps/docs/src/routes/(app)/docs/dark-mode/tauri.mdx
@@ -0,0 +1,44 @@
+<MDXHeader title="Tauri" description="Adding dark mode to your Tauri + Solid app." />
+
+<Steps>
+
+### Install Kobalte
+
+```bash
+npm install @kobalte/core
+```
+
+### Wrap your app
+
+Tauri frontends are SPAs. Use local storage for the color mode (same as Vite).
+
+```tsx
+import { ColorModeProvider, ColorModeScript, createLocalStorageManager } from "@kobalte/core"
+
+const storageManager = createLocalStorageManager("tauri-ui-theme")
+
+export default function App() {
+  return (
+    <>
+      <ColorModeScript storageType={storageManager.type} />
+      <ColorModeProvider storageManager={storageManager}>
+        {/* your router / layout */}
+      </ColorModeProvider>
+    </>
+  )
+}
+```
+
+### Add a mode toggle
+
+```bash
+npx solidui-cli@latest add mode-toggle
+```
+
+```tsx
+import { ModeToggle } from "~/components/ui/mode-toggle"
+```
+
+Place `<ModeToggle />` in your title bar or main navigation.
+
+</Steps>
diff --git a/apps/docs/src/routes/(app)/docs/dark-mode/vite.mdx b/apps/docs/src/routes/(app)/docs/dark-mode/vite.mdx
index d36e99e2..92b76372 100644
--- a/apps/docs/src/routes/(app)/docs/dark-mode/vite.mdx
+++ b/apps/docs/src/routes/(app)/docs/dark-mode/vite.mdx
@@ -37,17 +37,19 @@ export default function App() {
 }
 ```
 
-### Add needed components
+### Add a mode toggle
 
-Make sure you have the `button` and `dropdown-menu` components installed.
+Install the mode toggle (pulls in `button` and `dropdown-menu` automatically) and place it in your layout.
 
 ```bash
-npx solidui-cli@latest add button dropdown-menu
+npx solidui-cli@latest add mode-toggle
 ```
 
-### Add a mode toggle
+```tsx
+import { ModeToggle } from "~/components/ui/mode-toggle"
+```
 
-Place a mode toggle on your site to toggle between light and dark mode.
+Place a mode toggle on your site to toggle between light, dark, and system mode.
 
 <ComponentPreview name="mode-toggle" />
 
diff --git a/apps/docs/src/scripts/build-registry.ts b/apps/docs/src/scripts/build-registry.ts
index 1a91de7b..9fdbce24 100644
--- a/apps/docs/src/scripts/build-registry.ts
+++ b/apps/docs/src/scripts/build-registry.ts
@@ -99,3 +99,70 @@ fs.writeFileSync(
   JSON.stringify(uiPayload, null, 2),
   "utf-8"
 )
+
+// #######################################
+//    BUILD registry/block/[name].json
+// #######################################
+
+const blocksDir = path.join(REGISTRY_PATH, "block")
+if (!fs.existsSync(blocksDir)) {
+  fs.mkdirSync(blocksDir, { recursive: true })
+}
+
+for (const item of result.output) {
+  if (item.type !== "block") {
+    continue
+  }
+
+  const files = item.files?.map((file) => {
+    const content = fs
+      .readFileSync(path.join(process.cwd(), "src", "registry", file.path), "utf8")
+      .replaceAll("\r\n", "\n")
+
+    const relativePath =
+      file.path.replace(new RegExp(`^block/${item.name}/`), "") || path.basename(file.path)
+
+    return {
+      name: relativePath,
+      content,
+      target: file.target
+    }
+  })
+
+  const payload = {
+    ...item,
+    files
+  }
+
+  fs.writeFileSync(
+    path.join(blocksDir, `${item.name}.json`),
+    JSON.stringify(payload, null, 2),
+    "utf8"
+  )
+}
+
+// #######################################
+//    BUILD registry/blocks/index.json
+// #######################################
+
+const blockPayload = result.output
+  .filter((item) => item.type === "block")
+  .map((item) => ({
+    name: item.name,
+    description: item.description,
+    type: item.type,
+    dependencies: item.dependencies,
+    registryDependencies: item.registryDependencies,
+    files: item.files.map((file) => file.path)
+  }))
+
+const blocksIndexDir = path.join(REGISTRY_PATH, "blocks")
+if (!fs.existsSync(blocksIndexDir)) {
+  fs.mkdirSync(blocksIndexDir, { recursive: true })
+}
+
+fs.writeFileSync(
+  path.join(blocksIndexDir, "index.json"),
+  JSON.stringify(blockPayload, null, 2),
+  "utf-8"
+)
diff --git a/packages/cli/README.md b/packages/cli/README.md
index 448c3bc1..c802811c 100644
--- a/packages/cli/README.md
+++ b/packages/cli/README.md
@@ -1,43 +1,33 @@
-# solid-ui
+# solidui-cli
 
-A CLI for adding components to your project.
+CLI for adding [Solid UI](https://www.solid-ui.com) components to your project.
 
-## Usage
-
-Use the `init` command to initialize dependencies for a new project.
-
-The `init` command installs dependencies, adds the `cn` util, configures `tailwind.config.cjs`, and sets up CSS variables for the project.
-
-```bash
-npx solidui-cli@latest init
-```
-
-## add
+## Commands
 
-Use the `add` command to add components to your project.
+| Command | Description |
+| ------- | ----------- |
+| `init` | Create `ui.config.json`, Tailwind theme CSS, `cn` util |
+| `add` | Add UI components from the registry |
+| `add-block` | Add multi-file blocks (layouts) with `target` paths |
+| `update` | Re-fetch and overwrite installed UI components |
 
-The `add` command adds a component to your project and installs all required dependencies.
-
-```bash
-npx solidui-cli@latest add [component]
-```
-
-### Example
+## Usage
 
 ```bash
-npx solidui-cli@latest add alert-dialog
+npx solidui-cli@latest init -y --with-color-mode --with-tailwind
+npx solidui-cli@latest add button mode-toggle
+npx solidui-cli@latest add-block sidebar-01
+npx solidui-cli@latest update button
 ```
 
-You can also run the command without any arguments to view a list of all available components:
+## Environment
 
-```bash
-npx solidui-cli@latest add
-```
+- `SOLIDUI_REGISTRY_URL` — registry base URL (default `https://www.solid-ui.com`)
 
 ## Documentation
 
-Visit https://solid-ui.com to view the documentation.
+https://www.solid-ui.com/docs/cli
 
 ## License
 
-Licensed under the [MIT license](https://github.com/stefan-karger/solid-ui/blob/main/LICENSE).
+MIT
diff --git a/packages/cli/package.json b/packages/cli/package.json
index 260bc06a..8cb7cc47 100644
--- a/packages/cli/package.json
+++ b/packages/cli/package.json
@@ -52,7 +52,8 @@
     "execa": "^9.4.0",
     "recast": "^0.23.9",
     "ts-morph": "^20.0.0",
-    "tsconfig-paths": "^4.2.0"
+    "tsconfig-paths": "^4.2.0",
+    "valibot": "^0.36.0"
   },
   "devDependencies": {
     "@types/babel__core": "^7.20.5",
diff --git a/packages/cli/src/commands/add-block.ts b/packages/cli/src/commands/add-block.ts
new file mode 100644
index 00000000..dbd88657
--- /dev/null
+++ b/packages/cli/src/commands/add-block.ts
@@ -0,0 +1,109 @@
+import { existsSync } from "node:fs"
+import path from "node:path"
+
+import * as p from "@clack/prompts"
+import { Command } from "commander"
+import * as v from "valibot"
+
+import { getConfig } from "~/utils/config"
+import { handleError, highlight } from "~/utils/logger"
+import { installRegistryItems } from "~/utils/install-registry-items"
+import { fetchRegistryItems, getRegistryIndex, resolveTree } from "~/utils/registry"
+
+const addBlockOptionsSchema = v.object({
+  blocks: v.optional(v.array(v.string()), []),
+  cwd: v.string(),
+  overwrite: v.boolean()
+})
+
+export const addBlock = new Command()
+  .name("add-block")
+  .description("add registry blocks (multi-file layouts) to your project")
+  .argument("[blocks...]", "the blocks to add")
+  .option("-c, --cwd <cwd>", "the working directory", process.cwd())
+  .option("-o, --overwrite", "overwrite existing files", false)
+  .action(async (blocks, opts) => {
+    try {
+      const options = v.parse(addBlockOptionsSchema, { blocks, ...opts })
+
+      const cwd = path.resolve(options.cwd)
+      if (!existsSync(cwd)) {
+        throw new Error(`The path ${cwd} does not exist. Please try again.`)
+      }
+
+      const config = await getConfig(cwd)
+      if (!config) {
+        p.log.warning(
+          `Configuration is missing. Please run ${highlight(`init`)} to create a ui.config.json file.`
+        )
+        process.exit(1)
+      }
+
+      const registryIndex = await getRegistryIndex("block")
+
+      let selectedBlocks = options.blocks
+      if (!selectedBlocks.length) {
+        const prompts = await p.group(
+          {
+            blocks: () =>
+              p.multiselect<string>({
+                message: `Which ${highlight("blocks")} would you like to add?`,
+                options: registryIndex.map((entry) => ({ label: entry.name, value: entry.name })),
+                maxItems: 5
+              })
+          },
+          {
+            onCancel: () => {
+              p.cancel("Cancelled.")
+              process.exit(0)
+            }
+          }
+        )
+        selectedBlocks = prompts.blocks
+      }
+
+      if (!selectedBlocks.length) {
+        p.log.warn(`No blocks selected. Exiting.`)
+        process.exit(0)
+      }
+
+      const tree = await resolveTree(registryIndex, selectedBlocks)
+      const payload = await fetchRegistryItems(tree, "block")
+
+      if (!payload.length) {
+        p.log.warn(`Selected blocks not found in registry. Exiting.`)
+        process.exit(0)
+      }
+
+      const uiDependencyNames = [
+        ...new Set(payload.flatMap((block) => block.registryDependencies ?? []))
+      ]
+      if (uiDependencyNames.length) {
+        const uiIndex = await getRegistryIndex("ui")
+        const uiTree = await resolveTree(uiIndex, uiDependencyNames)
+        const uiPayload = await fetchRegistryItems(uiTree, "ui")
+        if (uiPayload.length) {
+          p.log.info(`Installing UI dependencies: ${uiDependencyNames.join(", ")}`)
+          await installRegistryItems({
+            cwd,
+            config,
+            payload: uiPayload,
+            selectedNames: uiDependencyNames,
+            overwrite: options.overwrite,
+            kind: "ui"
+          })
+        }
+      }
+
+      await installRegistryItems({
+        cwd,
+        config,
+        payload,
+        selectedNames: selectedBlocks,
+        overwrite: options.overwrite,
+        kind: "block"
+      })
+    } catch (e) {
+      handleError(e)
+    }
+  })
diff --git a/packages/cli/src/commands/add.ts b/packages/cli/src/commands/add.ts
index db02fae7..4da2c17a 100644
--- a/packages/cli/src/commands/add.ts
+++ b/packages/cli/src/commands/add.ts
@@ -1,23 +1,21 @@
 import { existsSync } from "node:fs"
-import { mkdir, writeFile } from "node:fs/promises"
 import path from "node:path"
 
 import * as p from "@clack/prompts"
 import { Command } from "commander"
-import { execa } from "execa"
 import * as v from "valibot"
 
 import { getConfig } from "~/utils/config"
-import { getPackageManager } from "~/utils/get-package-manager"
 import { handleError, highlight } from "~/utils/logger"
-import { fetchTree, getRegistryIndex, resolveTree } from "~/utils/registry"
-import { transform } from "~/utils/transformers"
+import { installRegistryItems } from "~/utils/install-registry-items"
+import { fetchRegistryItems, getRegistryIndex, resolveTree } from "~/utils/registry"
 
 const addOptionsSchema = v.object({
   components: v.optional(v.array(v.string()), []),
   cwd: v.string(),
   overwrite: v.boolean(),
-  all: v.boolean()
+  all: v.boolean(),
+  yes: v.boolean()
 })
 
 export const add = new Command()
@@ -25,8 +23,9 @@ export const add = new Command()
   .description("add components to your project")
   .argument("[components...]", "the components to add")
   .option("-c, --cwd <cwd>", "the working directory", process.cwd())
-  .option("-o --overwrite", "overwrite existing files", false)
+  .option("-o, --overwrite", "overwrite existing files", false)
   .option("-a, --all", "add all available components", false)
+  .option("-y, --yes", "skip confirmation prompts when overwriting", false)
   .action(async (components, opts) => {
     try {
       const options = v.parse(addOptionsSchema, { components, ...opts })
@@ -39,12 +38,12 @@ export const add = new Command()
       const config = await getConfig(cwd)
       if (!config) {
         p.log.warning(
-          `Configuration is missing. Please run ${highlight(`init`)} to create a components.json file.`
+          `Configuration is missing. Please run ${highlight(`init`)} to create a ui.config.json file.`
         )
         process.exit(1)
       }
 
-      const registryIndex = await getRegistryIndex()
+      const registryIndex = await getRegistryIndex("ui")
 
       let selectedComponents = options.all ? registryIndex.map((v) => v.name) : options.components
       if (!selectedComponents.length) {
@@ -73,90 +72,21 @@ export const add = new Command()
       }
 
       const tree = await resolveTree(registryIndex, selectedComponents)
-      const payload = await fetchTree(tree)
+      const payload = await fetchRegistryItems(tree, "ui")
 
       if (!payload.length) {
         p.log.warn(`Selected components not found. Exiting.`)
         process.exit(0)
       }
 
-      const spinner = p.spinner()
-      spinner.start("Installing...")
-
-      const targetDir = config.resolvedPaths.components
-      if (!existsSync(targetDir)) {
-        await mkdir(targetDir, { recursive: true })
-      }
-
-      for (const item of payload) {
-        spinner.message(`Installing ${highlight(item.name)}...`)
-
-        const existingComponent = item.files.filter((file) =>
-          existsSync(path.resolve(targetDir, file.name))
-        )
-        if (existingComponent.length && !options.overwrite) {
-          if (selectedComponents.includes(item.name)) {
-            spinner.stop()
-
-            const prompts = await p.group(
-              {
-                overwrite: () =>
-                  p.confirm({
-                    message: `Component ${item.name} already exists. Would you like to overwrite?`,
-                    initialValue: false
-                  })
-              },
-              {
-                onCancel: () => {
-                  p.cancel("Cancelled.")
-                  process.exit(0)
-                }
-              }
-            )
-            const overwrite = prompts.overwrite
-            if (!overwrite) {
-              p.log.info(
-                `Skipped ${item.name}. To overwrite, run with the ${highlight("--overwrite")} flag.`
-              )
-              continue
-            }
-
-            spinner.start(`Installing ${highlight(item.name)}...`)
-          } else {
-            continue
-          }
-        }
-
-        for (const file of item.files) {
-          let filePath = path.resolve(targetDir, file.name)
-
-          // run transformers
-          const content = await transform({
-            filename: file.name,
-            raw: file.content,
-            config: config
-          })
-
-          if (!config.tsx) {
-            filePath = filePath.replace(/\.tsx$/, ".jsx")
-            filePath = filePath.replace(/\.ts$/, ".js")
-          }
-
-          await writeFile(filePath, content, "utf-8")
-        }
-
-        // install dependencies
-        if (item.dependencies?.length) {
-          const packageManager = await getPackageManager(cwd)
-          await execa(packageManager, [
-            "add",
-            packageManager === "deno" ? "--npm" : "",
-            ...item.dependencies,
-          ], { cwd });
-        }
-      }
-
-      spinner.stop("Done.")
+      await installRegistryItems({
+        cwd,
+        config,
+        payload,
+        selectedNames: selectedComponents,
+        overwrite: options.overwrite || options.yes,
+        kind: "ui"
+      })
     } catch (e) {
       handleError(e)
     }
diff --git a/packages/cli/src/commands/init.ts b/packages/cli/src/commands/init.ts
index e8e36400..c2f7d502 100644
--- a/packages/cli/src/commands/init.ts
+++ b/packages/cli/src/commands/init.ts
@@ -29,17 +29,36 @@ const PROJECT_DEPENDENCIES = [
   "tailwind-merge"
 ]
 
+const COLOR_MODE_DEPENDENCIES = ["@kobalte/core"]
+
+const TAILWIND_DEV_DEPENDENCIES = ["tailwindcss", "postcss", "autoprefixer"]
+
 const initOptionsSchema = v.object({
-  cwd: v.string()
+  cwd: v.string(),
+  yes: v.boolean(),
+  withColorMode: v.boolean(),
+  withTailwind: v.boolean()
 })
 
 export const init = new Command()
   .name("init")
   .description("initialize your project and install dependencies")
   .option("-c, --cwd <cwd>", "the working directory", process.cwd())
+  .option("-y, --yes", "use defaults without prompts", false)
+  .option("--with-color-mode", "install @kobalte/core and write COLOR_MODE.md snippets", false)
+  .option(
+    "--with-tailwind",
+    "also install tailwindcss, postcss, and autoprefixer (devDependencies)",
+    false
+  )
   .action(async (opts) => {
     try {
-      const options = v.parse(initOptionsSchema, opts)
+      const options = v.parse(initOptionsSchema, {
+        cwd: opts.cwd,
+        yes: opts.yes ?? false,
+        withColorMode: opts.withColorMode ?? false,
+        withTailwind: opts.withTailwind ?? false
+      })
 
       const cwd = path.resolve(options.cwd)
       if (!existsSync(cwd)) {
@@ -49,7 +68,7 @@ export const init = new Command()
       const info = getPackageInfo()
       p.intro(headline(` ${info.name} - ${info.version} `))
 
-      const rawConfig = await promptForConfig()
+      const rawConfig = options.yes ? getDefaultConfig() : await promptForConfig()
 
       const spinner = p.spinner()
       spinner.start(`Creating ui.config.json...`)
@@ -63,12 +82,11 @@ export const init = new Command()
 
       spinner.start(`Initializing project...`)
 
-      // make sure all the directories exist
       for (const [key, resolvedPath] of Object.entries(config.resolvedPaths)) {
         let dirname = path.extname(resolvedPath) ? path.dirname(resolvedPath) : resolvedPath
 
         if (key === "utils" && resolvedPath.endsWith("/utils")) {
-          dirname = dirname.replace(/\/utils$/, "") // remove /utils at the end
+          dirname = dirname.replace(/\/utils$/, "")
         }
 
         if (!existsSync(dirname)) {
@@ -92,27 +110,78 @@ export const init = new Command()
         "utf-8"
       )
 
+      if (options.withColorMode) {
+        await writeFile(path.resolve(cwd, "COLOR_MODE.md"), templates.COLOR_MODE_SNIPPETS, "utf-8")
+      }
+
       spinner.stop(`Project initialized.`)
 
       spinner.start(`Installing dependencies...`)
 
       const packageManager = await getPackageManager(cwd)
-      await execa(packageManager, [
-        "add",
-        packageManager === "deno" ? "--npm" : "",
-        ...PROJECT_DEPENDENCIES,
-      ], { cwd });
+      const deps = [...PROJECT_DEPENDENCIES]
+      if (options.withColorMode) {
+        deps.push(...COLOR_MODE_DEPENDENCIES)
+      }
+
+      await execa(
+        packageManager,
+        ["add", packageManager === "deno" ? "--npm" : "", ...deps],
+        { cwd }
+      )
+
+      if (options.withTailwind) {
+        const postcssPath = path.resolve(cwd, "postcss.config.cjs")
+        if (!existsSync(postcssPath)) {
+          await writeFile(postcssPath, templates.POSTCSS_CONFIG, "utf-8")
+        }
+        await execa(
+          packageManager,
+          [
+            "add",
+            "-D",
+            packageManager === "deno" ? "--npm" : "",
+            ...TAILWIND_DEV_DEPENDENCIES
+          ],
+          { cwd }
+        )
+      }
 
       spinner.stop(`Dependencies installed.`)
 
-      p.outro(
-        `${highlight("Success!")} Project initialization completed. You may now add components.`
-      )
+      const outroLines = [
+        `${highlight("Success!")} Project initialization completed. You may now add components.`,
+        `Registry URL: ${highlight(process.env.SOLIDUI_REGISTRY_URL ?? "https://www.solid-ui.com")}`
+      ]
+      if (options.withColorMode) {
+        outroLines.push(`See ${highlight("COLOR_MODE.md")} for ColorModeProvider setup.`)
+      }
+      if (options.withTailwind) {
+        outroLines.push(`Add PostCSS config if missing: postcss.config.cjs with tailwindcss + autoprefixer.`)
+      }
+
+      p.outro(outroLines.join("\n"))
     } catch (e) {
       handleError(e)
     }
   })
 
+function getDefaultConfig(): RawConfig {
+  return v.parse(RawConfigSchema, {
+    $schema: "https://solid-ui.com/schema.json",
+    tsx: true,
+    tailwind: {
+      css: DEFAULT_CSS_FILE,
+      config: DEFAULT_TAILWIND_CONFIG,
+      prefix: DEFAULT_TAILWIND_PREFIX
+    },
+    aliases: {
+      components: DEFAULT_COMPONENTS,
+      utils: DEFAULT_UTILS
+    }
+  })
+}
+
 async function promptForConfig(): Promise<RawConfig> {
   const options = await p.group(
     {
diff --git a/packages/cli/src/commands/update.ts b/packages/cli/src/commands/update.ts
new file mode 100644
index 00000000..d0b07b9b
--- /dev/null
+++ b/packages/cli/src/commands/update.ts
@@ -0,0 +1,94 @@
+import { existsSync } from "node:fs"
+import path from "node:path"
+
+import * as p from "@clack/prompts"
+import { Command } from "commander"
+import * as v from "valibot"
+
+import { getConfig } from "~/utils/config"
+import { handleError, highlight } from "~/utils/logger"
+import { installRegistryItems } from "~/utils/install-registry-items"
+import { fetchRegistryItems, getRegistryIndex, resolveTree } from "~/utils/registry"
+
+const updateOptionsSchema = v.object({
+  components: v.optional(v.array(v.string()), []),
+  cwd: v.string(),
+  overwrite: v.boolean(),
+  all: v.boolean()
+})
+
+export const update = new Command()
+  .name("update")
+  .description("update installed UI components from the registry")
+  .argument("[components...]", "the components to update")
+  .option("-c, --cwd <cwd>", "the working directory", process.cwd())
+  .option("-o, --overwrite", "overwrite existing files without prompting", true)
+  .option("-a, --all", "update all registry components present in your ui folder", false)
+  .action(async (components, opts) => {
+    try {
+      const options = v.parse(updateOptionsSchema, { components, ...opts, overwrite: opts.overwrite ?? true })
+
+      const cwd = path.resolve(options.cwd)
+      if (!existsSync(cwd)) {
+        throw new Error(`The path ${cwd} does not exist. Please try again.`)
+      }
+
+      const config = await getConfig(cwd)
+      if (!config) {
+        p.log.warning(
+          `Configuration is missing. Please run ${highlight(`init`)} to create a ui.config.json file.`
+        )
+        process.exit(1)
+      }
+
+      const registryIndex = await getRegistryIndex("ui")
+
+      let selectedComponents = options.all
+        ? registryIndex.map((entry) => entry.name)
+        : options.components
+
+      if (!selectedComponents.length) {
+        const prompts = await p.group(
+          {
+            components: () =>
+              p.multiselect<string>({
+                message: `Which ${highlight("components")} would you like to update?`,
+                options: registryIndex.map((entry) => ({ label: entry.name, value: entry.name })),
+                maxItems: 10
+              })
+          },
+          {
+            onCancel: () => {
+              p.cancel("Cancelled.")
+              process.exit(0)
+            }
+          }
+        )
+        selectedComponents = prompts.components
+      }
+
+      if (!selectedComponents.length) {
+        p.log.warn(`No components selected. Exiting.`)
+        process.exit(0)
+      }
+
+      const tree = await resolveTree(registryIndex, selectedComponents)
+      const payload = await fetchRegistryItems(tree, "ui")
+
+      if (!payload.length) {
+        p.log.warn(`Selected components not found in registry. Exiting.`)
+        process.exit(0)
+      }
+
+      await installRegistryItems({
+        cwd,
+        config,
+        payload,
+        selectedNames: selectedComponents,
+        overwrite: true,
+        kind: "ui"
+      })
+    } catch (e) {
+      handleError(e)
+    }
+  })
diff --git a/packages/cli/src/index.ts b/packages/cli/src/index.ts
index 948e0755..c134bf8b 100644
--- a/packages/cli/src/index.ts
+++ b/packages/cli/src/index.ts
@@ -2,7 +2,9 @@
 import { Command } from "commander"
 
 import { add } from "~/commands/add"
+import { addBlock } from "~/commands/add-block"
 import { init } from "~/commands/init"
+import { update } from "~/commands/update"
 import { getPackageInfo } from "~/utils/get-package-info"
 
 process.on("SIGINT", () => process.exit(0))
@@ -19,6 +21,8 @@ async function main() {
     .version(packageInfo.version || "0.0.0", "-v, --version", "display the version number")
     .addCommand(init)
     .addCommand(add)
+    .addCommand(addBlock)
+    .addCommand(update)
     .parse()
 }
 
diff --git a/packages/cli/src/utils/install-registry-items.ts b/packages/cli/src/utils/install-registry-items.ts
new file mode 100644
index 00000000..c0f07004
--- /dev/null
+++ b/packages/cli/src/utils/install-registry-items.ts
@@ -0,0 +1,161 @@
+import { existsSync } from "node:fs"
+import { mkdir, writeFile } from "node:fs/promises"
+import path from "node:path"
+
+import * as p from "@clack/prompts"
+import { execa } from "execa"
+
+import type { Config } from "~/utils/config"
+import { getPackageManager } from "~/utils/get-package-manager"
+import { highlight } from "~/utils/logger"
+import type { RegistryItem } from "~/utils/registry"
+import { transform } from "~/utils/transformers"
+
+export type InstallRegistryItemsOptions = {
+  cwd: string
+  config: Config
+  payload: RegistryItem[]
+  selectedNames: string[]
+  overwrite: boolean
+  kind: "ui" | "block"
+}
+
+export async function installRegistryItems(options: InstallRegistryItemsOptions) {
+  const { cwd, config, payload, selectedNames, overwrite, kind } = options
+
+  const spinner = p.spinner()
+  spinner.start("Installing...")
+
+  if (kind === "ui") {
+    const targetDir = config.resolvedPaths.components
+    if (!existsSync(targetDir)) {
+      await mkdir(targetDir, { recursive: true })
+    }
+
+    for (const item of payload) {
+      spinner.message(`Installing ${highlight(item.name)}...`)
+
+      const existingComponent = item.files.filter((file) =>
+        existsSync(path.resolve(targetDir, file.name))
+      )
+
+      if (existingComponent.length && !overwrite) {
+        if (selectedNames.includes(item.name)) {
+          spinner.stop()
+          const prompts = await p.group(
+            {
+              overwrite: () =>
+                p.confirm({
+                  message: `Component ${item.name} already exists. Would you like to overwrite?`,
+                  initialValue: false
+                })
+            },
+            {
+              onCancel: () => {
+                p.cancel("Cancelled.")
+                process.exit(0)
+              }
+            }
+          )
+          if (!prompts.overwrite) {
+            p.log.info(
+              `Skipped ${item.name}. To overwrite, run with the ${highlight("--overwrite")} flag.`
+            )
+            spinner.start(`Installing ${highlight(item.name)}...`)
+            continue
+          }
+          spinner.start(`Installing ${highlight(item.name)}...`)
+        } else {
+          continue
+        }
+      }
+
+      for (const file of item.files) {
+        let filePath = path.resolve(targetDir, file.name)
+        const content = await transform({
+          filename: file.name,
+          raw: file.content,
+          config
+        })
+
+        if (!config.tsx) {
+          filePath = filePath.replace(/\.tsx$/, ".jsx").replace(/\.ts$/, ".js")
+        }
+
+        await mkdir(path.dirname(filePath), { recursive: true })
+        await writeFile(filePath, content, "utf-8")
+      }
+
+      await installItemDependencies(cwd, item)
+    }
+  } else {
+    for (const item of payload) {
+      spinner.message(`Installing block ${highlight(item.name)}...`)
+
+      for (const file of item.files) {
+        const relativePath = file.target ?? file.name
+        let filePath = path.resolve(cwd, relativePath)
+        const content = await transform({
+          filename: path.basename(filePath),
+          raw: file.content,
+          config
+        })
+
+        if (!config.tsx) {
+          filePath = filePath.replace(/\.tsx$/, ".jsx").replace(/\.ts$/, ".js")
+        }
+
+        if (!overwrite && existsSync(filePath)) {
+          spinner.stop()
+          const prompts = await p.group(
+            {
+              overwrite: () =>
+                p.confirm({
+                  message: `File ${relativePath} already exists. Overwrite?`,
+                  initialValue: false
+                })
+            },
+            {
+              onCancel: () => {
+                p.cancel("Cancelled.")
+                process.exit(0)
+              }
+            }
+          )
+          if (!prompts.overwrite) {
+            p.log.info(`Skipped ${relativePath}.`)
+            spinner.start(`Installing block ${highlight(item.name)}...`)
+            continue
+          }
+          spinner.start(`Installing block ${highlight(item.name)}...`)
+        }
+
+        await mkdir(path.dirname(filePath), { recursive: true })
+        await writeFile(filePath, content, "utf-8")
+      }
+
+      await installItemDependencies(cwd, item)
+
+      const uiDeps = item.registryDependencies ?? []
+      if (uiDeps.length) {
+        p.log.info(
+          `Block ${item.name} depends on UI components: ${uiDeps.join(", ")}. Run ${highlight(`solidui-cli add ${uiDeps.join(" ")}`)} if needed.`
+        )
+      }
+    }
+  }
+
+  spinner.stop("Done.")
+}
+
+async function installItemDependencies(cwd: string, item: RegistryItem) {
+  if (!item.dependencies?.length) {
+    return
+  }
+  const packageManager = await getPackageManager(cwd)
+  await execa(
+    packageManager,
+    ["add", packageManager === "deno" ? "--npm" : "", ...item.dependencies],
+    { cwd }
+  )
+}
diff --git a/packages/cli/src/utils/registry.ts b/packages/cli/src/utils/registry.ts
index d55372f0..6e46d9ba 100644
--- a/packages/cli/src/utils/registry.ts
+++ b/packages/cli/src/utils/registry.ts
@@ -1,54 +1,65 @@
 import * as v from "valibot"
 
-const BASE_URL = "https://www.solid-ui.com"
+export function getRegistryBaseUrl() {
+  const fromEnv = process.env.SOLIDUI_REGISTRY_URL?.replace(/\/$/, "")
+  return fromEnv ?? "https://www.solid-ui.com"
+}
 
 export const RegistryIndexSchema = v.array(
   v.object({
     name: v.string(),
     dependencies: v.optional(v.array(v.string())),
     registryDependencies: v.optional(v.array(v.string())),
-    files: v.array(v.string()),
-    type: v.picklist(["ui", "example"])
+    files: v.optional(v.array(v.string())),
+    type: v.picklist(["ui", "block", "example"])
   })
 )
 
 export type RegistryIndex = v.InferOutput<typeof RegistryIndexSchema>
 
+export const RegistryItemFileSchema = v.object({
+  name: v.string(),
+  content: v.string(),
+  target: v.optional(v.string())
+})
+
 export const RegistryItemSchema = v.object({
   name: v.string(),
   dependencies: v.optional(v.array(v.string())),
-  files: v.array(
-    v.object({
-      name: v.string(),
-      content: v.string()
-    })
-  ),
-  type: v.picklist(["ui", "example"])
+  registryDependencies: v.optional(v.array(v.string())),
+  files: v.array(RegistryItemFileSchema),
+  type: v.picklist(["ui", "block", "example"])
 })
 
 export type RegistryItem = v.InferOutput<typeof RegistryItemSchema>
 
 async function fetchRegistry(paths: string[]) {
+  const baseUrl = getRegistryBaseUrl()
   try {
     const results = await Promise.all(
-      paths.map(async (path) => {
-        const response = await fetch(`${BASE_URL}/registry/${path}`)
+      paths.map(async (registryPath) => {
+        const response = await fetch(`${baseUrl}/registry/${registryPath}`)
+        if (!response.ok) {
+          throw new Error(`${response.status} ${response.statusText}`)
+        }
         return await response.json()
       })
     )
     return results
   } catch (e) {
     console.log(e)
-    throw new Error(`Failed to fetch registry from ${BASE_URL}.`)
+    throw new Error(`Failed to fetch registry from ${baseUrl}.`)
   }
 }
 
-export async function getRegistryIndex() {
+export async function getRegistryIndex(kind: "ui" | "block" = "ui") {
   try {
-    const [result] = await fetchRegistry(["index.json"])
-    return v.parse(RegistryIndexSchema, result).filter((item) => item.type === "ui")
+    const indexPath = kind === "ui" ? "index.json" : "blocks/index.json"
+    const [result] = await fetchRegistry([indexPath])
+    const parsed = v.parse(RegistryIndexSchema, result)
+    return parsed.filter((item) => item.type === kind)
   } catch (e) {
-    throw new Error(`Failed to fetch components from registry.`)
+    throw new Error(`Failed to fetch ${kind} components from registry.`)
   }
 }
 
@@ -69,15 +80,15 @@ export async function resolveTree(index: RegistryIndex, names: string[]) {
     }
   }
 
-  // filter out duplicates
   return tree.filter(
     (component, idx, self) => self.findIndex((c) => c.name === component.name) === idx
   )
 }
 
-export async function fetchTree(tree: RegistryIndex) {
+export async function fetchRegistryItems(tree: RegistryIndex, kind: "ui" | "block") {
   try {
-    const paths = tree.map((item) => `ui/${item.name}.json`)
+    const prefix = kind === "ui" ? "ui" : "block"
+    const paths = tree.map((item) => `${prefix}/${item.name}.json`)
     const results = await fetchRegistry(paths)
 
     return v.parse(v.array(RegistryItemSchema), results)
diff --git a/packages/cli/src/utils/templates.ts b/packages/cli/src/utils/templates.ts
index d351a1ec..2bf15cae 100644
--- a/packages/cli/src/utils/templates.ts
+++ b/packages/cli/src/utils/templates.ts
@@ -262,3 +262,58 @@ export const TAILWIND_CSS = `@tailwind base;
   display: none;
 }
 `
+
+export const COLOR_MODE_SNIPPETS = `# Color mode setup (Solid UI)
+
+Generated by \`solidui-cli init --with-color-mode\`. Pick the section that matches your stack.
+
+## SolidStart (cookie SSR)
+
+\`\`\`tsx
+import { isServer } from "solid-js/web"
+import { ColorModeProvider, ColorModeScript, cookieStorageManagerSSR } from "@kobalte/core"
+import { getCookie } from "vinxi/http"
+
+function getServerCookies() {
+  "use server"
+  const colorMode = getCookie("kb-color-mode")
+  return colorMode ? \`kb-color-mode=\${colorMode}\` : ""
+}
+
+// Inside Router root:
+const storageManager = cookieStorageManagerSSR(isServer ? getServerCookies() : document.cookie)
+
+<ColorModeScript storageType={storageManager.type} />
+<ColorModeProvider storageManager={storageManager}>
+  {props.children}
+</ColorModeProvider>
+\`\`\`
+
+Then add \`npx solidui-cli@latest add mode-toggle\` and place \`<ModeToggle />\` in your layout.
+
+## Vite / SPA (localStorage)
+
+\`\`\`tsx
+import { ColorModeProvider, ColorModeScript, createLocalStorageManager } from "@kobalte/core"
+
+const storageManager = createLocalStorageManager("solid-ui-theme")
+
+<ColorModeScript storageType={storageManager.type} />
+<ColorModeProvider storageManager={storageManager}>
+  {props.children}
+</ColorModeProvider>
+\`\`\`
+
+## Tailwind note
+
+CLI \`init\` scaffolds **Tailwind CSS v3** (\`tailwind.config.cjs\`). The solid-ui.com docs site uses **v4**.
+Components such as \`sidebar\` use CSS variables compatible with both; avoid v4-only syntax like \`w-(--var)\` in custom code.
+`
+
+export const POSTCSS_CONFIG = `module.exports = {
+  plugins: {
+    tailwindcss: {},
+    autoprefixer: {}
+  }
+}
+`