@thorprovider/create-storefront 0.1.1

package/skills/sf-view-gen/SKILL.md

@@ -0,0 +1,94 @@
+---
+name: sf-view-gen
+description: Add a new view or modify an existing view in a Thor Commerce storefront, selecting block variants and optional sections from this package's recipes
+---
+
+# sf-view-gen
+
+Generate or modify a single view, driven by this package's **recipe registry** so storefronts are not identical.
+
+Self-contained: never read `projects/electrostore` or machine-global skills.
+
+## Resolving package assets
+
+Recipes live **inside the installed package**, not in the target project. Resolve the package root before running the validator:
+
+1. If `.opencode/.create-storefront-root` exists in the target project, read it — the installer writes the absolute package root there.
+2. Otherwise, if this skill was loaded from a path under `.opencode/skills/sf-view-gen/`, walk upward from there to the package root.
+3. Run the validator as `node <package-root>/recipes/validate.mjs ...` (do not assume a project-local `recipes/`).
+
+If the package root cannot be resolved, STOP and tell the user to re-run the installer.
+
+## Allowed views
+`home`, `product`, `category`, `checkout`, `user-panel`
+
+Reject any other name with the full allowed list.
+
+## Recipe registry (the source of variety)
+
+- `recipes/recipes.json` — per view: `route`, `loader`, `requiredDataKeys`, `defaultVariants`, `allowedVariants`, `optionalSections`
+- `recipes/sections.json` — optional sections → `elementType`, `variants`, `defaultVariant`, `propsHint`
+- `recipes/archetypes.json` — the **archetype (intent) layer**: per slot (`<view>.<slot>`) a set of named **intents**, each with a `variant` and a `when` usage hint, plus the slot `default` intent
+- `recipes/validate.mjs` — validator. Use it:
+  ```bash
+  node recipes/validate.mjs list
+  node recipes/validate.mjs show <view>
+  node recipes/validate.mjs archetypes
+  node recipes/validate.mjs resolve <view> <slot> <intent>
+  node recipes/validate.mjs validate '<composition-json>'
+  ```
+
+## json-render references (consult when authoring element types)
+
+When adding a view you register new element `type`s in `catalog.ts` (zod props) and `registry.tsx` (component mapping + action wiring). Consult the vendored references instead of working from memory:
+
+- `skills/json-render-core/` — catalog/schema/spec authoring (the shape of a catalog entry and a spec element)
+- `skills/json-render-react/` — registry mapping and action wiring (`defineRegistry`, `Renderer`, `useStateStore`)
+
+**Selection rule:** choose an **intent by meaning** from the user's description (never a raw variant ordinal), then resolve the intent to its variant via `recipes/archetypes.json`. The resolved variant must be allowed by the recipe for that slot. Choose optional sections the same way. Never invent an intent, variant, or component. If the description is silent, use the archetype slot `default`.
+
+```bash
+node recipes/validate.mjs resolve home hero showcase   # -> StorefrontHero2
+```
+
+## Stack constraints
+- UI: only `@thorprovider/blocks`
+- Data: only `@thorprovider/adapters` + `@thorprovider/storefronts/commerce`
+- Never `@thorprovider/medusa-extended`
+- No custom blocks without explicit user authorization
+- Every element `type` used in a spec MUST be registered in `catalog.ts` AND `registry.tsx`
+
+## Add-view workflow
+
+1. Parse `$ARGUMENTS` → view name (+ optional description). Validate name. Confirm `lib/<name>/` exists (else suggest `/sf-init`).
+2. `node recipes/validate.mjs show <view>` — read slots, allowed variants + sections. `node recipes/validate.mjs archetypes` — read slots with their named intents.
+3. Choose an intent per slot by meaning from the description (defaults if silent), resolve each with `node recipes/validate.mjs resolve <view> <slot> <intent>`, then validate the full composition with `node recipes/validate.mjs validate '<json>'` before writing.
+4. Write `lib/<name>/spec/<view>.ts` using chosen blocks:
+   - product → `ProductOverview`/`ProductCard`/`ReviewRating` variants
+   - category → `ProductCategory`/`CategoryFilter`/`ProductCard` variants
+   - checkout → `Checkout`/`CheckoutConfirmation` plus cart-backed state
+   - user-panel → `AppShell`/`OrderHistory`/`LoginPage`/`SignUpPage` variants
+   - Any chosen optional section → add its `elementType` element (from `sections.json`).
+5. Register new element `type`s in `catalog.ts` (zod props) and `registry.tsx` (map to the blocks component).
+6. Register the route+loader in `lib/<name>/spec/index.ts` and the loader in `runtime.ts` (data via `@thorprovider/storefronts/commerce`).
+7. Verify: `pnpm typecheck`; every new `type` present in catalog+registry; no non-blocks UI import; no direct HTTP.
+
+## Modify workflow (`/sf-view`)
+
+1. Parse view name + change. Validate name.
+2. Read `lib/<name>/spec/<view>.ts` fully.
+3. Apply ONLY the change. Preserve ids, `type`, untouched `props`, `$state`, `on` wiring, route/loader/catalog/registry.
+4. If new blocks are needed, choose intents from `archetypes.json`, resolve to allowed variants, and validate before writing.
+5. Re-run `pnpm typecheck`.
+
+## Generation headers
+Every generated/edited file gets:
+```
+// Generated by @thorprovider/create-storefront (sf-view-gen) from recipes/<view>
+```
+
+## Error handling
+- Unknown view → error + allowed list, stop.
+- Missing `lib/<name>/` → suggest `/sf-init`, stop.
+- Undeclared variant/section → reject via `recipes/validate.mjs`, show allowed options.
+- Type errors → fix before finishing; never leave broken specs.

package/skills/shadcn-component-discovery/SKILL.md

@@ -0,0 +1,273 @@
+---
+name: shadcn-component-discovery
+description: Discover shadcn-compatible components and registries across the entire ecosystem before writing any custom UI. Use PROACTIVELY before building tables, forms, modals, animations, dashboards, auth pages, or any UI component. Use when the user says "find a component for...", "is there something for...", "search registries", "what exists for...", or asks about shadcn blocks, Magic UI, Aceternity, ReUI, Animate UI, DiceUI, Tailark, AI Elements, or any other shadcn-compatible registry. Complements the official shadcn skill by surfacing registries beyond the user's configured `components.json` — use when exploring what's available to add, not just what's already installed.
+---
+
+# shadcn Component Discovery
+
+Surface existing components from across the shadcn ecosystem — including registries the user hasn't configured yet — before spending effort on custom implementations.
+
+## How This Complements the Official shadcn Skill
+
+The official `shadcn` skill (shipped with CLI v4) searches the registries declared in the user's `components.json`. That's the right tool once the user has decided which registries to use.
+
+This skill fills the *upstream* gap: ecosystem-wide awareness. It helps the user find and choose registries they may not yet have configured — Magic UI for animations, Aceternity for hero sections, AI Elements for chat interfaces, ElevenLabs UI for voice components, and so on. Use this skill for "what exists out there"; let the official skill handle "install this thing I know about."
+
+When both skills apply, this one runs first (discovery), then the official skill takes over for installation and project-aware work.
+
+## Core Principle
+
+Search before building. Most UI needs have been solved in the shadcn ecosystem. The cost of a 10-second registry check is almost always less than custom-building something that already exists.
+
+## When to Trigger
+
+**Proactive triggers** (activate before writing any component code):
+
+- User asks to build a table, form, modal, sidebar, dashboard, auth page, landing section, animation, carousel, chart, or any standard UI pattern
+- User describes a feature that implies UI (e.g. "add user accounts management" → table; "let users pick a date range" → date picker)
+- User mentions building something "like X" where X is a common pattern
+
+**Explicit triggers** (user directly requests search):
+
+- "Find a component for..."
+- "Is there a shadcn component for..."
+- "Search registries for..."
+- "What exists for..."
+- "Any good [category] components?"
+- Direct mentions of specific registries (@animate-ui, Magic UI, Aceternity, Tailark, etc.)
+
+## Workflow
+
+### Step 1: Clarify the Need
+
+Before searching, confirm:
+
+- **Functionality**: What must it do? (e.g. sortable + filterable + paginated table)
+- **Style**: Animated, minimal, accessible-first, dense, brutalist?
+- **Constraints**: Must support keyboard nav? Drag-drop? Mobile-first? SSR?
+
+A two-sentence clarification beats five searches with the wrong query.
+
+### Step 2: Search
+
+Three paths depending on tool availability. The **official shadcn MCP** is strongly preferred when the user has a shadcn project — it returns real results with code examples.
+
+#### Path A: Official shadcn MCP (preferred)
+
+If the shadcn MCP server is running (configured via `npx shadcn@latest mcp init` or equivalent), use its tools directly:
+
+```text
+1. mcp__shadcn__search_items_in_registries
+   - registries: ["@shadcn", "@blocks", "@animate-ui", "@reui", "@diceui"]
+   - query: "<search term>"
+   - limit: 10
+
+2. For promising results, get full details:
+   mcp__shadcn__view_items_in_registries
+   - items: ["@registry/component-name", "@registry/other"]
+
+3. For implementation examples:
+   mcp__shadcn__get_item_examples_from_registries
+   - query: "<component>-demo"
+
+4. For the install command:
+   mcp__shadcn__get_add_command_for_items
+   - items: ["@registry/chosen-component"]
+```
+
+The MCP only searches registries configured in the user's `components.json`. If the user is looking for something specialized, suggest adding a relevant registry to `components.json` first — see `references/registries.md` for recommendations and configuration snippets.
+
+#### Path B: shadcn CLI (no MCP, but shadcn project)
+
+If there's a `components.json` but no MCP is configured, use the CLI commands that shipped with CLI v3:
+
+```bash
+# Search across configured registries
+npx shadcn@latest search "<term>"
+
+# Preview a component before installing
+npx shadcn@latest view @registry/component-name
+
+# List everything available in a registry
+npx shadcn@latest list @registry
+```
+
+Suggest adding the MCP for better agent integration: `npx shadcn@latest mcp init`.
+
+#### Path C: No project context
+
+If there's no shadcn project yet, or the user is just exploring:
+
+- Recommend registries from `references/registries.md` based on their described need
+- Link directly to the registry's website so they can browse
+- Offer to help set up a shadcn project (`npx shadcn@latest init`) once they've picked direction
+
+### Step 3: Present Findings
+
+Match the response format to the context. Keep it scannable — the user is about to make a decision, not read an essay.
+
+#### Proactive check (during build flow)
+
+When the user didn't explicitly ask to search but you searched anyway:
+
+```markdown
+Before building custom, I found existing options:
+
+1. **@registry/component-name** — [one-line description]
+2. **@registry/alternative** — [one-line description]
+
+Want me to install one, or build custom?
+```
+
+Keep it under five lines. The user is in flow; don't derail them.
+
+#### Explicit search (user asked)
+
+```markdown
+## Results for "<query>"
+
+**Top matches:**
+
+### @registry/component-name ⭐
+[What it does in one sentence]
+- Fits because: [specific to their need]
+- Install: `npx shadcn@latest add @registry/component-name`
+
+### @registry/alternative
+[What it does in one sentence]
+- Fits because: [specific to their need]
+- Install: `npx shadcn@latest add @registry/alternative`
+
+---
+Install [1] or [2], see more results, view code example, or build custom?
+```
+
+#### Comparison (multiple good options, choice matters)
+
+Use a short table when 3+ options are genuinely viable and trade off differently. Follow with a recommendation and the install command for the recommended one. Don't table-ify everything — it's heavier than plain prose and should earn its place.
+
+### Step 4: Execute the Choice
+
+- **Install chosen**: Run the `add` command, then customize via props / composition as needed
+- **See more**: Return additional matches, continue pagination
+- **View code**: Fetch example via `get_item_examples_from_registries` or the registry's demo URL
+- **Build custom**: Proceed — but reference the closest existing component for composition patterns (CVA, `cn()`, `data-slot`, semantic tokens)
+
+## Search Strategy
+
+### Effective Query Terms
+
+Short, concrete nouns work best. Keep queries to 1–3 words.
+
+| Looking for… | Try searching… |
+|---|---|
+| Data display | `table`, `data-grid`, `list` |
+| User input | `form`, `input`, `field`, `select`, `combobox` |
+| Navigation | `sidebar`, `nav`, `menu`, `tabs`, `breadcrumb` |
+| Feedback | `toast`, `sonner`, `alert`, `notification` |
+| Overlays | `dialog`, `modal`, `sheet`, `popover`, `drawer` |
+| Media | `carousel`, `gallery`, `image` |
+| Animation | `animate`, `motion`, `transition` |
+| Layout | `card`, `section`, `hero`, `grid`, `stack` |
+| Date/time | `calendar`, `date-picker`, `date-range` |
+
+### Registry Specialties (Quick Pick)
+
+| Need | Check first |
+|---|---|
+| Core UI primitives | `@shadcn` |
+| Page sections, pre-built blocks | `@blocks`, Tailark, HextaUI |
+| Data grids, advanced tables | `@reui` |
+| Animated components | `@animate-ui`, Magic UI, Aceternity UI |
+| AI / chat interfaces | AI Elements, assistant-ui |
+| Accessibility-first (React Aria) | `@diceui`, JollyUI, Intent UI |
+| Voice / audio | ElevenLabs UI |
+| Marketing / landing pages | Tailark, Eldora UI |
+| Style variants (brutalist, retro, glass) | See `references/registries.md` |
+
+For the full catalog including URLs, configuration snippets, and registry specialties, see [references/registries.md](references/registries.md).
+
+## Response Requirements
+
+Every discovery response should surface:
+
+1. **What was searched** — the query used
+2. **Top 2–3 recommendations** — registry-qualified name, one-line description, why it fits
+3. **Install command** — ready to copy
+4. **A recommendation** — which to pick, when there's a clear fit
+5. **Next-step options** — install, view code, see more, build custom
+
+Skip anything beyond this unless the user asks. Brevity respects flow.
+
+## Examples
+
+### Proactive check
+
+**User:** "Add a table showing user accounts with sorting"
+
+**Response:**
+
+> Before building custom, I found existing options:
+>
+> 1. **@reui/data-grid-table** — Full-featured grid with sorting, filtering, pagination
+> 2. **@shadcn/table** — Unstyled primitives (pair with TanStack Table for sorting)
+>
+> `@reui/data-grid-table` looks like the fit — install it?
+
+### Explicit search
+
+**User:** "Find me an animated accordion"
+
+**Response:**
+
+> ## Results for "animated accordion"
+>
+> ### @animate-ui/components-base-accordion ⭐
+> Accordion with smooth enter/exit transitions built on Motion.
+> - Fits because: Animation is built-in, accessible, keyboard nav included
+> - Install: `npx shadcn@latest add @animate-ui/components-base-accordion`
+>
+> ### @shadcn/accordion
+> Standard Radix-based accordion, unanimated by default.
+> - Fits because: Lighter dependency footprint; you add your own motion
+> - Install: `npx shadcn@latest add @shadcn/accordion`
+>
+> ---
+> Install animated [1], install plain [2], or see more?
+
+### No good match
+
+**User:** "Find a component for visualizing git commit lineage"
+
+**Response:**
+
+> ## Results for "git commit lineage"
+>
+> No directly matching components in the shadcn ecosystem. Closest adjacencies:
+> - `@reui/tree` — tree visualizations (could adapt)
+> - `@shadcn/chart` — generic charting (Recharts-based)
+>
+> This is a custom build. Want me to sketch an approach using one of these as a foundation, or look at non-shadcn libraries like `@gitgraph/react`?
+
+## Best Practices
+
+**Do:**
+- Search before writing component code — always
+- Surface 2–3 options, not 10
+- Explain *why* each fits the specific need
+- Include the install command, not just the name
+- Recommend when the choice is clear
+
+**Don't:**
+- Skip searching because "it's faster to build" (it usually isn't)
+- Dump the full search-result list — curate
+- Present registries the user hasn't configured without mentioning the `components.json` step
+- Recommend unmaintained or abandoned registries (check `references/registries.md` for current status)
+
+## Resources
+
+- **Registry catalog**: [references/registries.md](references/registries.md)
+- **Official shadcn docs**: https://ui.shadcn.com
+- **Official shadcn MCP docs**: https://ui.shadcn.com/docs/mcp
+- **Registry browser**: https://registry.directory
+- **Component index**: https://shadcnregistry.com

package/skills/shadcn-component-discovery/references/registries.md

@@ -0,0 +1,226 @@
+# shadcn-Compatible Registry Catalog
+
+Curated catalog of registries that work with the shadcn CLI and MCP, organized by specialty. Recommendations here are for narrowing the field quickly — for an exhaustive live list, see the canonical aggregator at [shadcn.io/awesome/registries](https://www.shadcn.io/awesome/registries).
+
+## Core Registries
+
+Well-maintained registries that cover most project needs. Start here.
+
+### @shadcn — Official primitives
+**URL:** [ui.shadcn.com](https://ui.shadcn.com)
+**Focus:** Core UI primitives built on Radix or Base UI
+**Best for:** Buttons, inputs, cards, dialogs, tables, the foundational layer of any project
+
+### @blocks — Official blocks
+**URL:** [ui.shadcn.com/blocks](https://ui.shadcn.com/blocks)
+**Focus:** Pre-built page sections using official primitives
+**Best for:** Dashboards, auth pages, sidebars, settings layouts — production-ready starting points
+
+### @reui
+**URL:** [reui.io](https://reui.io)
+**Focus:** Advanced components and full app templates
+**Best for:** Data grids, complex forms, admin panels, full page templates beyond basic primitives
+
+### @animate-ui
+**URL:** [animate-ui.com](https://animate-ui.com)
+**Focus:** Animated components built with Motion (formerly Framer Motion)
+**Best for:** Transitions, micro-interactions, animated backgrounds, polished UI
+
+### @aceternity
+**URL:** [ui.aceternity.com](https://ui.aceternity.com)
+**Focus:** Effect-heavy animated components and landing page elements
+**Best for:** Hero sections, 3D cards, spotlight effects, visually striking marketing pages
+
+### @diceui
+**URL:** [diceui.com](https://diceui.com)
+**Focus:** Accessibility-first components (React Aria based)
+**Best for:** Enterprise apps, WCAG-compliant projects, keyboard-heavy UIs
+
+---
+
+## Specialty Registries
+
+### AI & Chat Interfaces
+
+| Registry | Focus | URL |
+|---|---|---|
+| AI Elements | Radix-style primitives for AI chat, message threads, streaming | [aielements.dev](https://aielements.dev) |
+| assistant-ui | AI assistant interfaces with backend adapters (AI SDK, LangGraph, Mastra) | [assistant-ui.com](https://assistant-ui.com) |
+| Manifest UI | ChatGPT-style application patterns | [manifest-ui.com](https://manifest-ui.com) |
+
+**Search terms:** `chat`, `message`, `conversation`, `ai`, `assistant`, `streaming`, `thread`
+
+### Animation & Motion
+
+| Registry | Focus | URL |
+|---|---|---|
+| Magic UI | Animated components, especially landing-page focused | [magicui.design](https://magicui.design) |
+| Cult UI | Design-engineer animations and interactions | [cult-ui.com](https://cult-ui.com) |
+| Motion Primitives | Low-level motion building blocks | [motion-primitives.com](https://motion-primitives.com) |
+| Kokonut UI | Stylized animated UI components | [kokonutui.com](https://kokonutui.com) |
+
+**Search terms:** `animate`, `motion`, `transition`, `hover`, `entrance`, `particles`
+
+### Marketing & Landing Pages
+
+| Registry | Focus | URL |
+|---|---|---|
+| Tailark | Marketing-focused blocks | [tailark.com](https://tailark.com) |
+| Shadcnblocks | Premium block library with 1000+ blocks and templates (paid) | [shadcnblocks.com](https://shadcnblocks.com) |
+| Eldora UI | Landing page components | [eldoraui.com](https://eldoraui.com) |
+| HextaUI | Extended blocks and components | [hextaui.com](https://hextaui.com) |
+
+**Search terms:** `hero`, `cta`, `pricing`, `features`, `testimonial`, `landing`
+
+### Data & Tables
+
+| Registry | Focus | URL |
+|---|---|---|
+| @reui | Advanced data grids with sorting/filtering/DnD | [reui.io](https://reui.io) |
+
+**Search terms:** `table`, `data-grid`, `column`, `sort`, `filter`, `pagination`, `virtualized`
+
+**Note:** For very large or complex tables, `@shadcn/table` + TanStack Table is often the better path than a pre-built grid. The shadcn Data Table docs cover this pattern.
+
+### Forms & Validation
+
+| Registry | Focus | URL |
+|---|---|---|
+| @shadcn | Core form primitives (`form`, `input`, `field`, `field-group`, `input-group`) | [ui.shadcn.com](https://ui.shadcn.com) |
+| Shadcn Form Builder | Form-generation utilities | [shadcn-form-builder.vercel.app](https://shadcn-form-builder.vercel.app) |
+
+**Search terms:** `form`, `input`, `field`, `validation`, `submit`
+
+### Voice & Audio
+
+| Registry | Focus | URL |
+|---|---|---|
+| ElevenLabs UI | Voice agents, audio players, waveform visualizations | [elevenlabs.io](https://elevenlabs.io) |
+
+**Search terms:** `audio`, `voice`, `waveform`, `player`, `orb`
+
+### Style Variants
+
+| Registry | Style | URL |
+|---|---|---|
+| 8bitcn | Retro 8-bit pixel style | [8bitcn.com](https://8bitcn.com) |
+| RetroUI | Neobrutalism | [retroui.dev](https://retroui.dev) |
+| Neobrutalism UI | Bold brutalist aesthetic | [neobrutalism.dev](https://neobrutalism.dev) |
+
+**Search terms:** `retro`, `brutalist`, `glass`, `pixel`, `8bit`
+
+### Accessibility-First
+
+| Registry | Focus | URL |
+|---|---|---|
+| JollyUI | React Aria based | [jollyui.dev](https://jollyui.dev) |
+| Intent UI | Accessible, customizable | [intent-ui.com](https://intent-ui.com) |
+| Kibo UI | Composable, accessible patterns | [kibo-ui.com](https://kibo-ui.com) |
+
+**Search terms:** `accessible`, `aria`, `a11y`, `keyboard`
+
+### Icons
+
+| Registry | Focus | URL |
+|---|---|---|
+| pqoqubbw/icons | Animated Lucide icons | [icons.pqoqubbw.dev](https://icons.pqoqubbw.dev) |
+
+**Search terms:** `icon`, `animated-icon`, `lucide`
+
+---
+
+## Quick-Pick by Project Type
+
+| Building… | Start with |
+|---|---|
+| SaaS dashboard | `@shadcn`, `@blocks`, `@reui` |
+| Marketing site | Tailark, Aceternity, Magic UI |
+| AI application | AI Elements, assistant-ui, `@animate-ui` |
+| Admin panel | `@reui`, `@blocks`, `@diceui` |
+| E-commerce | `@shadcn`, `@blocks`, `@reui` |
+| Portfolio | Aceternity, Magic UI, Cult UI |
+| Enterprise app | `@diceui`, JollyUI, `@shadcn` |
+| Voice / audio app | ElevenLabs UI, `@shadcn` |
+
+---
+
+## Configuring Registries
+
+Since shadcn CLI 3.0, registries are declared with namespaces in `components.json` using a `{name}` URL template:
+
+```json
+{
+  "registries": {
+    "@animate-ui": "https://animate-ui.com/r/{name}.json",
+    "@aceternity": "https://ui.aceternity.com/registry/{name}.json",
+    "@reui": "https://reui.io/r/{name}.json",
+    "@magicui": "https://magicui.design/r/{name}.json"
+  }
+}
+```
+
+For each registry, check the registry's own docs for the exact URL — templates occasionally differ. Once registered, install with `npx shadcn@latest add @namespace/component-name`.
+
+### Authenticated Registries
+
+Paid or private registries take a config object with headers:
+
+```json
+{
+  "registries": {
+    "@shadcnblocks": {
+      "url": "https://shadcnblocks.com/r/{name}.json",
+      "headers": {
+        "Authorization": "Bearer ${SHADCNBLOCKS_API_KEY}"
+      }
+    }
+  }
+}
+```
+
+The `${ENV_VAR}` syntax reads from the environment at CLI/MCP invocation time. Never commit raw tokens.
+
+---
+
+## Discovery Commands (CLI)
+
+shadcn CLI ships search and discovery commands that complement MCP-based discovery:
+
+```bash
+# Search configured registries
+npx shadcn@latest search "data table"
+
+# Preview a component before installing
+npx shadcn@latest view @reui/data-grid-table
+
+# List everything in a registry
+npx shadcn@latest list @animate-ui
+
+# Get documentation and examples for an installed component
+npx shadcn@latest docs combobox
+```
+
+---
+
+## Browsing Registries Manually
+
+When the MCP or CLI isn't available (or the user wants to browse visually):
+
+- **[shadcn.io/awesome/registries](https://www.shadcn.io/awesome/registries)** — Canonical aggregator, maintained alongside the docs
+- **[registry.directory](https://registry.directory)** — Third-party registry browser
+- **[shadcnregistry.com](https://shadcnregistry.com)** — Searchable component index across registries
+- **[ui.shadcn.com/blocks](https://ui.shadcn.com/blocks)** — Official blocks gallery
+
+Each registry's own site typically has demos and copy-pasteable snippets.
+
+---
+
+## Notes on Registry Health
+
+Registry quality and maintenance varies. When recommending a registry, favor:
+
+- Registries referenced on the official shadcn.io/awesome list (signals active maintenance)
+- Registries with clear `{name}.json` URL schemas (signals MCP/CLI compatibility)
+- Registries with demos and example code (signals commitment to usability)
+
+Avoid recommending registries without recent updates, without clear documentation, or with broken install flows. When in doubt, fall back to `@shadcn` + `@blocks` + build custom.