From e83432a4f1b9be7b5457f101baf296dd0a75e9ed Mon Sep 17 00:00:00 2001
From: Faster Marketplace <marketplace@fasterhq.com>
Date: Fri, 16 Jan 2026 11:48:44 +0000
Subject: [PATCH] Add registry documentation

---
 CLAUDE.md | 125 ++++++++++++++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 125 insertions(+)
 create mode 100644 CLAUDE.md

diff --git a/CLAUDE.md b/CLAUDE.md
new file mode 100644
index 0000000..591b59c
--- /dev/null
+++ b/CLAUDE.md
@@ -0,0 +1,125 @@
+# Faster Marketplace Registry
+
+This repository manages the marketplace catalog for themes and components.
+Changes to this registry are automatically synced to the database.
+
+## Structure
+
+```
+_registry/
+├── themes.json      # All published themes
+├── components.json  # All published components
+└── CLAUDE.md        # This documentation
+```
+
+## Adding a Theme
+
+Add an entry to `themes.json`:
+
+```json
+{
+  "uuid": "your-unique-uuid-here",
+  "name": "Theme Name",
+  "slug": "theme-name",
+  "description": "Theme description",
+  "category": "business",
+  "repo_name": "theme-your-unique-uuid-here",
+  "repo_url": "https://gitea.../faster-marketplace/theme-your-unique-uuid-here",
+  "version": "1.0.0",
+  "image": "https://example.com/screenshot.png",
+  "status": "active"
+}
+```
+
+### Required Fields
+| Field | Description |
+|-------|-------------|
+| `uuid` | Unique identifier (generate with `uuidgen` or online tool) |
+| `name` | Display name of the theme |
+| `category` | One of: business, portfolio, blog, ecommerce, landing |
+
+### Optional Fields
+| Field | Default |
+|-------|---------|
+| `slug` | Same as uuid |
+| `description` | Empty string |
+| `repo_name` | `theme-{uuid}` |
+| `repo_url` | Auto-generated |
+| `version` | `1.0.0` |
+| `image` | Placeholder image |
+| `status` | `active` |
+
+## Adding a Component
+
+Add an entry to `components.json`:
+
+```json
+{
+  "uuid": "your-unique-uuid-here",
+  "name": "Component Name",
+  "slug": "component-name",
+  "description": "Component description",
+  "category": "hero",
+  "repo_name": "component-your-unique-uuid-here",
+  "repo_url": "https://gitea.../faster-marketplace/component-your-unique-uuid-here",
+  "version": "1.0.0"
+}
+```
+
+## Removing Items
+
+To remove a theme or component:
+1. Delete the entry from themes.json or components.json
+2. Commit and push
+3. The database record will be soft-deleted automatically
+
+## UUID Generation
+
+Generate a unique UUID before adding:
+
+```bash
+# Linux/Mac
+uuidgen | tr -d '-' | tr '[:upper:]' '[:lower:]'
+
+# Or use: https://www.uuidgenerator.net/
+```
+
+## Sync Behavior
+
+- **Push to registry** → Webhook triggers → Database updated
+- **Add entry** → New StdMarketplaceApp record created
+- **Update entry** → Existing record updated
+- **Remove entry** → Record soft-deleted (status='deleted')
+
+## Theme Repository Structure
+
+Each theme should have its own repo at `faster-marketplace/theme-{uuid}`:
+
+```
+theme-{uuid}/
+├── components/
+│   ├── header.hbs
+│   ├── footer.hbs
+│   └── functional/
+│       └── hero/
+├── templates/
+│   ├── blog.hbs
+│   ├── post.hbs
+│   └── page.hbs
+├── assets/
+│   ├── css/app.css
+│   └── js/index.js
+└── manifest.json
+```
+
+## Component Repository Structure
+
+Each component should have its own repo at `faster-marketplace/component-{uuid}`:
+
+```
+component-{uuid}/
+└── components/
+    └── {component-name}/
+        ├── index.js
+        └── view.hbs
+```