From aea3b4f8006c113d8e72e1ba83b30d1ffb02be8d Mon Sep 17 00:00:00 2001
From: Soroush Asadi <soroush@soroushasadi.com>
Date: Sun, 21 Jun 2026 18:50:25 +0330
Subject: [PATCH] feat: add FlatRender Remotion template-creation skill suite

10 skills for building high-quality video templates with Remotion/Three.js:
design-styles, character-design, aspect-ratios, template-composition,
sound-effects, music-picker, template-catalog, svg-colors, persian-fonts,
and flatrender-template-seo (category/tags/SEO/related, code-verified).

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
---
 flatrender-template-seo/SKILL.md       | 171 +++++++++++++++++++++++++
 persian-fonts/SKILL.md                 |  55 ++++++++
 remotion-aspect-ratios/SKILL.md        |  91 +++++++++++++
 remotion-character-design/SKILL.md     |  51 ++++++++
 remotion-design-styles/SKILL.md        |  49 +++++++
 remotion-music-picker/SKILL.md         |  59 +++++++++
 remotion-sound-effects/SKILL.md        |  56 ++++++++
 remotion-svg-colors/SKILL.md           |  45 +++++++
 remotion-template-catalog/SKILL.md     |  54 ++++++++
 remotion-template-composition/SKILL.md |  60 +++++++++
 10 files changed, 691 insertions(+)
 create mode 100644 flatrender-template-seo/SKILL.md
 create mode 100644 persian-fonts/SKILL.md
 create mode 100644 remotion-aspect-ratios/SKILL.md
 create mode 100644 remotion-character-design/SKILL.md
 create mode 100644 remotion-design-styles/SKILL.md
 create mode 100644 remotion-music-picker/SKILL.md
 create mode 100644 remotion-sound-effects/SKILL.md
 create mode 100644 remotion-svg-colors/SKILL.md
 create mode 100644 remotion-template-catalog/SKILL.md
 create mode 100644 remotion-template-composition/SKILL.md

diff --git a/flatrender-template-seo/SKILL.md b/flatrender-template-seo/SKILL.md
new file mode 100644
index 0000000..286a113
--- /dev/null
+++ b/flatrender-template-seo/SKILL.md
@@ -0,0 +1,171 @@
+---
+name: flatrender-template-seo
+description: >-
+  Classifies and merchandises a FlatRender video template when an admin or developer creates or
+  publishes it. Decides the single primary category, the faceted tags, the SEO title/description/
+  keywords/slug, the Persian-first presentation copy, and the related-templates set — every choice
+  driven by the template's actual design, editable content, and usability. Use whenever creating,
+  editing, publishing, or seeding a template (project_container) and you must fill category_ids,
+  tag_ids, keywords, slug, description, news_text, or write its catalog/detail copy. Persian (fa) is
+  the source of truth; English (en) mirrors it 1:1.
+---
+
+# FlatRender Template SEO & Taxonomy
+
+Decide a template's category, tags, SEO, presentation copy, and related set — grounded in what the
+template *actually is*, not what you wish it ranked for. **fa is canonical; en mirrors it.**
+
+## When to use
+- An admin creates/edits a template in `TemplatesAdmin.tsx`, or you set fields on `content.project_containers`.
+- You run/extend `scripts/seed_remotion_templates.py` (which currently leaves SEO + taxonomy EMPTY — see below).
+- You publish (`is_published = true`) and need the template to be findable and well-presented.
+
+Cross-reference: `remotion-template-catalog` (template TYPE → pattern), `remotion-template-composition`
+(what's editable, used to write "what you can customize"), `persian-fonts` (RTL copy & Persian numerals).
+
+## The real data model (use these exact names — do not invent fields)
+
+Template = `content.project_containers`. Admin sets via `TemplatesAdmin.tsx` → `POST/PUT /v1/templates`
+(`Create/UpdateContainerRequest`). Settable, SEO/taxonomy-relevant fields:
+
+| Purpose | Admin label | form key | DTO | DB column |
+|---|---|---|---|---|
+| Name (→ H1) | نام | `name` | `Name` | `name` |
+| Slug | اسلاگ | `slug` | `Slug` | `slug` (CITEXT UNIQUE) |
+| Description / presentation copy | توضیحات | `description` | `Description` | `description` |
+| Keywords (opaque free text) | کلمات کلیدی (سئو) | `keywords` | `Keywords` | `keywords` (TEXT) |
+| Announcement (NOT seo) | متن خبر | `news_text` | `NewsText` | `news_text` |
+| Categories (M2M) | دسته‌بندی‌ها | `category_ids[]` | `CategoryIds` | `container_categories` |
+| Tags (M2M) | برچسب‌ها | `tag_ids[]` | `TagIds` | `container_tags` |
+| Primary mode | حالت اصلی | `primary_mode` | `PrimaryMode` | `primary_mode` enum |
+
+**Hard constraints from the platform (work within these):**
+- **No `meta_title` / `meta_description` on a template.** The only SEO string on a container is `keywords`.
+  Per-page `meta_title`/`meta_description`/`meta_keywords`/`bot_follow` exist ONLY on `content.categories`
+  (and on `blogs`). Workaround: put the page's discoverable meta intent into `keywords`; pack the human
+  title/description into `name` + `description`; lift the rest of the meta from the **assigned category's**
+  `meta_*` fields (so choose the category deliberately — its SEO is inherited).
+- **The public detail page emits title-only metadata** (`templates/[id]/page.tsx` → `{ title: "${name} — FlatRender" }`),
+  and the public mapper (`admin-api.ts` `containerToAdminProject`) DROPS `keywords`, `coverImageUrl`→OG, and
+  hardcodes `categoryName: undefined`. So today your `keywords`/category never reach the public `<head>`.
+  Still fill them: they power the backend list filters and are the fix-point when the frontend SEO gap is closed.
+  When you can, also fix the mapper to surface `keywords` + cover OG; otherwise flag it.
+- **No related-templates table/column/endpoint exists.** "Related" is computed by re-querying
+  `GET /v1/templates?categoryId={guid}` or `?tagSlug={slug}` and excluding the current template.
+  There is no precomputed set — pick the category/tags such that this query returns good neighbors.
+- **Tags are not shown anywhere in the templates UI** today, and the list page ignores the real DB
+  categories: the sidebar is ~12 hardcoded buckets (11 real categories + `"all"`), and because the
+  public mapper hardcodes `categoryName: undefined`, every template defaults to `"social"`. Tags/categories
+  still matter for the backend filters and future UI — set them correctly regardless.
+- `demo_script_tag` exists in DB + DTO but is NOT in the admin form — you cannot set it there.
+- Categories are a tree (`parent_id`); `GET /v1/categories` only eager-loads one child level. Keep the
+  primary set flat (8–12). Tags have `applies_to_mode`; categories do not.
+
+## Step-by-step decision process
+
+Run this for every template, in order. Each step feeds the next.
+
+**0. Read the design + content + usability.** What does it output (format)? What's editable (text/colors/
+logo/images/music — from `remotion-template-composition`)? Who hires it and when? 2D or 3D (real Remotion
+build: SVG vs `@remotion/three`)? Which aspects exist (16:9 / 1:1 / 9:16 child projects)?
+
+**1. Category — pick exactly ONE primary.** Category = the *output format*, never the occasion/industry.
+Test: which single shelf would a user expect this on? If the answer is a format (logo reveal, story, slideshow)
+it's the category; if it's when/why/who (Nowruz, real estate, teens) that's a TAG. Use the flat set:
+اینترو و لوگو / Intro & Logo · استوری و ریلز / Story & Reels · پست شبکه اجتماعی / Social Post ·
+تبلیغ و پروموشن / Promo & Ad · اسلایدشو / Slideshow · معرفی محصول / Product Showcase ·
+دعوت‌نامه و مناسبت / Invitation & Event · تیتراژ و زیرنویس / Titles & Lower-thirds ·
+ارائه و اینفوگرافیک / Presentation & Infographic · یوتیوب و اینترو کانال / YouTube & Channel.
+No "Other"; no category with <5 templates. → set `category_ids` (the primary first; its `sort` = index 0).
+
+**2. Tags — 6–12, from a controlled fa↔en vocabulary**, each TRUE of this design, across facets:
+use-case · occasion · industry · style/aesthetic · aspect ratio · color/mood · 2D-3D · audience.
+Empty facets are fine — don't invent tags. Aspect ratio is a TAG (one template, three outputs), never a
+separate catalog entry. Tag 3D only if it really renders 3D. Reuse existing `content.tags` (match by
+`slug`/`latin_name`); create a new tag only as a deliberate dictionary edit. → set `tag_ids`.
+
+**3. SEO title / description / keywords / slug.**
+- **Title** (lives in `name`): `{Template Name} | {Category} {use/occasion}`. Keep the keyword in the
+  first ~30 chars (Persian runs long); brand is appended by the layout, don't double it.
+- **Description** (lives in `description`, also reused as presentation copy): benefit + what + how-to-edit +
+  soft CTA. fa 120–155 / en 120–158 chars. One natural keyword, no stuffing.
+- **Keywords** (lives in `keywords`): how Iranians actually search — «قالب آماده», «ساخت/دانلود استوری»,
+  «تیزر تبلیغاتی», «اینترو لوگو» — include loanword + Persian spelling both ways (استوری/Story, اینترو/Intro).
+  1 primary + 2–3 secondaries. Note: `keywords` is an opaque free-text column — the platform does NOT
+  tokenize, split, index, or search on it (no comma parsing anywhere in form or backend). Commas are
+  purely an authoring convention for human readability; write it however reads cleanest.
+- **Slug** (`slug`): the slugifier KEEPS Persian (no transliteration). Prefer a curated **latin/transliterated**
+  keyword slug for shareable URLs (Persian slugs become `%D9%82...` when copied). Lowercase, hyphenated, short,
+  keyword-bearing. Never change a published slug.
+
+**4. Presentation copy** (write into `description`; structure it so it doubles as SEO + usability):
+H1 = human Persian `name` → one-line benefit hook → "این قالب برای چیست؟" (use-case+occasion+audience) →
+"چه چیزهایی قابل تغییر است؟" (bullet the REAL editable fields — don't claim editable music if there's none) →
+"چطور بسازم؟" (انتخاب → ویرایش متن/رنگ → دانلود) → spec strip (aspects, duration, 2D/3D). Benefit before
+feature; second person; every claim true of THIS template.
+
+**5. Related set** (caller-computed; pick category/tags so this works). Query
+`GET /v1/templates?categoryId=...` then `?tagSlug=...`; rank occasion > category+use-case > style > industry;
+show 6–8; **exclude this template's own aspect siblings** (dedupe by template id); cap same-style clones;
+label pack-mates «از همین مجموعه».
+
+## fa / en parity & RTL rules
+- Fill fa first, then en as a faithful mirror. Two self-consistent pages — never a Persian page with an
+  English title. Same template id; localized labels resolve per current locale.
+- Persian uses Vazirmatn / RTL (see `persian-fonts`); use Persian digits in user-facing copy; don't fight the
+  `[dir="rtl"]` block. Tag/category *slugs* stay latin for stability; *display names* are localized.
+- hreflang fa↔en + x-default is the right target even though the detail page doesn't emit it yet — flag the gap.
+
+## Worked examples
+
+**A. Nowruz 3D greeting (تبریک نوروز سه‌بعدی)**
+- Category: `دعوت‌نامه و مناسبت / Invitation & Event`.
+- Tags: occasion=نوروز/Nowruz · use-case=تبریک/greeting · style=لاکچری/luxury · 2D-3D=سه‌بعدی/3D ·
+  aspect=۹:۱۶,۱:۱,۱۶:۹ · color=طلایی/gold · audience=کسب‌وکار کوچک/small business.
+- name (fa): «قالب تبریک نوروز سه‌بعدی | مناسبت و تبریک»  · (en): "Nowruz 3D Greeting Template | Invitation & Event"
+- description (fa): «کارت تبریک نوروزی سه‌بعدی و لاکچری؛ نام برند، متن تبریک و رنگ طلایی را در چند دقیقه شخصی‌سازی کن و ویدیوی آماده انتشار بساز.»
+- keywords: `قالب تبریک نوروز, تبریک عید, نوروز سه بعدی, دانلود کارت تبریک, Nowruz greeting`
+- slug: `nowruz-3d-greeting` · Related: other نوروز items first, then Invitation & Event + greeting.
+
+**B. Instagram sale promo (پروموشن فروش ویژه اینستاگرام)**
+- Category: `استوری و ریلز / Story & Reels` (output is a 9:16 vertical — format wins over "sale").
+- Tags: use-case=فروش ویژه/flash sale · industry=فروشگاه آنلاین/e-shop · style=نئون/neon · aspect=عمودی ۹:۱۶/vertical ·
+  color=انرژیک/energetic · audience=فروشگاه/store · 2D.
+- name (fa): «قالب استوری فروش ویژه | استوری و ریلز» · (en): "Flash-Sale Story Template | Story & Reels"
+- description (fa): «قالب آماده استوری برای اعلام تخفیف و فروش ویژه؛ متن، قیمت، رنگ و لوگوی فروشگاهت را جایگزین کن و استوری حرفه‌ای ۹:۱۶ بساز.»
+- keywords: `قالب استوری فروش, تخفیف اینستاگرام, ساخت استوری تبلیغاتی, دانلود قالب استوری, flash sale reels`
+- slug: `instagram-flash-sale-story` · Related: same use-case (flash sale) across categories, then Story & Reels.
+
+**C. Corporate logo reveal (لوگو موشن شرکتی)**
+- Category: `اینترو و لوگو / Intro & Logo`.
+- Tags: use-case=معرفی برند/brand intro · style=مینیمال/minimal · audience=شرکتی/corporate ·
+  aspect=۱۶:۹,۱:۱,۹:۱۶ · color=آبی/blue · 2D (or 3D only if it truly is).
+- name (fa): «قالب لوگو موشن شرکتی | اینترو و لوگو» · (en): "Corporate Logo Reveal Template | Intro & Logo"
+- description (fa): «اینترو حرفه‌ای برای نمایش لوگوی شرکت؛ لوگو، نام برند و رنگ سازمانی را وارد کن و یک اینترو تمیز و مینیمال بساز.»
+- keywords: `لوگو موشن, اینترو لوگو, ساخت اینترو, لوگو موشن شرکتی, logo motion intro`
+- slug: `corporate-logo-reveal` · Related: other Intro & Logo + brand-intro use-case.
+
+## Where each value goes
+- **Admin UI** (`TemplatesAdmin.tsx`): name→`name`, slug→`slug`, presentation copy→`description`,
+  SEO keywords→`keywords`, categories→`category_ids` (multi-select chips), tags→`tag_ids`, mode→`primary_mode`.
+  Saves via `/api/admin/resource/templates` → `/v1/templates`.
+- **Categories/Tags** are managed on their own admin pages (`admin-resources.tsx` → `/v1/categories`, `/v1/tags`);
+  category-level `meta_title`/`meta_description`/`meta_keywords`/`bot_follow` live there — set them once per category.
+- **Seeder** (`scripts/seed_remotion_templates.py`): currently SETS only `name/slug/description/image/demo*/
+  is_published/primary_mode/sort` and inserts ZERO `container_categories` / `container_tags` and NO `keywords`.
+  To seed SEO+taxonomy: add `keywords` to the `project_containers` INSERT, and add INSERTs into
+  `content.container_categories` (with `sort` = index) and `content.container_tags`. Otherwise each seeded
+  template ships with no keywords, no category, no tags — invisible to backend category/tag filters until an
+  admin opens it and assigns them.
+
+## Final checklist
+- [ ] Exactly ONE primary category, format-based, from the flat set → `category_ids` (primary at index 0).
+- [ ] 6–12 tags, controlled fa↔en vocab, each true of the design, across facets; aspect is a tag → `tag_ids`.
+- [ ] `name` carries the SEO title (keyword in first ~30 chars; no doubled brand).
+- [ ] `description` = benefit→for-what→customize(real fields)→how-to→specs; doubles as the meta description.
+- [ ] `keywords` = 1 primary + 2–3 secondary, loanword + Persian spelling (free text — commas are just an authoring convention, not parsed).
+- [ ] `slug` = curated latin keyword slug, stable, never changed after publish.
+- [ ] fa filled first, en a 1:1 mirror; Persian digits + RTL in copy.
+- [ ] Related works via category/tag query; own aspect siblings excluded.
+- [ ] Gaps flagged: no template `meta_*`, public mapper drops `keywords`/cover OG/category, no related table,
+      no hreflang on detail page — note these where relevant rather than pretending they're set.
diff --git a/persian-fonts/SKILL.md b/persian-fonts/SKILL.md
new file mode 100644
index 0000000..98511c0
--- /dev/null
+++ b/persian-fonts/SKILL.md
@@ -0,0 +1,55 @@
+---
+name: persian-fonts
+description: Persian (Farsi) and Latin font selection for FlatRender — which font to use where, with a Persian-first priority. Use when choosing typefaces for a template or UI, pairing display vs body fonts, handling RTL/Persian numerals, or adding a new font to the Remotion project. Persian fonts are the priority.
+---
+
+# Persian-first typography
+
+This is an Iran-facing product: **Persian (Farsi) is the default and the priority**. Latin is secondary. Get the Persian type right first.
+
+## What the project already uses
+- **Vazirmatn** — the default Persian face everywhere. Remotion bundles `services/remotion/public/fonts/vazirmatn-{400,600,700,800,900}.woff2` and exposes `FONT` from `src/lib/fonts.ts` (use `fontFamily: FONT` + `direction: "rtl"` in every composition).
+- Web app: `globals.css` has a `[dir="rtl"]` block that FORCES Vazirmatn on all elements — don't fight it with utility classes; work with it.
+- Latin pairing in the web app: **Plus Jakarta Sans** + **Inter**.
+
+## Persian font palette (pick by role)
+| Font | Character | Use for |
+|---|---|---|
+| **Vazirmatn** | clean, neutral, many weights | DEFAULT — body, UI, most template text |
+| **Estedad** | modern, geometric, friendly | headings, modern brand templates |
+| **Yekan Bakh** | contemporary sans, professional | corporate/business templates |
+| **Shabnam / Sahel** | soft, readable | body text, calm/elegant designs |
+| **IRANSans / IRANYekan** | familiar Iranian UI standard | UI-style promos, app mockups |
+| **Morabba** | bold display, rounded | big punchy headlines, posters |
+| **Gandom** | strong display | impactful titles, sale/sport |
+| **Lalezar** | playful, heavy, fun | kids, party, birthday, casual |
+| **Shekari / Vahid** | decorative/calligraphic | festive, traditional (Nowruz, wedding, Yalda) |
+| **Nastaliq (e.g. IranNastaliq)** | classical calligraphy | very formal/traditional, invitations — use sparingly, hard to read small |
+
+Pairing rule: one display face for the headline + Vazirmatn (or Shabnam) for everything else. Don't mix two display faces.
+
+## Match font to template mood
+- Corporate / SaaS → Estedad / Yekan Bakh + Vazirmatn.
+- Festive (birthday, party) → Lalezar / Morabba + Vazirmatn.
+- Traditional / occasion (Nowruz, wedding, Yalda, Eid) → a decorative/Nastaliq display for the greeting + Vazirmatn for details.
+- Sale / bold promo → Gandom / Morabba (heavy) + Vazirmatn.
+- Minimal / elegant → Shabnam / Sahel, lighter weights.
+
+## Persian typesetting rules
+- **RTL:** always `direction: "rtl"`; align right or center. Mixed Persian+Latin/numbers needs care (bidi) — test the actual string.
+- **Numerals:** decide Persian (۱۲۳) vs Latin (123) and be consistent. For Persian digits, format with `toLocaleString('fa-IR')` or use a font that supports Persian numerals. Years/prices in templates are usually Persian digits (۱۴۰۶, ۲۹۹٬۰۰۰).
+- **Weights:** Persian script needs a bit more weight to feel solid — headings 700-900, body 400-600. Avoid ultra-thin for small text.
+- **Line-height:** Persian needs slightly more (`lineHeight` 1.4-1.6 for body) — descenders/diacritics need room.
+- **ZWNJ (نیم‌فاصله, `‌`):** preserve it in words like «می‌شود», «نیم‌فاصله» — don't strip it.
+- **No fake bold/italic:** use real weights; Persian has no italic — don't slant it.
+
+## Adding a new font to a Remotion template
+1. Get the woff2 (license-checked — Vazirmatn/Estedad/Shabnam are SIL OFL, free for commercial; verify others). Place in `services/remotion/public/fonts/`.
+2. Register it (a `@font-face` injected via `<style>` in the composition, or `@remotion/fonts` `loadFont`) and expose a `FONT_X` const next to `FONT` in `lib/fonts.ts`.
+3. Use `fontFamily: FONT_X` only for that template's display text; keep body on Vazirmatn.
+4. Embed the actual weights you use (don't ship 9 weights if you use 2) to keep bundles small.
+
+## Licensing
+Prefer SIL OFL / free-for-commercial Persian fonts (Vazirmatn, Estedad, Shabnam, Sahel, Samim, Gandom, Morabba — most from the `font-store`/Google Persian sets are OFL). Verify each before shipping in an exported-video product; keep a license record.
+
+Related: `remotion-template-composition`, `remotion-design-styles`.
diff --git a/remotion-aspect-ratios/SKILL.md b/remotion-aspect-ratios/SKILL.md
new file mode 100644
index 0000000..8d236e0
--- /dev/null
+++ b/remotion-aspect-ratios/SKILL.md
@@ -0,0 +1,91 @@
+---
+name: remotion-aspect-ratios
+description: How to design ONE Remotion template that genuinely fits all three FlatRender aspects — 16:9, 1:1, 9:16 — without text cropping, off-screen elements, or a layout that is really just the 16:9 version letterboxed. Use whenever building or reviewing a template's layout. Read this BEFORE positioning any text or element.
+---
+
+# Designing for 16:9 / 1:1 / 9:16 (do this right)
+
+Every template registers in all three aspects (`ASPECTS` in `src/lib/aspect.ts`). A common mistake (made in early FlatRender templates) is to design for 16:9 and just let the same coordinates render in 9:16 — which **crops text, pushes elements off-screen, and looks broken**. A template must be *re-laid-out* per aspect, not scaled.
+
+## Two strategies — responsive component OR per-aspect components
+There are TWO legitimate ways to support the three aspects; pick per template:
+
+1. **One responsive component** (default) — a single composition that adapts via `useLayout()` (`isWide/isSquare/isTall`, `pick()`). Use when the design is fundamentally the same and only positions/sizes change. Less code, stays in sync.
+
+2. **A dedicated component per aspect** — when the design must differ STRUCTURALLY (different layout, different scene, different element set), not just reposition. e.g. a cinematic wide hero vs a stacked vertical story vs a centered square badge can be genuinely different scenes.
+
+The registry supports both. In `services/remotion/src/templates.tsx` a `TemplateDef` has `component` (shared default) plus an optional `componentsByAspect` map keyed by aspect id:
+```tsx
+{
+  id: "MyTemplate",
+  component: MyTemplateWide,            // fallback for any aspect not overridden
+  componentsByAspect: {
+    "1x1":  MyTemplateSquare,           // dedicated square design
+    "9x16": MyTemplateTall,             // dedicated vertical design
+  },
+  schema, durationSec, defaultProps,    // SHARED across aspects — keep the editable
+}                                       //   fields, props and duration identical
+```
+`Root.tsx` picks `componentsByAspect[aspectId] ?? component`. **Keep `schema`, `defaultProps`, and `durationSec` shared** so the studio shows the same editable fields and the same composition ids (`${id}-${aspect}`) regardless — only the visual layout differs. Reuse shared sub-components (background, characters, text overlay) across the per-aspect files so they don't drift.
+
+Guideline: start with one responsive component; split into per-aspect components only when responsive branching gets gnarly or the designs truly diverge. Don't duplicate three files when `pick()` would do.
+
+## Why the naive approach breaks
+`useLayout().vmin(n)` sizes off the SHORT side (1080 in all three aspects), so a `vmin(92)` font is the same pixel size everywhere. But the WIDTH differs hugely: **1920px (16:9) vs 1080px (9:16)**. A headline that fits 1920 wide overflows/crops at 1080 wide. Likewise positioning at `width*0.34` puts an element in a totally different place relative to its own size when width changes.
+
+## The rules
+
+1. **Design 9:16 (tall) first.** It's the tightest. If it fits there, widening to 1:1 and 16:9 is easy. Building 16:9-first guarantees the tall version breaks.
+
+2. **Branch layout on `L.isWide / L.isSquare / L.isTall`** — don't just scale. Things that sit side-by-side in 16:9 should STACK vertically in 9:16:
+   ```tsx
+   const L = useLayout();
+   // hero element position differs per aspect
+   const heroX = L.isTall ? L.width * 0.5 : L.width * 0.34;   // centered in tall, left in wide
+   // layout direction
+   flexDirection: L.isTall ? "column" : "row"
+   ```
+   Add a tiny helper to `aspect.ts` and use it everywhere:
+   ```ts
+   pick: <T,>(wide: T, square: T, tall: T): T =>
+     kind === "wide" ? wide : kind === "tall" ? tall : square,
+   ```
+   Then: `fontSize: L.pick(L.vmin(92), L.vmin(84), L.vmin(72))`.
+
+3. **Cap font size to the WIDTH, not just the short side.** Headlines must wrap, never crop. Always set `maxWidth` and let text wrap:
+   ```tsx
+   maxWidth: L.width * 0.86, // safe text column
+   // and scale type DOWN in tall:
+   fontSize: L.pick(L.vmin(90), L.vmin(80), L.vmin(64)),
+   wordBreak: "normal", lineHeight: 1.15,
+   ```
+   Test with the LONGEST realistic Persian string for that field, not the short default.
+
+4. **Respect SAFE ZONES.** Keep all meaningful content inside the central safe area; give tall more vertical margin:
+   - 16:9: ~5% horizontal / 8% vertical padding.
+   - 9:16: ~8% horizontal, and keep the hero in the middle 60% vertically (top/bottom of phones get UI chrome).
+   Anchor text blocks to a zone (top third / bottom third), put the hero visual in the center.
+
+5. **Reposition the hero per aspect.** A character/object that's at `x=34%` and text on the right in 16:9 should become hero-centered with text above/below in 1:1 and 9:16. Use `pick()` for x/y and for `justifyContent`/`alignItems`.
+
+6. **Scale element COUNT/spread, not just size.** A row of 5 floating shapes that spans 1920 looks sparse/clipped at 1080 — reduce spread radius or count in tall (`L.pick(...)`).
+
+7. **3D:** adjust `camera.fov` / `position.z` per aspect so the subject fills the frame (a tall frame needs the camera pulled back or a narrower fov). Keep the 2D text overlay using the same `pick()` rules.
+
+## Mandatory verification (the step that was skipped before)
+Render a still in **all three aspects** at a frame where text is visible, with a LONG test string, and LOOK at each:
+```
+npx remotion still src/index.ts "<Comp>-16x9" out/_a.png --frame=NN
+npx remotion still src/index.ts "<Comp>-1x1"  out/_b.png --frame=NN
+npx remotion still src/index.ts "<Comp>-9x16" out/_c.png --frame=NN
+```
+Reject if: text is clipped at any edge, an element is off-frame, the hero is tiny/huge, or the tall version is obviously "the wide one squished".
+
+## Checklist
+- [ ] Designed tall-first; used `pick()`/`isTall` to branch layout (not just scale).
+- [ ] Headlines wrap with `maxWidth`; tested with long Persian text — no cropping.
+- [ ] Hero repositioned/centered per aspect; content in safe zones.
+- [ ] Spread/count adjusted for narrow frames; 3D fov/camera tuned per aspect.
+- [ ] Eyeballed stills in ALL THREE aspects.
+
+Related: `remotion-template-composition`, `remotion-design-styles`.
diff --git a/remotion-character-design/SKILL.md b/remotion-character-design/SKILL.md
new file mode 100644
index 0000000..5545ad3
--- /dev/null
+++ b/remotion-character-design/SKILL.md
@@ -0,0 +1,51 @@
+---
+name: remotion-character-design
+description: How to build and animate 2D (SVG) and 3D (@remotion/three) characters and mascots for FlatRender Remotion templates. Use when a template needs a character — a mascot, Haji Firuz, animals (goldfish, butterflies), people, or any articulated figure. Covers construction from primitives, rigging via grouped transforms, animation cycles (walk/dance/idle), facial expression, and the 2D-vs-3D / GLTF trade-offs.
+---
+
+# Character design for Remotion
+
+We have NO rigged 3D model assets and the asset CDNs are geo-blocked, so characters are built from **primitives** — SVG shapes (2D) or Three.js geometries (3D) — and animated off `useCurrentFrame()`. Reference implementations: `NowruzGreeting.tsx` (2D Haji Firuz, goldfish, butterflies) and `Nowruz3D.tsx` (3D scene).
+
+## Core principle: build in parts, rig with groups
+A character = a tree of grouped parts, each animated by transforming its group around a PIVOT.
+- 2D: nested `<g transform="translate/rotate/scale">`. Put the pivot at the joint (e.g. shoulder) by translating the group there, drawing the limb from origin, and rotating the group.
+- 3D: nested `<group position rotation>`. Same idea — position the group at the joint, model the limb from there, rotate the group.
+
+## 2D characters (SVG)
+Construction kit:
+- Head = `<circle>`; body = `<path>` trapezoid (`M.. Q..`); limbs = `<rect rx>` (rounded) or `<path>`; hands/feet = small ellipses; hat = `<path>` triangle/cone.
+- Face (friendly/stylized): two dot eyes, a `Q` curve smile, rosy `circle` cheeks at low opacity. Keep it simple — over-detailing reads worse, not better.
+- Skin/clothing: flat fills + one darker shade for a soft AO at edges (`fillOpacity` overlay).
+
+Animating cycles (all from `frame`):
+- **Idle/breathe:** body `scale.y = 1 + 0.02*sin(frame/30)`.
+- **Dance/bounce:** whole body `translateY = -abs(sin(frame/7))*H`, plus a small `rotate(sin(frame/7)*4)` sway; legs counter-rotate.
+- **Limb swing:** `rotate(amp*sin(frame/period))` around the joint pivot.
+- **Hop-in entrance:** `spring()` from off-frame X to the target, then switch to the idle/dance loop.
+- **Prop shake (tambourine, flag):** `rotate(sin(frame/3.2)*18)` + sparkle accents on peaks.
+
+## 3D characters (primitives)
+Build the figure from: `sphereGeometry` (head/joints), `cylinderGeometry`/`capsule` (limbs/torso), `coneGeometry` (hat/skirt), `RoundedBox` (blocky bodies), `torusGeometry` (rings/mouth). Group per limb for articulation. Material: `meshStandardMaterial` (roughness ~0.5 for cloth, lower for shiny). Light with `three-kit` StudioLights; add a soft contact shadow (a dark blurred plane or `shadows` + a floor).
+- 3D animation is the SAME math (rotate/translate groups by `frame`), just in 3D space and you can also move the camera/scene for parallax.
+- Faces in 3D are hard — keep them simple (sphere eyes, a small torus/curve mouth) or face the character slightly away.
+
+## Animation principles (what makes it not look stiff)
+- **Anticipation:** dip before a jump, wind-up before a throw.
+- **Squash & stretch:** scale on impacts/landings (subtle: ±8%).
+- **Overlap / secondary motion:** hat ball, scarf, string, ears, tambourine lag behind the body — offset their phase.
+- **Easing:** `Easing.out(Easing.cubic)` for arrivals, `spring()` for bouncy pops, never linear for organic motion.
+- **Hold:** let a pose read for a beat before the next move.
+
+## Cultural / brand-safety notes
+- Default to a **modern stylized** look (friendly, non-realistic) unless the user asks otherwise. Specifically for Haji Firuz: red costume + conical hat + tambourine, but a friendly non-blackface face (avoids the blackface connotation).
+- Confirm a storyboard with the user BEFORE building complex characters (the project convention) — list the cast, the beats, and the look.
+
+## When NOT to hand-build
+- Photoreal humans or complex rigged motion → out of scope without GLTF assets; propose a stylized take or a non-character design instead.
+- If a GLTF model IS provided, load with drei `useGLTF` and animate transforms by `frame` (no `useFrame`).
+
+## Workflow
+Storyboard → build parts → rig groups → animate cycles → **render stills at 3-4 beats and LOOK** → refine → render all 3 aspects (see `remotion-aspect-ratios` — characters must sit in the safe zone in 9:16 too).
+
+Related: `remotion-design-styles`, `remotion-aspect-ratios`, `remotion-template-catalog`.
diff --git a/remotion-design-styles/SKILL.md b/remotion-design-styles/SKILL.md
new file mode 100644
index 0000000..5be288c
--- /dev/null
+++ b/remotion-design-styles/SKILL.md
@@ -0,0 +1,49 @@
+---
+name: remotion-design-styles
+description: Visual art-direction reference for building FlatRender video templates with Remotion (2D) and Three.js/@remotion/three (3D). Use when starting a new template, picking an art style, designing color palettes, or designing objects/scenes. Covers flat, gradient/mesh, glassmorphism, neon, 3D/cinematic, paper-cut, isometric, luxury looks plus color theory, lighting, and material design.
+---
+
+# Remotion design styles (2D + 3D)
+
+Project location: `services/remotion/`. Shared helpers: `src/lib/anim.ts` (hexToRgba, mixHex, rand), `src/lib/branding.ts` (colorSchema + BRAND), `src/lib/aspect.ts` (useLayout), `src/lib/three-kit.tsx` (3D studio kit). Animate everything off `useCurrentFrame()` — never `Math.random()`/`Date.now()` (breaks determinism; use `rand(i)`), and in 3D never use R3F's `useFrame` (use `useCurrentFrame`).
+
+## Pick a style first, then build
+Each template should commit to ONE art style — mixing reads as "basic". Catalog:
+
+| Style | Look | How (Remotion) | Best for |
+|---|---|---|---|
+| Flat / minimal | solid fills, generous whitespace, 1-2 accents | SVG shapes, simple springs | corporate, clean promos |
+| Gradient / mesh | soft drifting color blobs | blurred radial-gradient divs animated by frame (see GradientPromo) | modern SaaS, backgrounds |
+| Glassmorphism | frosted translucent cards | `backdrop-filter: blur`, rgba fills, thin borders | UI/app promos |
+| Neon / glow | dark bg + luminous strokes | `drop-shadow`/`textShadow` glows, emissive in 3D | gaming, nightlife, tech |
+| 3D / cinematic | real depth, reflections, bokeh | @remotion/three + three-kit (lighting, MeshReflectorMaterial, bloom/DOF) | premium logo/product reveals |
+| Paper-cut / layered | stacked shapes with soft shadows | layered SVG + offset box-shadows | storytelling, kids, greetings |
+| Isometric | 2.5D objects on a grid | SVG with skew/`rotateX` CSS, or true 3D ortho camera | explainer, product, city scenes |
+| Luxury / gold | dark + metallic gold + serif | gold gradients, shine sweeps, slow easing | weddings, premium brands |
+
+## 2D vs 3D — choose deliberately
+- **2D (SVG/CSS):** fast to render, crisp text, full control, no WebGL. Use for flat/gradient/glass/neon/character scenes, anything text-heavy.
+- **3D (@remotion/three):** depth, real lighting/reflections, bokeh, camera moves. Use for premium logo/product/abstract reveals. Costs render time. Setup is already done: R3F v9 + `Config.setChromiumOpenGlRenderer("angle")`. Reuse `three-kit.tsx` (StudioEnv, StudioLights, StudioFloor, StudioEffects, Confetti3D). Keep crisp Persian text as a 2D `<AbsoluteFill>` overlay ON TOP of `<ThreeCanvas>` — don't render Persian text in 3D.
+
+## Color design
+- Drive every colorable element from the `colorSchema` props (accent / secondary / background / text) so the studio can recolor it — see `remotion-svg-colors`.
+- Build depth with VALUE, not just hue: dark bg → mid elements → bright accents/highlights. Add glow (`hexToRgba(accent, .6)` shadows) and a vignette (`inset 0 0 600px rgba(0,0,0,.6)`).
+- Gradients: 2-3 stops max; blend related hues (`mixHex(a,b,.5)`). Mesh look = several large blurred radial-gradient circles drifting on `sin(frame/…)`.
+- Contrast: text needs ≥ 4.5:1 over its backdrop — add a scrim/shadow when over busy/3D scenes.
+- Default palettes per mood: tech = blue→violet on near-black; festive = warm gold/red/green on cream or turquoise; luxury = gold on charcoal; fresh = teal/green on light.
+
+## Object design
+- **2D:** compose from primitives — `<circle>`, `<rect rx>`, `<path>` (quadratic `Q` for organic curves). Reuse `rand(i)` for deterministic scatter (particles, confetti, petals). Add glow via SVG `filter: drop-shadow`.
+- **3D:** primitives + good material = premium. `meshStandardMaterial` with `metalness` 0.3-0.7, `roughness` 0.15-0.35, `flatShading` for faceted gems, `emissive`+`emissiveIntensity` for glow that bloom picks up (set `toneMapped={false}` on flames/glows). Light with 3-point + colored rims (StudioLights). Faceted icosahedron/octahedron/dodecahedron read as "gems"; RoundedBox for gifts/cards.
+
+## Motion = polish
+Stagger entrances (don't reveal everything at once), use `spring()` for pops and `interpolate(..., Easing.out(Easing.cubic))` for slides, add secondary motion (breathe, drift, twinkle), and a subtle continuous camera/scene sway in 3D. Hold the final frame ~1s for readability.
+
+## Quality checklist
+- One coherent style; depth via value + glow + vignette.
+- All colors come from props (recolorable).
+- Staggered, eased motion with secondary detail.
+- Renders deterministically (no random/date).
+- Verify visually: render stills at 3-4 key frames and LOOK before shipping.
+
+Related: `remotion-character-design`, `remotion-aspect-ratios`, `remotion-template-composition`, `remotion-svg-colors`.
diff --git a/remotion-music-picker/SKILL.md b/remotion-music-picker/SKILL.md
new file mode 100644
index 0000000..3fd2770
--- /dev/null
+++ b/remotion-music-picker/SKILL.md
@@ -0,0 +1,59 @@
+---
+name: remotion-music-picker
+description: How to choose royalty-free background music for a FlatRender template and sync the animation to its beat/vibe. Use when picking a music bed for a template, matching mood and BPM to the visuals, syncing reveals to the beat, or sourcing free/royalty-free tracks.
+---
+
+# Music picker for templates
+
+> Status: templates currently ship without a music bed. This is the playbook for adding one. The right track + beat-synced motion is what makes a template feel "produced".
+
+## Match music to the template's job
+| Template vibe | Genre / mood | Typical BPM |
+|---|---|---|
+| Corporate / SaaS logo | clean inspirational, soft piano + synth pluck | 90-110 |
+| Energetic promo / sale | upbeat pop, four-on-the-floor, claps | 120-130 |
+| Social / Insta / trendy | lo-fi or modern pop, punchy | 100-120 |
+| Epic / product reveal | cinematic build, big drum, riser | 70-90 build → hit |
+| Festive (birthday, Nowruz, party) | happy ukulele/marimba, bells | 110-128 |
+| Emotional (wedding, tribute) | warm piano/strings | 60-80 |
+| Tech / gaming | electronic, arpeggios, bass | 120-140 |
+| Luxury | downtempo, jazzy, smooth | 80-100 |
+| Minimal / explainer | light marimba/plucks, unobtrusive | 95-115 |
+
+## Sync the animation to the beat (this is the magic)
+1. Know the track's BPM → frames per beat = `fps * 60 / bpm` (e.g. 30fps, 120bpm → 15 frames/beat).
+2. Land your hero reveals, pops, and cuts ON beats (multiples of frames-per-beat). Stagger small element pops on 1/2 or 1/4 beats.
+3. Put the BIG reveal on a musical downbeat or right after a riser/drop.
+4. For a known track, hardcode beat frames; for generic use, expose `bpm` as a prop and compute beat frames so motion stays in sync if the track changes.
+```tsx
+const FPS = 30, BPM = 120;
+const beat = (FPS * 60) / BPM;            // frames per beat
+const onBeat = (n: number) => Math.round(n * beat);
+// reveal hero on beat 4, CTA on beat 8
+```
+
+## Remotion wiring
+```tsx
+import { Audio, staticFile, interpolate, useCurrentFrame, useVideoConfig } from "remotion";
+const { durationInFrames } = useVideoConfig();
+const f = useCurrentFrame();
+<Audio src={staticFile("music/upbeat-120.mp3")}
+  volume={(ff)=>interpolate(ff,[0,15,durationInFrames-20,durationInFrames],[0,0.7,0.7,0])} />
+```
+- Fade IN over ~0.5s and OUT over the last ~0.7s — never start/end abruptly.
+- Trim/loop the track to the template length; cut on a bar boundary so the end feels intentional.
+- If there's a voiceover, DUCK the music (~-12 dB) under it.
+- Store beds in `services/remotion/public/music/`, named with BPM (`upbeat-120.mp3`).
+
+## Free / royalty-free sources (verify license per track)
+- **Uppbeat** (free tier, gives a clearance ID), **Pixabay Music** (CC0-ish), **Mixkit** (free for commercial), **Bensound** (free w/ attribution or licensed), **Free Music Archive** (per-track CC), **YouTube Audio Library** (downloadable, check terms), **Incompetech / Kevin MacLeod** (CC-BY).
+- ALWAYS check: commercial use allowed? attribution required? Keep a per-file license/attribution record. Prefer CC0 / royalty-free-with-commercial. Avoid anything Content-ID-flagged for a product that exports user videos.
+- For an Iran-facing product, also consider local royalty-free Persian/instrumental sources where licensing is clearer.
+
+## Workflow
+1. Pick vibe + BPM from the table for the template's purpose.
+2. Source 2-3 candidate tracks (license-checked), audition against the animation.
+3. Re-time the key reveals to the chosen BPM's beats.
+4. Add `<Audio>` with fades; render and LISTEN; nudge beats until reveals hit on the downbeat.
+
+Related: `remotion-sound-effects`, `remotion-template-catalog`.
diff --git a/remotion-sound-effects/SKILL.md b/remotion-sound-effects/SKILL.md
new file mode 100644
index 0000000..08d08ef
--- /dev/null
+++ b/remotion-sound-effects/SKILL.md
@@ -0,0 +1,56 @@
+---
+name: remotion-sound-effects
+description: Which sound effects (SFX) to use for FlatRender video templates and exactly where to place them in the timeline. Use when adding audio punch to a template — whooshes, impacts, sparkles, pops, risers, confetti — and syncing them to keyframes with Remotion's Audio component.
+---
+
+# Sound-effect design for templates
+
+> Status: current FlatRender templates have NO audio yet. This skill is the playbook for adding it. SFX dramatically raise perceived quality — a logo "thud" + sparkle makes a reveal feel pro.
+
+## How audio works in Remotion
+Use `<Audio>` from `remotion`, placed in the composition tree, timed to frames:
+```tsx
+import { Audio, useVideoConfig } from "remotion";
+// play a one-shot SFX starting at frame 55 (the logo-land beat)
+<Audio src={staticFile("sfx/impact.mp3")} startFrom={0} volume={0.8}
+       // mount it only around its moment using a <Sequence from={55}> wrapper
+/>
+```
+Patterns:
+- Wrap one-shots in `<Sequence from={FRAME}>` so they trigger at the right beat.
+- `volume` can be a function of frame for fades: `volume={(f)=>interpolate(f,[0,10],[0,1])}`.
+- Layer SFX over the music bed (see `remotion-music-picker`); keep SFX ~ -6 dB under dialogue, on top of music.
+- Put shared SFX in `services/remotion/public/sfx/` and load with `staticFile()`.
+
+## SFX → moment mapping (sync to the KEYFRAME, not vaguely)
+| Moment in the animation | SFX | Place at |
+|---|---|---|
+| Element/text flies in | **whoosh** (short, directional) | 2-3 frames BEFORE it lands |
+| Logo / hero lands | **impact / thud / boom** | the exact land frame (spring settle) |
+| Glitter / magic reveal | **sparkle / shimmer / chime** | over the particle gather (0.3-0.5s) |
+| Small element appears | **pop / tick / blip** | each appearance (stagger to match) |
+| Countdown ticking | **clock tick** per number, **ding/airhorn** on GO | each number frame |
+| Birthday / party | **party horn + confetti rustle**, soft **chime** | greeting reveal + confetti burst |
+| Sale / promo | **cash register "cha-ching" / coin**, **stamp** on the badge | badge pop |
+| Shine sweep across logo | **soft shimmer swell** | sweep start→end |
+| Transition between scenes | **whoosh + light riser** | on the cut |
+| Build-up before reveal | **riser / uplifter** (0.5-1.5s) | leading INTO the hero moment |
+
+## Placement principles
+- **Anticipation:** risers and whooshes START before the visual peak and resolve ON it. A whoosh that lands with the logo sells the motion.
+- **One hero hit:** the reveal gets ONE big impact — don't stack 3 booms; it muddies.
+- **Match the motion curve:** fast spring = sharp transient; slow ease = soft swell.
+- **Stagger to the visuals:** if 5 elements pop on different frames, 5 pops on those frames (vary pitch slightly so it's not robotic).
+- **Less is more:** 3-6 well-placed SFX per template beats a wall of sound. Leave silence for contrast.
+- **Loudness:** normalize SFX, peak ~ -3 dB, sit them under the music bed; the final mix shouldn't clip.
+
+## Free / royalty-aware SFX sources
+Mixkit, Pixabay (sound), Freesound (check each license — CC0 vs attribution), Uppbeat (free tier), and Remotion-safe CC0 packs. ALWAYS record the license per file; prefer CC0/royalty-free with commercial use. Keep an attributions file if any source requires it.
+
+## Workflow
+1. Identify the 3-6 key beats (reveal, pops, transitions, CTA).
+2. Pick one SFX per beat from the table.
+3. Place via `<Sequence from={frame}>` + `<Audio>`; tune volume + a short fade.
+4. Render with audio and LISTEN — adjust timing by a few frames so hits land exactly on the visual.
+
+Related: `remotion-music-picker`, `remotion-template-composition`.
diff --git a/remotion-svg-colors/SKILL.md b/remotion-svg-colors/SKILL.md
new file mode 100644
index 0000000..0ed3ee0
--- /dev/null
+++ b/remotion-svg-colors/SKILL.md
@@ -0,0 +1,45 @@
+---
+name: remotion-svg-colors
+description: How FlatRender makes template colors user-editable and generates per-scene SVG so the studio can recolor a template and preview it in real time. Use when wiring a template's colors to the studio color picker, choosing which elements are recolorable, or generating an SVG color-preview for a scene.
+---
+
+# SVG + color system (real-time recolor)
+
+Goal: a user opens a template, changes its colors, and sees the result update live. This works because every colorable element reads from a NAMED color, those names are stored as editable color elements in the DB, and a lightweight SVG representation lets the studio recolor without a full re-render.
+
+## The color data model
+- **`content.shared_colors`** — project-wide colors (key = `element_key`, e.g. `accentColor`). Used by every scene.
+- **`content.scene_color_elements`** — per-scene colors (key = `element_key`, e.g. `frl_c1t1` for AE, or a Remotion prop name).
+- Studio copies these into `studio.saved_shared_colors` / `saved_scene_colors`; the render binder (`GetRenderBindings` in render-svc) returns them as `{element_key: hex}`.
+- For **Remotion**, those keys must equal the composition's `colorSchema` props: `accentColor`, `secondaryColor`, `backgroundColor`, `textColor` (from `src/lib/branding.ts`). The node-agent passes them as `--props`.
+- For **AE**, colours bind into the `frshare` comp's text layers (`bind.jsx`).
+
+**Rule:** design every template so EVERY colorable element's color comes from a named prop — never a hardcoded hex for anything the user should be able to change. Seed a `shared_colors` row per color prop (the seed script already does accent/secondary/background/text).
+
+## The SVG color-preview (live recolor without re-rendering)
+A full Remotion/AE re-render is too slow for a color picker. So a scene is also represented as an **SVG** whose shapes' `fill`/`stroke` reference the SAME color keys. The studio swaps the SVG's colors instantly as the user drags the picker.
+- AE pipeline: `content.projects.shared_colors_svg` + the `template_svg_previews` table + per-scene snapshots.
+- For a Remotion template, generate an SVG snapshot of a representative frame where colorable regions are tagged with their key, e.g.:
+  ```svg
+  <rect ... fill="var(--accentColor)" data-color-key="accentColor"/>
+  <text ... fill="var(--textColor)" data-color-key="textColor">...</text>
+  ```
+  The studio sets CSS variables (`--accentColor: #...`) or rewrites `fill` by `data-color-key` to recolor live; on export the real props go to the renderer.
+
+## How to author a recolorable template
+1. Use the 4 `colorSchema` props for all themeable color (add more named props only if a template genuinely needs them — and seed a matching `shared_colors` row for each).
+2. Keep colorable regions as FLAT fills/strokes that map cleanly to one key (gradients = blend of two named props via `mixHex`, still derived from props).
+3. Produce an SVG preview of the key frame with each region tagged `data-color-key` = the prop name, so the studio can map picker → region.
+4. Verify: changing a prop changes exactly the intended regions and nothing hardcoded stays the wrong color.
+
+## Generating the SVG
+- Simple/flat scenes: hand-author or script an SVG mirroring the composition's shapes, tagging fills with the color keys.
+- 3D / complex scenes: an SVG can't represent them faithfully — fall back to a rendered key-frame thumbnail per color theme, or a simplified 2D SVG stand-in for the picker (note this limitation to the user).
+- Store alongside the template (the AE path uses `shared_colors_svg` / `template_svg_previews`; mirror that for Remotion).
+
+## Pitfalls
+- A hardcoded hex on a "should-be-editable" element = the picker silently does nothing there. Audit for stray hexes.
+- Key mismatch (SVG `data-color-key` ≠ schema prop ≠ seeded `element_key`) breaks the binding — keep ONE naming source of truth.
+- Contrast: when users can recolor text + background, enforce/encourage a min contrast or the text can vanish.
+
+Related: `remotion-template-composition`, `remotion-design-styles`.
diff --git a/remotion-template-catalog/SKILL.md b/remotion-template-catalog/SKILL.md
new file mode 100644
index 0000000..d3043e3
--- /dev/null
+++ b/remotion-template-catalog/SKILL.md
@@ -0,0 +1,54 @@
+---
+name: remotion-template-catalog
+description: A taxonomy of video template TYPES to build for FlatRender, with the purpose, key editable elements, suggested style/aspect, and 2D-vs-3D recommendation for each. Use when deciding what template to create next, planning a content batch, or scoping a requested template into a known pattern.
+---
+
+# Template catalog — what to build
+
+FlatRender already has these (services/remotion `TEMPLATES`): IlluminatedCircles, KineticQuote, GradientPromo, VerticalStory, LogoMotion, Opener, InstaPromo, YouTubeIntro, Slideshow, HappyBirthday, SalePromo, QuoteCard, EventInvite, Countdown, GlitterReveal (editable logo), NowruzGreeting (2D characters), + 3D: Hero3D, Nowruz3D, Birthday3D, Promo3D.
+
+Use this map to pick the NEXT one and to scope a request into a pattern. Each row: key editable elements · suggested style · best aspect(s) · 2D/3D.
+
+## Brand / logo
+- **Logo reveal** — logo + tagline · any style · all aspects · 2D or 3D. (have: IlluminatedCircles, LogoMotion, GlitterReveal, Hero3D)
+- **Opener / intro sting** — title + subtitle · cinematic/kinetic · 16:9, 9:16 · 2D/3D. (have: Opener)
+- **Outro / subscribe / end-card** — CTA + socials + logo · flat/neon · 16:9, 9:16 · 2D. (gap)
+- **Lower-third / name tag** — name + role · clean/glass · 16:9 · 2D. (gap)
+
+## Social / marketing
+- **Instagram post/story promo** — headline + image + CTA · gradient/bold · 1:1, 9:16. (have: InstaPromo, VerticalStory)
+- **YouTube intro/outro** — channel + subscribe · energetic · 16:9. (have: YouTubeIntro)
+- **TikTok/Reels hook** — big kinetic text · trendy · 9:16 · 2D. (gap)
+- **Sale / discount** — badge + headline + CTA · bold/3D gifts · all. (have: SalePromo, Promo3D)
+- **Product showcase / turntable** — product image/3D + specs · 3D cinematic · 16:9, 1:1. (gap — high value)
+- **Testimonial / review** — quote + stars + name/photo · clean · 1:1, 9:16. (gap)
+- **Explainer / feature list** — icon + text steps · isometric/flat · 16:9. (gap)
+- **Real-estate / listing** — photos + price + details · elegant · 16:9, 1:1. (gap)
+- **Restaurant / menu / food** — dish image + price · warm/appetizing · 1:1, 9:16. (gap)
+
+## Greetings / occasions (great for characters + 3D)
+- **Birthday** — name + message · party/3D cake · all. (have: HappyBirthday, Birthday3D)
+- **Nowruz (نوروز)** — greeting + year · spring characters/3D Haft-Sin · all. (have: NowruzGreeting, Nowruz3D)
+- **Yalda (یلدا)** — pomegranate/watermelon, candles, warm night · 2D/3D · all. (gap — high value, Persian)
+- **Wedding / engagement** — names + date · luxury gold/floral · all. (gap)
+- **Eid / Ramadan / Mehregan** — lantern/crescent/autumn motifs · ornate · all. (gap, Persian/region)
+- **New Year / holidays** — countdown + fireworks · festive 3D · 16:9, 9:16. (gap)
+- **Condolence / tribute** — respectful, minimal, slow · muted palette · all. (gap)
+
+## Content / text
+- **Quote card** — quote + author · kinetic/typographic · 1:1, 9:16. (have: QuoteCard, KineticQuote)
+- **Countdown** — target + number · energetic riser · all. (have: Countdown)
+- **Event invite** — title + date/place + RSVP · elegant · 1:1, 9:16. (have: EventInvite)
+- **Slideshow / photo gallery** — N images + captions · clean transitions · all. (have: Slideshow)
+- **Music visualizer** — audio-reactive bars + cover · neon/3D · 1:1, 9:16. (gap)
+
+## How to choose next
+1. Prefer **gaps** with high value for an Iran-facing product: Yalda, wedding, product showcase, testimonial, lower-thirds, outro/subscribe, music visualizer.
+2. Pick a STYLE that differs from neighbors (don't ship five dark-particle reveals) — see `remotion-design-styles`.
+3. Decide 2D vs 3D by subject (logos/products/abstract → 3D shines; text/character/illustrative → 2D or hybrid).
+4. Confirm a storyboard with the user for anything character- or scene-heavy.
+
+## Per-template build steps
+Storyboard (confirm) → build composition (lib helpers, design-styles, character-design) → make it fit all aspects (`remotion-aspect-ratios`) → wire editable text/logo/colors (`remotion-template-composition`, `remotion-svg-colors`) → pick fonts (`persian-fonts`) → optional music/SFX → render thumbnails + preview → seed (`scripts/seed_remotion_templates.py`) → deploy.
+
+Related: every other remotion-* skill.
diff --git a/remotion-template-composition/SKILL.md b/remotion-template-composition/SKILL.md
new file mode 100644
index 0000000..bba8ad4
--- /dev/null
+++ b/remotion-template-composition/SKILL.md
@@ -0,0 +1,60 @@
+---
+name: remotion-template-composition
+description: How to compose the editable elements of a FlatRender template — text, logo, image/media, and supporting copy — into a clear, well-paced presentation. Use when laying out what goes where, deciding the visual hierarchy, wiring editable fields, or timing the reveal sequence of a template.
+---
+
+# Composing a template (text / logo / image / copy)
+
+A template is not just a nice animation — it's a *fill-in-the-blanks* product. Users edit a few fields and it must look great with THEIR text/logo. Design for editability + clarity.
+
+## The binding model (how editable fields work)
+Editable elements live in the DB and bind to Remotion props by KEY (see `remotion-svg-colors` for the full pipeline):
+- **Text** → `content.scene_content_elements` of type `Text`; the element `key` MUST equal the composition's Zod schema field (e.g. `headline`, `tagline`). Studio shows a text input.
+- **Logo / image / media** → a `scene_content_elements` of type `Media`; key = a `z.string()` prop (e.g. `logoUrl`). Studio shows upload/replace. In the composition: `logoUrl ? <Img src={logoUrl}> : <DefaultMark/>`. See `GlitterReveal.tsx`.
+- **Colors** → `shared_colors` / `scene_color_elements`, key = a `colorSchema` prop.
+- Seed all of these via `scripts/seed_remotion_templates.py` (it has a `MEDIA` dict for image fields).
+
+**Rule:** every visible piece of copy or media a user would want to change MUST be a prop + a seeded element. Don't hardcode the brand name, date, price, etc.
+
+## Visual hierarchy (most templates need 2-4 tiers)
+1. **Primary** — the logo OR the headline/hero. Biggest, highest contrast, center of attention.
+2. **Secondary** — tagline / subtitle. ~35-45% of primary size.
+3. **Tertiary** — CTA, date, price badge, handle. Small but distinct (pill, badge, accent color).
+4. **Ambient** — decorative scene (particles, 3D, characters) — supports, never competes.
+
+Size ratios that read well: primary `vmin(80-110)`, secondary `vmin(26-40)`, tertiary `vmin(24-32)`. Weight: primary 800-900, secondary 500-700, tertiary 600-900.
+
+## Text legibility (critical over busy/3D backgrounds)
+- Add a scrim or shadow: `textShadow: 0 0 vmin(20) rgba(0,0,0,.7)`, or a semi-transparent panel behind text.
+- Persian is RTL: set `direction: "rtl"`, use `FONT` (Vazirmatn) from `lib/fonts.ts`. See `persian-fonts`.
+- Keep line length comfortable (`maxWidth ~ 86%`); never let text touch frame edges (see `remotion-aspect-ratios`).
+- For gradient text use `backgroundClip: text` + a `drop-shadow` for separation.
+
+## Logo placement
+- Center-stage for logo reveals; corner/lockup for promos.
+- Always provide a branded DEFAULT (the FlatRender mark) so the template looks finished before the user uploads.
+- Constrain with `maxWidth/maxHeight` + `objectFit: contain` so any uploaded logo fits without distortion.
+
+## Image / media
+- `objectFit: cover` for fullscreen backdrops (with a gradient scrim for text), `contain` for product/logo.
+- Add motion: slow Ken-Burns (`scale 1→1.08` + slight pan) so stills feel alive.
+- Mask into shapes (rounded rect, circle) for polish.
+
+## Timing & pacing (the reveal sequence)
+Stagger — never reveal everything at frame 0. A typical 6s (180f @30) beat sheet:
+- 0-30: scene/background establishes, ambient starts.
+- 20-55: hero/logo springs in (`spring()`), optional flash/impact.
+- 55-90: headline rises/fades in.
+- 90-120: tagline fades, letter-spacing settles.
+- 120-160: CTA/date pops (`spring`, glow pulse).
+- last ~30f: hold everything still for readability.
+Give each text element ~0.6-0.8s on screen minimum before the next competes.
+
+## Editability checklist
+- [ ] Every changeable text/logo/image/color is a prop + seeded element (key == schema field).
+- [ ] Branded default for logo + sensible default copy.
+- [ ] Clear 2-4 tier hierarchy; text legible over the background.
+- [ ] Staggered, eased reveal with a final hold.
+- [ ] Looks good with long Persian text and a tall logo (test it).
+
+Related: `remotion-svg-colors`, `remotion-aspect-ratios`, `persian-fonts`, `remotion-design-styles`.