chore(skills+remotion): add flat-artist skill bundle; register 3D templates

- .claude/skills/flat-artist: the bundled FlatRender template-creation suite (orchestrator + 16 sub-skills + design/motion R&D), mirrors the Gitea AISkills repo. - services/remotion Root.tsx/templates.tsx: register the 3D templates + Three3DTest. Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
2026-06-21 19:39:25 +03:30
parent cb11c177a7
commit f83d657844
20 changed files with 1750 additions and 2 deletions
@@ -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/SKILL.md` (template TYPE → pattern), `../remotion-template-composition/SKILL.md`
+(what's editable, used to write "what you can customize"), `../persian-fonts/SKILL.md` (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/SKILL.md`)? 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/SKILL.md`); 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.