feat: started on new workflow hub feature

Author: simula-r

CLAUDE.md

@@ -0,0 +1,192 @@
+# CLAUDE.md — ComfyUI Workflow Templates Monorepo
+
+## What This Repo Is
+
+A monorepo managing **ComfyUI workflow templates** distributed as Python packages AND a public **Astro-based workflow hub website** at templates.comfy.org. Two distinct systems share the same template data.
+
+## Repository Map
+
+```
+workflow_templates/
+├── templates/              # SOURCE OF TRUTH: workflow JSONs, thumbnails, index metadata
+│   ├── index.json          # Master template metadata (English)
+│   ├── index.{locale}.json # 11 locale variants (zh, ja, ko, es, fr, ru, tr, ar, pt-BR, zh-TW)
+│   ├── *.json              # ComfyUI workflow definitions
+│   └── *-1.webp, *-2.webp # Template thumbnails
+├── blueprints/             # Reusable subgraph blueprint definitions
+├── bundles.json            # Maps template names → Python package bundles
+├── blueprints_bundles.json # Maps blueprint names → package
+├── packages/               # Python distribution packages (Nx monorepo)
+│   ├── core/               # Loader + manifest
+│   ├── media_api/          # API-calling templates (Replicate, BFL, etc.)
+│   ├── media_image/        # Image generation templates
+│   ├── media_video/        # Video generation templates
+│   ├── media_other/        # Audio, 3D, utilities
+│   ├── meta/               # Meta package aggregating all above
+│   └── blueprints/         # Subgraph blueprints package
+├── scripts/                # Python: validation, sync, i18n
+├── site/                   # INDEPENDENT Astro 5 project (see "Site" section below)
+├── docs/                   # Specs, i18n guide, publishing guide
+├── .claude/skills/         # 6 Claude skill definitions
+├── .github/workflows/      # CI/CD (validation, deploy, lint, tests)
+├── pyproject.toml          # Python project version & config
+├── package.json            # Nx monorepo root (npm run sync, etc.)
+└── nx.json                 # Nx workspace config
+```
+
+## Two Distinct Systems
+
+### System 1: Template Packages (Python/PyPI)
+- Templates are grouped into 4 media bundles via `bundles.json`
+- `scripts/sync_bundles.py` copies templates + thumbnails into package directories
+- Published to PyPI as `comfyui-workflow-templates-*` packages
+- Version lives in root `pyproject.toml` (currently 0.8.43)
+
+### System 2: Astro Website (`site/`)
+- **Independent project** — own `package.json`, `pnpm-lock.yaml`, tooling
+- Consumes templates from `../templates/` via sync scripts
+- AI content generation pipeline (GPT-4o) enriches template pages
+- Deployed to Vercel
+
+## Data Flow
+
+```
+templates/index.json + *.json + *.webp
+  ├──→ scripts/sync_bundles.py ──→ packages/media_*/
+  └──→ site/scripts/sync-templates.ts ──→ site/src/content/templates/
+       └──→ site/scripts/generate-ai.ts ──→ AI-enriched content
+            └──→ astro build ──→ templates.comfy.org (Vercel)
+```
+
+## Key Commands
+
+### Root (template management)
+```bash
+npm run sync              # Sync bundle manifests + assets to packages
+python scripts/validate_templates.py   # Validate template JSON
+python scripts/sync_data.py --templates-dir templates  # Sync i18n translations
+```
+
+### Site (in site/ directory)
+```bash
+pnpm install              # Install deps (required first)
+pnpm run dev              # Dev server at localhost:4321
+pnpm run build            # Full build (prebuild + astro build)
+pnpm run sync             # Sync templates from ../templates/
+pnpm run sync -- --top-50 # Sync top 50 only (faster dev)
+pnpm run generate:ai      # AI content generation (needs OPENAI_API_KEY)
+pnpm run generate:ai -- --skip-ai  # Use placeholder content (no API key needed)
+pnpm run lint             # ESLint
+pnpm run format           # Prettier
+pnpm run test:e2e         # Playwright E2E tests
+```
+
+## Template Structure
+
+### index.json Entry
+Each template in `templates/index.json` has:
+- `name` — Must match the JSON filename (snake_case, no extension)
+- `title`, `description` — Display metadata
+- `mediaType` — "image" | "video" | "audio" | "3d"
+- `mediaSubtype` — Usually "webp"
+- `thumbnailVariant` — "compareSlider" | "hoverDissolve" | "hoverZoom" | "zoomHover" | null
+- `tags`, `models`, `logos`, `date`, `usage`, `size`, `vram`, `searchRank`
+- `tutorialUrl`, `openSource`, `requiresCustomNodes`, `io`
+
+### Workflow JSON Files
+Standard ComfyUI workflow format with embedded model metadata:
+- `properties.models[]` — Download URLs, SHA256 hashes, target directories
+- `properties.cnr_id` + `properties.ver` — Node version pinning
+
+### Thumbnails
+- Named `{template_name}-1.webp` (primary), `{template_name}-2.webp` (comparison)
+- WebP format, target <1MB, 512×512 or 768×768
+
+## Bundle Assignment
+Templates in `bundles.json` map to Python packages:
+| Bundle | Contents |
+|--------|----------|
+| `media-api` | Templates using external APIs |
+| `media-image` | Image generation/editing |
+| `media-video` | Video generation |
+| `media-other` | Audio, 3D, utilities |
+
+## Internationalization
+
+### 11 Supported Languages
+en (default), zh, zh-TW, ja, ko, es, fr, ru, tr, ar, pt-BR
+
+### Template i18n
+- Master: `templates/index.json` (English)
+- Locales: `templates/index.{locale}.json`
+- Translation tracking: `scripts/i18n.json`
+- Sync: `python scripts/sync_data.py --templates-dir templates`
+
+### Site i18n
+- Config: `site/src/i18n/config.ts`
+- UI strings: `site/src/i18n/ui.ts`
+- URL pattern: English at `/templates/`, others at `/{locale}/templates/`
+- SEO: Hreflang tags via `HreflangTags.astro`
+
+## Site Architecture (Astro 5)
+
+### Key Directories
+- `site/src/pages/` — Route pages ([slug].astro, [locale]/templates/)
+- `site/src/components/` — Astro components (TemplateCard, TemplateDetailPage, etc.)
+- `site/src/lib/` — Utilities (templates.ts, urls.ts, slugify.ts, model-logos.ts)
+- `site/src/content/` — Content collections (git-ignored, generated by sync)
+- `site/scripts/` — Build scripts (sync, AI generation, previews, OG images)
+- `site/knowledge/` — AI generation context (prompts, model docs, concepts)
+- `site/overrides/templates/` — Human-edited content (survives AI regeneration)
+
+### AI Content Pipeline
+1. `sync-templates.ts` syncs metadata from `../templates/`
+2. `generate-ai.ts` calls GPT-4o with context from `knowledge/`
+3. Generates: extendedDescription, howToUse[], metaDescription, suggestedUseCases[], faqItems[]
+4. Content templates: tutorial (default), showcase, comparison, breakthrough
+5. Cached in `.content-cache/` with hash-based invalidation
+6. Human overrides in `site/overrides/templates/{name}.json` (set `humanEdited: true`)
+
+### Critical Site Components (DO NOT remove/modify without care)
+- `SEOHead.astro` — Meta tags, structured data
+- `HreflangTags.astro` — i18n SEO
+- `t()` calls, `localizeUrl()` — i18n functions
+- `<Analytics />` — Telemetry
+
+## CI/CD
+
+### Template Validation (triggers on templates/ changes)
+- `validate-templates.yml` — JSON schema validation
+- `validate-blueprints.yml` — Blueprint validation
+- `validate-manifests.yml` — Manifest sync check
+- `link-checker.yml` — Model download URL validation
+
+### Site (triggers on site/ changes)
+- `lint-site.yml` — ESLint + Prettier
+- `e2e-tests-site.yml` — Playwright tests
+- `visual-regression-site.yml` — Visual regression
+- `seo-audit-site.yml` — SEO audit
+- `lighthouse.yml` — Performance checks
+- `deploy-site.yml` — Manual Vercel deploy
+
+## Code Style
+- **Python**: Ruff, line-length 100, py312, rules E/F
+- **TypeScript/Astro**: ESLint + Prettier (configured in site/)
+- **Templates**: snake_case naming, JSON format
+- **Commits**: Bump version in `pyproject.toml` when modifying templates
+
+## Claude Skills Available
+- `/adding-templates` — Add new workflow templates (full workflow)
+- `/managing-bundles` — Move templates between bundles, reorder
+- `/managing-thumbnails` — Add/replace/audit thumbnails
+- `/managing-translations` — Sync/check translations across 11 languages
+- `/editing-site-content` — Edit site page content with overrides
+- `/regenerating-ai-content` — Regenerate AI descriptions, manage cache
+
+## Important Docs
+- `docs/SPEC.md` — Formal template JSON schema
+- `docs/BLUEPRINTS.md` — Subgraph blueprint spec
+- `docs/I18N_GUIDE.md` — Translation management workflow
+- `site/docs/PRD.md` — Product requirements for the site
+- `site/docs/TDD.md` — Technical design document
+- `site/docs/design-integration-guide.md` — REQUIRED when implementing Figma designs

bundles.json

@@ -1,5 +1,6 @@
 {
   "media-api": [
+    "test_purz_template",
     "api_bria_image_edit",
     "api_bria_image_outpainting",
     "api_bytedace_seedance1_5_image_to_video",

docs/CREATORS.md

@@ -0,0 +1,166 @@
+# Creator System — Authorship & Attribution
+
+## Overview
+
+Every workflow template has a **creator** (who built the workflow) and optionally a **model brand** (the AI model it uses). These are independent concepts:
+
+- **Creator** = the person/team who made the workflow (stored as `username`)
+- **Model brand** = the AI provider logo shown on thumbnails (stored in `logos[]`)
+
+## Data Model
+
+### `templates/creators.json`
+
+The single source of truth for creator profiles. Keyed by username:
+
+```json
+{
+  "ComfyUI": {
+    "displayName": "ComfyUI",
+    "handle": "ComfyUI",
+    "summary": "Official ComfyUI workflow templates created by the Comfy team.",
+    "social": "x.com/comaboratory"
+  },
+  "hellorob": {
+    "displayName": "RobTheMan",
+    "handle": "hellorob",
+    "summary": "Rob is a core member of the ComfyUI creative team...",
+    "social": "x.com/hellorob"
+  }
+}
+```
+
+Fields:
+- `displayName` — Shown on cards, profile pages, spotlights
+- `handle` — Used in URLs and @mentions (usually matches the key)
+- `summary` — Bio text for profile pages and creator spotlights
+- `social` — Social link (without `https://` prefix)
+- `avatarUrl` — (optional) URL to avatar image; if absent, an initial-based avatar is generated
+- `coverUrl` — (optional) Profile cover image
+
+### `templates/index.json` — The `username` Field
+
+Every template entry has a `username` field linking it to a creator:
+
+```json
+{
+  "name": "flux_text_to_image",
+  "title": "Flux Text to Image",
+  "username": "ComfyUI",
+  "logos": [{ "provider": "Flux" }],
+  ...
+}
+```
+
+- `username` maps to a key in `creators.json`
+- Default is `"ComfyUI"` for official templates (322 of 333 as of Feb 2026)
+- Community creators get their own username (e.g. `"hellorob"`, `"PurzBeats"`)
+- The `logos[].provider` field is for **model branding only** (thumbnail overlay), NOT authorship
+
+## Data Flow
+
+```
+templates/index.json (username field)
+    │
+    ├─→ site/scripts/sync-templates.ts
+    │     Syncs to site/src/content/templates/*.json
+    │     username is included via TemplateInfo spread
+    │
+    └─→ templates/creators.json (profile data)
+          │
+          ├─→ Astro pages resolve displayName at build time
+          │     index.astro: serializes creatorDisplayName for Vue island
+          │     [username].astro: generates profile pages from creators.json keys
+          │
+          ├─→ Vue components receive creatorDisplayName as prop
+          │     HubBrowse → WorkflowGrid → HubWorkflowCard
+          │
+          ├─→ CreatorsSection.astro: groups templates by username
+          │     Looks up displayName, handle, bio from creators.json
+          │     Excludes "ComfyUI" (too many templates to spotlight)
+          │
+          └─→ WorkflowCard.astro: imports creators.json directly
+                Resolves author from username prop
+```
+
+## URL Structure
+
+- `/templates/` — Hub page with all templates (creator shown on each card)
+- `/templates/{username}/` — Creator profile page (e.g. `/templates/hellorob/`)
+- `/templates/{template-name}/` — Individual template detail page
+
+Profile pages are statically generated from `creators.json` keys via `getStaticPaths()` in `[username].astro`.
+
+## Component Architecture
+
+### Serialization Boundary (Astro → Vue)
+
+Vue islands can't import server-side JSON. The Astro pages pre-resolve the display name:
+
+```
+Astro page (index.astro)
+  → imports creators.json
+  → resolves creatorDisplayName per template
+  → passes serialized array to Vue island
+
+Vue island (HubBrowse.vue)
+  → receives templates with creatorDisplayName
+  → passes through WorkflowGrid → HubWorkflowCard
+```
+
+### Card Components
+
+| Component | Type | How it gets author |
+|-----------|------|--------------------|
+| `HubWorkflowCard.vue` | Vue | `creatorDisplayName` prop (from parent Vue component) |
+| `WorkflowCard.astro` | Astro | Imports `creators.json`, resolves from `username` prop |
+| `CreatorWorkflowCard.astro` | Astro | Receives `authorName` prop from `CreatorSpotlight` |
+
+All cards show:
+- **Author avatar**: Green gradient circle with first initial (consistent across all cards)
+- **Author name**: Resolved display name from creators.json
+- **Logo overlay on thumbnail**: Model brand logo (separate from author — this is `logos[].provider`)
+
+### CreatorsSection
+
+Groups templates by `username`, excludes `"ComfyUI"`, sorts by total usage. Requires `>= 2` templates to appear. Shows top 3 creators with their top 3 workflows each.
+
+## Adding a New Creator
+
+1. Add entry to `templates/creators.json`:
+   ```json
+   "newuser": {
+     "displayName": "New User",
+     "handle": "newuser",
+     "summary": "Description of the creator.",
+     "social": "x.com/newuser"
+   }
+   ```
+
+2. Set `"username": "newuser"` on their templates in `templates/index.json`
+
+3. Run `pnpm run sync` in `site/` to propagate changes
+
+4. A profile page at `/templates/newuser/` is automatically generated
+
+## Key Files
+
+| File | Purpose |
+|------|---------|
+| `templates/creators.json` | Creator profile data (source of truth) |
+| `templates/index.json` | Template metadata with `username` field |
+| `site/scripts/lib/types.ts` | `TemplateInfo.username` type definition |
+| `site/src/content/config.ts` | Content collection schema (includes `username`) |
+| `site/src/pages/templates/index.astro` | Hub page, serializes `creatorDisplayName` |
+| `site/src/pages/templates/[username].astro` | Creator profile page |
+| `site/src/components/hub/HubWorkflowCard.vue` | Vue card (receives `creatorDisplayName` prop) |
+| `site/src/components/hub/WorkflowCard.astro` | Astro card (imports creators.json directly) |
+| `site/src/components/hub/CreatorsSection.astro` | Creator spotlight section |
+| `site/src/components/hub/CreatorSpotlight.astro` | Individual creator row |
+
+## Common Mistakes to Avoid
+
+- **Don't use `logos[0].provider` as the author.** That's model branding (e.g. "Grok", "Flux"), not who made the workflow.
+- **Don't forget the serialization boundary.** Vue islands can't import JSON — resolve display names in Astro and pass as props.
+- **Don't hardcode creator data in components.** Always resolve from `creators.json` via username.
+- **Remember to run sync** after changing `index.json` — the content collection won't update automatically.

site/.gitignore

@@ -1,5 +1,6 @@
 # build output
 dist/
+.vercel/
 # generated types
 .astro/
 
@@ -32,6 +33,7 @@ Thumbs.db
 .content-cache/
 src/content/templates/
 public/thumbnails/
+public/templates/thumbnails/
 public/workflows/
 public/logos/
 public/previews/