@polymorphism-tech/morph-spec 8.27.0 → 8.29.0

package/framework/skills/core/migrate-lp-to-umbraco/SKILL.md

@@ -4,7 +4,7 @@ description: Migra uma landing page existente (React/Vite, Next.js estático ou
 version: core
 when-to-invoke: ao receber instrução "use /migrate-lp-to-umbraco {projeto}" do usuário, ou quando o usuário descrever necessidade de migrar uma LP para Umbraco
 user-invokable: true
-cliVersion: "8.27.0"
+cliVersion: "8.29.0"
 stacks:
   - umbraco
 ---
@@ -35,6 +35,7 @@ O processo é reproduzível para qualquer LP (React/Vite, Next.js estático ou H
   - **(a) código-fonte local** da LP (React/Vite, Next.js ou HTML) — caminho de **fidelidade máxima**, pois o CSS, o markup e os assets exatos estão disponíveis para o lift verbatim.
   - **(b) apenas a URL** da LP em produção — fallback: scrapear o HTML renderizado, o CSS computado e baixar todos os assets. O mesmo gate de paridade (passo 6) se aplica.
 - **Docker** disponível para boot local (`docker compose`), ou .NET 10 SDK + Node para boot sem container.
+- **Se a origem é scroll-driven** (canvas frame-scrub, pin, parallax, smooth scroll), leia antes os standards `frontend/scroll-driven/frame-scrub.md`, `smooth-scroll.md` e `scroll-components.md`. Eles carregam o conhecimento que o lift precisa preservar; o passo 4e diz onde os assets dessa animação vivem no destino.
 
 ## Passo 0 — Obter o template (sempre)
 
@@ -192,15 +193,31 @@ O script:
 
 Nunca commitar `.env`. O cache do passo 0 permanece intacto (read-only) — todo o trabalho acontece nesta cópia.
 
-**Smoke-boot antes de qualquer customização** — boot limpo do template para confirmar que o ambiente funciona:
+**Smoke-boot antes de qualquer customização** — boot limpo do template para confirmar que o ambiente funciona. Suba **na ordem**, backend primeiro, e só depois construa o frontend:
 
 ```bash
-docker compose up --build
+docker compose up -d backend
+# espere a Delivery API, não o backoffice (ver abaixo)
+until [ "$(curl -s -o /dev/null -w '%{http_code}' \
+  'http://localhost:5001/umbraco/delivery/api/v2/content?take=1')" = "200" ]; do sleep 5; done
+docker compose up --build -d frontend
 ```
 
-Backend sobe em `http://localhost:5001`, frontend em `http://localhost:3000`. Acessar `http://localhost:3000` e confirmar que a página carrega sem erro 500. Isso elimina problemas de ambiente antes de introduzir customizações — falha precoce = horas economizadas.
+Backend sobe em `http://localhost:5001`, frontend em `http://localhost:3000`. Acessar `http://localhost:3000` e confirmar que a página carrega sem erro 500. Isso elimina problemas de ambiente antes de introduzir customizações; falha precoce economiza horas.
 
-**Atenção (gotcha Build do Next.js):** o Dockerfile do frontend executa `next build` na imagem — nesse momento o backend precisa estar acessível para o Next.js buscar conteúdo via Delivery API. Se o build rodar antes do backend estar pronto, o build falha com erro de fetch. O `docker compose` com `depends_on: backend` mitiga isso, mas em CI adicionar um `healthcheck` no serviço `backend` e `condition: service_healthy` no `depends_on` do `frontend`.
+**Atenção (gotcha Build do Next.js):** o Dockerfile do frontend executa `next build` na imagem, e nesse momento o Next busca conteúdo via Delivery API para o SSG. Se a API não responder **conteúdo**, o build falha, e a mensagem que chega é só `npm run build ... exit code 1`, sem dizer que o problema é o backend. Por isso `docker compose up --build` sozinho, do zero, não é um comando confiável: ele constrói o frontend junto com o backend.
+
+> **O critério de prontidão é a Delivery API responder 200, nunca o backoffice.** Um healthcheck
+> que bate em `/umbraco` fica **healthy** enquanto `/umbraco/delivery/api/v2/content` ainda devolve
+> **500**: o backoffice sobe, o uSync importa, o seed grava, e a API só quebra quando alguém pede o
+> conteúdo. `depends_on: condition: service_healthy` apontando para o healthcheck errado dá uma
+> falsa sensação de ordem resolvida e o build do frontend morre mesmo assim. Aponte o healthcheck
+> do backend para a Delivery API.
+>
+> **E se ela devolver 500, não é questão de esperar mais.** Um 500 persistente na Delivery API com
+> banco recém-seedado é quase sempre **dado seedado no formato errado**, não lentidão de boot.
+> Aumentar timeout não resolve; vá para a seção "Gotchas de campo" e diagnostique pelo log do
+> Umbraco antes de seguir.
 
 ### 4. Lift verbatim — portar markup, mídia e tema
 
@@ -401,6 +418,33 @@ Registrar o módulo em `frontend/src/components/modules/moduleRegistry.ts`:
 nomeSection: () => import('./NomeSection'),
 ```
 
+#### 4e. Sequências de frames e assets de animação (LP scroll-driven)
+
+Se a origem tem hero (ou seção) com **canvas frame-scrub** (o scroll avançando um vídeo quadro a quadro), a animação atravessa a migração intacta, mas só se os assets forem para o balde certo. O modelo abaixo é o que roda em produção; foi decidido uma vez e não deve ser reaberto por engano.
+
+**Dois baldes, e a fronteira não é opinião:**
+
+| O quê | Onde | Editável no backoffice |
+|---|---|---|
+| Sequência de frames (`hero-frames/`, `oficio-frames/`), fontes, monograma da marca, ícones posicionais | `frontend/public/` | não, é asset estrutural |
+| Poster do scrub, fotos editoriais, logo, imagem de OG | `backend/seed-assets/` → Media Library → MediaPicker3 | sim |
+
+**Por que os frames não vão para a Media Library.** Três razões, em ordem de gravidade:
+
+1. O processamento on-the-fly do ImageSharp (`?format=webp`) exige URL assinada por HMAC, e no Umbraco 17 o HMAC não é relaxável por configuração. Uma sequência servida de `/media/` perde o webp e não tem como recuperá-lo no frontend headless.
+2. São 145 arquivos por sequência. Como requests assinadas ao backend, é um custo por visitante que não existe servindo de `/public`.
+3. O `SeedContentHandler` só enxerga `backend/seed-assets/` e o banco. Deixando os frames em `frontend/public/`, eles ficam fora do universo do seed: sobrevivem a re-seed, a re-import do uSync e a um `--reset-db` completo, sem nenhum tratamento especial.
+
+**O poster é o que fica editável.** É ele que aparece no mobile e sob `prefers-reduced-motion`, então é o único da dupla que o cliente tem motivo para trocar. Frames fixos, poster no MediaPicker.
+
+**Cache-bust é obrigatório e manual.** `frontend/public/` não recebe hash de build (o Dockerfile copia o diretório verbatim e o Next só versiona `.next/static`), então reextrair frames mantendo os mesmos nomes serve os bytes antigos de qualquer cache intermediário. O `framePath` carrega um `?v=N` que sobe a cada reextração:
+
+```ts
+const framePath = (i: number) => `/hero-frames/frame_${String(i).padStart(3, '0')}.jpg?v=2`
+```
+
+**No lift, não trocar a lib de animação.** O template não traz `gsap` nem `lenis`; se a origem usa, adicione ao `frontend/package.json` do destino. Portar o registry de motion e o runtime de scroll como componentes `'use client'`, com o guard de SSR no registro do ScrollTrigger (ele toca `document`) e o runtime montado uma vez na page. Detalhe completo em `frontend/scroll-driven/smooth-scroll.md` e `frontend/scroll-driven/frame-scrub.md` no acervo de standards.
+
 ### 5. Conectar o formulário ao backend de leads
 
 O template usa uma arquitetura de **multi-sink**: o backend seleciona automaticamente a integração correta pelo valor de `leadIntegration` configurado no nó `leadsConfig` do backoffice.
@@ -446,8 +490,12 @@ Objetivo: **provar** que a LP migrada é idêntica à origem. Com o lift verbati
 
 #### 6a. Boot + checklist manual (sanidade)
 
+Mesma ordem do passo 3: backend primeiro, Delivery API respondendo 200, e só então o frontend.
+
 ```bash
-docker compose up --build
+docker compose up -d backend
+until [ "$(curl -s -o /dev/null -w '%{http_code}' 'http://localhost:5001/umbraco/delivery/api/v2/content?take=1')" = "200" ]; do sleep 5; done
+docker compose up --build -d frontend
 ```
 
 Percorrer a página em `http://localhost:3000` e conferir, lado a lado com a origem: todas as seções na ordem certa, textos/mídias corretos, formulário visível, navegação e footer funcionando. Isso é só uma sanidade rápida antes dos checks automáticos.
@@ -459,7 +507,27 @@ A skill **scaffolda** o harness de paridade no projeto destino (o template **nã
 1. **Estrutura DOM + nomes de classe** por seção — `compare-sections.mjs` extrai o esqueleto de tags+classes de cada `<section>`/`<nav>`/`<footer>` dos dois lados (agrupado por chave semântica/texto âncora) e aponta diferenças. Adaptar o array `KEYS` (`[nome, matchFn]`) aos textos âncora das seções do projeto.
 2. **Estilo computado** em elementos amostrados — para cada seção, comparar `getComputedStyle` de elementos-chave (cor, `font-family`, `font-size`, `font-weight`, paddings/margins, `border-radius`) origem × destino. Divergência = falha.
 3. **Checksum de assets** — o conjunto de `sha256` de todas as imagens/vídeos/fontes servidas pelo destino deve igualar o conjunto capturado da origem no passo 1. Asset reencode/otimizado quebra aqui (proposital).
-4. **Comportamento por interação** — uma asserção Playwright por comportamento capturado no passo 1 (scroll-expand, carrossel, marquee, autoplay de vídeo, hover, máscara/validação de telefone, submit do formulário com `/api/leads` mockado retornando `{"ok":true}`).
+4. **Comportamento por interação** — uma asserção Playwright por comportamento capturado no passo 1 (scroll-expand, **canvas frame-scrub**, carrossel, marquee, autoplay de vídeo, hover, máscara/validação de telefone, submit do formulário com `/api/leads` mockado retornando `{"ok":true}`).
+
+> **Scrub e qualquer efeito dirigido por scroll se verificam COM MOVIMENTO.** Um screenshot
+> estático não distingue um scrub vivo de um canvas quebrado: o canvas pode estar 1x1 desenhando
+> um pixel esticado, ou ignorando o scroll por completo, e a foto continua plausível. Dirija o
+> scroll e compare o que foi desenhado em posições diferentes:
+>
+> ```js
+> const lenis = window.__lenis
+> const h = document.querySelector('header.hero-scrub').getBoundingClientRect().height
+> for (const p of [0, .15, .3, .45, .6, .8, 1]) {
+>   lenis.scrollTo(Math.round((h - innerHeight) * p), { immediate: true })
+>   await new Promise(r => setTimeout(r, 350))   // deixa o scrub:0.4 assentar
+>   // capture aqui: screenshot, ou uma assinatura de pixels via ctx.getImageData
+> }
+> ```
+>
+> A espera não é opcional: com `scrub: 0.4` o desenho não salta, e sem ela você fotografa o frame
+> anterior. **Critério de aprovação:** as capturas diferem entre si. Todas iguais significa scrub
+> morto, mesmo que a página pareça correta. Confirmar também que os frames respondem 200 com o
+> `?v=N` em uso e que os beats de texto trocam ao longo do percurso.
 
 ```bash
 cd frontend
@@ -487,6 +555,22 @@ A migração é "exata" quando **todos** são verdade:
 - `robots.txt`/`sitemap.xml` de produção apontam pro domínio real (não o placeholder `minha-landing-page.com.br` do template) — só acontece se `NEXT_PUBLIC_SITE_URL` foi setada como Build Variable no provedor.
 - Nenhuma chave de API ou token aparece em arquivo versionado.
 
+## Gotchas de campo
+
+Furos que já custaram build quebrado ou deploy revertido em migração real. Nenhum deles aparece como erro óbvio no caminho feliz.
+
+**Property editor guarda JSON, não escalar. Seedar string crua derruba a Delivery API inteira.** `Umbraco.DropDown.Flexible` persiste **array JSON mesmo com `Multiple: false`**. Dentro do JSON de um Block List a tentação é escrever `"ctaAcao": "ancora"` como qualquer outro campo do bloco; o correto é `["ancora"]`. O erro não fica no campo: a exceção sobe pelo `BlockListPropertyValueConverter` e **derruba o documento inteiro** (500 na home), o que mata o `next build` com SSG e chega até você como `npm run build ... exit code 1`. Só aparece com banco novo, então passa despercebido até o primeiro `--reset-db` ou deploy limpo.
+
+Regra, diagnóstico pela letra citada no `JsonException` e o procedimento de A/B estão em `references/umbraco-lp-patterns.md` (seção 6) da skill `create-umbraco-lp`, instalada em `.claude/skills/create-umbraco-lp/`. Leia essa seção antes de seedar qualquer dropdown.
+
+**MediaPicker3 sempre volta array, mesmo em single-pick.** Na Delivery API, todo campo de mídia chega como array (`poster`, `logo`, `favicon`, `imageSeo`, `modalLogo`), embutido sem `expand`. Acessar `campo.url` direto funciona enquanto o campo está vazio e passa a estourar no instante em que um editor o preenche. Pior: em `generateMetadata` o Next trata a exceção como fatal e derruba o build inteiro, então o sintoma é um deploy que quebra sozinho depois de alguém publicar no backoffice, sem nenhuma mudança de código. Tipar como `UmbracoImage[]` e indexar em `[0]`, sempre com fallback para o asset estático de `/public`.
+
+**Label de Block List aninhado usa UFM.** O backoffice do Umbraco 17 (Bellissima) renderiza o label do bloco com Umbraco Flavored Markdown, `{=alias}`, e não com o `{{ alias }}` do backoffice AngularJS antigo. Com a sintaxe velha o header do bloco mostra a chave literal para o editor. É só display do backoffice, não afeta o render da LP, e por isso passa despercebido em toda validação automática.
+
+**Reverse proxy e bind do Next.** Atrás de Traefik ou Coolify, o backend precisa de `UseForwardedHeaders` (X-Forwarded-Proto/For), senão o OpenIddict do backoffice não vê HTTPS e o login em `/umbraco` falha com `ID2083: This server only accepts HTTPS requests`. E o runner do frontend precisa de `HOSTNAME=0.0.0.0`: sem isso o `server.js` do Next standalone faz bind no id do container, o healthcheck via `localhost:3000` nunca passa, o container nunca fica healthy e o deploy dá rollback sem erro de aplicação nenhum.
+
+**Antes de escrever qualquer um destes, confira se o template já resolveu.** Correções são portadas do projeto de volta para o `MORPH_Umbraco_LP_Template`, então parte desta lista pode já estar no scaffold que o passo 0 baixou. Ensinar de novo uma correção existente cria divergência.
+
 ## Anti-padrões
 
 - Não commitar `.env` nem nenhum arquivo com tokens ou senhas.
@@ -531,3 +615,4 @@ Repo do template (privado, branch `master`): `polymorphism-tech/MORPH_Umbraco_LP
 - `MORPH_Umbraco_LP_Template/frontend/src/app/globals.css` — bloco `@theme` para portar o tema da origem
 - `MORPH_Umbraco_LP_Template/frontend/e2e/home.spec.ts` + `playwright.config.ts` — base de e2e (estender com `parity.spec.ts`)
 - `MORPH_Umbraco_LP_Template/docker-compose.yml` — orquestração backend + frontend com variáveis de ambiente
+- `.claude/skills/create-umbraco-lp/references/umbraco-lp-patterns.md` — padrões e gotchas do template (controller público, multi-sink, leitura server-side, segurança da Delivery API, uSync, **dropdown como JSON array (seção 6)**, seed idempotente, build do Next.js exigindo backend). Instalado junto com a skill irmã; carregue sob demanda.

package/framework/skills/core/morph-apply/SKILL.md

@@ -4,7 +4,7 @@ description: Orquestra a execução autônoma de tasks de uma feature morph-spec
 version: core
 when-to-invoke: após Gate 2 aprovado, ao receber instrução "use /morph-apply" ou "implementar feature"
 user-invokable: true
-cliVersion: "8.27.0"
+cliVersion: "8.29.0"
 ---
 
 # morph-apply

package/framework/skills/core/morph-brainstorming/SKILL.md

@@ -4,7 +4,7 @@ description: Entende o negócio, os usuários e a arquitetura antes de qualquer
 version: core
 when-to-invoke: ao receber um novo request de feature, antes de morph-plan
 user-invokable: true
-cliVersion: "8.27.0"
+cliVersion: "8.29.0"
 ---
 
 # morph-brainstorming

package/framework/skills/core/morph-eval/SKILL.md

@@ -4,7 +4,7 @@ description: Avalia a qualidade de uma tarefa ou fase com rubricas graduadas 0-1
 version: core
 when-to-invoke: ao completar uma tarefa ou ao finalizar uma fase de implementação
 user-invokable: false
-cliVersion: "8.27.0"
+cliVersion: "8.29.0"
 ---
 
 # morph-eval

package/framework/skills/core/morph-hotfix/SKILL.md

@@ -4,7 +4,7 @@ description: ADW cirúrgico de hotfix — resolve uma queda/bug crítico de prod
 version: core
 when-to-invoke: ao receber "/morph-hotfix {feature}", quando a morph-proposal classifica o pedido como workType hotfix (Passo 0), ou o usuário diz "produção caiu / hotfix / urgente"
 user-invokable: true
-cliVersion: "8.27.0"
+cliVersion: "8.29.0"
 ---
 
 # morph-hotfix

package/framework/skills/core/morph-implement/SKILL.md

@@ -4,7 +4,7 @@ description: Guia a execução de cada tarefa de implementação com standard e
 version: core
 when-to-invoke: ao iniciar cada task de implementação listada em tasks.json
 user-invokable: false
-cliVersion: "8.27.0"
+cliVersion: "8.29.0"
 ---
 
 # morph-implement

package/framework/skills/core/morph-plan/SKILL.md

@@ -4,7 +4,7 @@ description: Guia a produção dos artefatos de planejamento de uma feature (use
 version: core
 when-to-invoke: ao iniciar a fase plan de uma feature, após o Gate 1 (proposal aprovado)
 user-invokable: true
-cliVersion: "8.27.0"
+cliVersion: "8.29.0"
 ---
 
 # morph-plan

package/framework/skills/core/morph-proposal/SKILL.md

@@ -4,7 +4,7 @@ description: Orquestra a fase de proposta+plano de uma feature morph-spec. Encad
 version: core
 when-to-invoke: ao receber instrução "use /morph-proposal" do usuário, ou ao iniciar uma nova feature
 user-invokable: true
-cliVersion: "8.27.0"
+cliVersion: "8.29.0"
 ---
 
 # morph-proposal

package/framework/skills/core/morph-review/SKILL.md

@@ -4,7 +4,7 @@ description: Conduz a fase de revisão e produz o review-report.md para o Gate 3
 version: core
 when-to-invoke: ao iniciar a fase review, após todas as tasks de tasks.json estarem com status `done`
 user-invokable: true
-cliVersion: "8.27.0"
+cliVersion: "8.29.0"
 ---
 
 # morph-review

package/framework/skills/core/morph-stack-scan/SKILL.md

@@ -4,7 +4,7 @@ description: Varre o codebase existente, detecta stack atual, compara com o stac
 version: core
 when-to-invoke: ao iniciar uma feature em projeto brownfield (codebase já existente)
 user-invokable: true
-cliVersion: "8.27.0"
+cliVersion: "8.29.0"
 ---
 
 # morph-stack-scan

package/framework/skills/core/morph-standards/SKILL.md

@@ -4,7 +4,7 @@ description: Localiza um standard específico via busca server-side (morph-spec
 version: core
 when-to-invoke: quando precisar consultar um standard específico durante a implementação
 user-invokable: true
-cliVersion: "8.27.0"
+cliVersion: "8.29.0"
 ---
 
 # morph-standards

package/framework/skills/core/morph-uiux/SKILL.md

@@ -4,7 +4,7 @@ description: Conduz a fase opcional de UI/UX — design system, mockups, compone
 version: core
 when-to-invoke: ao tomar o ramo uiux (morph-spec advance --design), depois do Gate 1 e antes do morph-plan
 user-invokable: true
-cliVersion: "8.27.0"
+cliVersion: "8.29.0"
 ---
 
 # morph-uiux

package/framework/standards/PROVENANCE.json

@@ -0,0 +1,41 @@
+{
+  "version": "1.0.0",
+  "_note": "Standards distilled from an external source. The source is not a dependency at runtime: it lives in another repository and is not needed to use the framework. This file exists so drift is detectable instead of silent. Pin `sourceTree` when distilling, and re-pin deliberately after reviewing what changed. See test/framework/standards-provenance.test.js.",
+  "sources": [
+    {
+      "id": "morph-lp-cinematic",
+      "repo": "morph-HUB",
+      "path": "skills/morph-lp-cinematic",
+      "envVar": "MORPH_HUB",
+      "defaultCheckout": "R:/Polymorphism Tech/repos/morph-HUB",
+      "sourceTree": "e43114d4b28ff55680a5355cce27d31ffa74f22f",
+      "sourceCommit": "465c9b0",
+      "distilledOn": "2026-08-21",
+      "distilledFrom": [
+        "references/build-stack.md",
+        "references/component-recipes.md",
+        "references/premium-finish.md",
+        "references/seo-and-qa.md",
+        "references/gemini-image-prompt.md",
+        "references/seedance-scrub-prompt.md",
+        "references/seedance-loop-prompt.md"
+      ],
+      "notDistilled": [
+        "references/gates.md",
+        "references/last-mile.md",
+        "references/copy-and-messaging.md",
+        "references/section-blueprint.md"
+      ],
+      "notDistilledReason": "Deliberate split: a standard carries knowledge, a skill carries process. HITL gates, deploy and copy strategy stay with the skill.",
+      "standards": [
+        "frontend-scroll-driven-frame-scrub",
+        "frontend-scroll-driven-smooth-scroll",
+        "frontend-scroll-driven-scroll-components",
+        "frontend-design-system-premium-finish",
+        "frontend-design-system-ai-image-generation",
+        "frontend-design-system-ai-video-generation",
+        "frontend-seo-meta-schema-audit"
+      ]
+    }
+  ]
+}

package/framework/standards/STANDARDS.json

@@ -1226,7 +1226,7 @@
         "react"
       ],
       "stacks": [
-        "nextjs"
+        "*"
       ],
       "aliases": [
         "GSAP",
@@ -1260,7 +1260,7 @@
         "scroll-animation"
       ],
       "stacks": [
-        "nextjs"
+        "*"
       ],
       "aliases": [
         "ScrollTrigger",
@@ -1290,7 +1290,7 @@
         "plugins"
       ],
       "stacks": [
-        "nextjs"
+        "*"
       ],
       "aliases": [
         "Flip",
@@ -1695,21 +1695,30 @@
         "mcp"
       ],
       "stacks": [
-        "nextjs"
+        "*"
       ],
       "aliases": [
         "Image Generation",
         "AI Assets",
-        "Gemini Images"
+        "Gemini Images",
+        "brand fidelity",
+        "reference images",
+        "favicon",
+        "og image",
+        "asset generation"
       ],
       "anchors": {
         "when-to-use": "#when-to-use-ai-generated-images",
         "prompt-patterns": "#prompt-engineering-patterns",
         "aspect-ratios": "#aspect-ratio-guide",
         "assets-md": "#assetsmd-format",
-        "edit-workflows": "#iterative-editing-workflows"
+        "edit-workflows": "#iterative-editing-workflows",
+        "brand-fidelity": "#brand-fidelity-reference-dont-invent",
+        "to-video": "#downstream-images-that-become-video",
+        "favicon-og": "#the-two-assets-everyone-forgets",
+        "variations": "#variations-and-cost"
       },
-      "digest": "Guidelines for generating project images with Gemini Image MCP — prompt patterns, aspect ratios, design-system-aware prompts, iterative editing, and assets.md format."
+      "digest": "Guidelines for generating project images with the Gemini Image MCP: when to use AI versus stock versus SVG, prompt patterns, aspect ratios, iterative editing and assets.md format. Core principle is brand fidelity over invention: always pass the client's real assets as referenceImages via edit_image rather than generating in a vacuum, never AI-recreate a property developer's architectural render or a physical product (animate or reference the real one), and chain derivatives from an approved hero so the whole set shares light, palette and identity. Frame anything destined to become video WITHOUT a face, because video moderation is stricter (E005), and generate scrub frames at the video's exact ratio with the subject opposite the copy. Always produce the two forgotten assets: a favicon derived from the real logo (never a new one) and a 1200x630 OG share image. Offer two to three genuinely different variations per image, varying angle, light or composition rather than the seed, and never advance with a weak image because every derivative inherits it."
     },
     {
       "id": "ai-agents-durable-workflows-hitl",
@@ -1807,6 +1816,208 @@
         "errorbody": "#rule-2--error-path-tests-assert-the-response-body-not-just-the-status-code"
       },
       "digest": "Inject TimeProvider (never DateTime.UtcNow / DateOnly.FromDateTime(DateTime.UtcNow) directly in a handler or validator) and fake it with FakeTimeProvider (Microsoft.Extensions.TimeProvider.Testing) in integration tests — deterministic, no midnight-UTC flake, boundary dates (today vs. yesterday) become facts about the fake clock instead of when the suite happens to run. xUnit + WebApplicationFactory error-path tests (400/404/409) must assert the ProblemDetails response BODY (title/detail/violated field or error code), never just the HTTP status code — a status-only assertion lets the wrong validation rule or the wrong error branch pass silently as long as the status matches."
+    },
+    {
+      "id": "frontend-scroll-driven-frame-scrub",
+      "name": "frame scrub",
+      "path": "frontend/scroll-driven/frame-scrub.md",
+      "category": "frontend",
+      "subcategory": "scroll-driven",
+      "tags": [
+        "frontend",
+        "scroll-driven",
+        "motion"
+      ],
+      "stacks": [
+        "*"
+      ],
+      "aliases": [
+        "frame scrub",
+        "canvas scrub",
+        "scroll-driven video",
+        "scrollytelling video",
+        "apple scroll video",
+        "ffmpeg frames",
+        "poster fallback"
+      ],
+      "anchors": {
+        "why": "#section-1-canvas-not-video-currenttime",
+        "extraction": "#section-2-frame-extraction",
+        "cachebust": "#section-3-cache-busting-is-mandatory",
+        "bug": "#section-5-the-1x1-canvas-bug",
+        "responsive": "#section-6-responsive-and-reduced-motion",
+        "verify": "#section-8-verify-with-motion-never-with-a-still"
+      },
+      "digest": "Scroll-driven video is a preloaded JPG sequence drawn into a <canvas>, never a <video currentTime> driven by scroll (unreliable seek on iOS Safari, black-frame flashes) and never an autoplay loop (reads as a demo, not as user-driven). Extract with ffmpeg (fps=30, ~120-300 frames, -q:v 5), always extract a poster, hflip when the subject collides with the copy, and treat total sequence weight as a performance budget. Always cache-bust the frame URL (?v=N) when re-extracting under the same filenames. Known bug: a section starting hidden measures 0 and the canvas becomes 1x1 drawing one stretched pixel, so keep the canvas display:none and resize on the first loaded frame. Mobile and prefers-reduced-motion collapse to the static poster in both the JS guard and the CSS. Verify by driving the scroll through positions and comparing captured frames (allow ~350ms for scrub:0.4 to settle), never with a single screenshot."
+    },
+    {
+      "id": "frontend-scroll-driven-smooth-scroll",
+      "name": "smooth scroll",
+      "path": "frontend/scroll-driven/smooth-scroll.md",
+      "category": "frontend",
+      "subcategory": "scroll-driven",
+      "tags": [
+        "frontend",
+        "scroll-driven",
+        "motion"
+      ],
+      "stacks": [
+        "*"
+      ],
+      "aliases": [
+        "lenis",
+        "smooth scroll",
+        "scroll wiring",
+        "gsap ticker",
+        "window.__lenis",
+        "scrolltrigger refresh",
+        "HMR stale triggers"
+      ],
+      "anchors": {
+        "registry": "#section-1-central-motion-registry",
+        "raf": "#section-2-the-raf-handoff",
+        "expose": "#section-3-expose-the-instance-on-window",
+        "hmr": "#section-4-the-hmr-staleness-trap"
+      },
+      "digest": "Register GSAP plugins once in a shared lib/motion module that also exports prefersReducedMotion. Drive Lenis from gsap.ticker (never its own RAF loop), bind lenis.on(scroll, ScrollTrigger.update), set gsap.ticker.lagSmoothing(0), and call ScrollTrigger.refresh() on window load so triggers re-measure after fonts and images settle. Expose window.__lenis deliberately: overlays need stop()/start() to freeze the background, and automated verification needs scrollTo(y, {immediate:true}) to step through positions; consumers must use optional chaining because the instance is never created under reduced motion. After many hot reloads ScrollTrigger accumulates stale instances and pins/scrubs silently die, so full-reload before debugging, wrap every effect in gsap.context()/matchMedia() with revert on cleanup, and set invalidateOnRefresh on viewport-dependent triggers."
+    },
+    {
+      "id": "frontend-scroll-driven-scroll-components",
+      "name": "scroll components",
+      "path": "frontend/scroll-driven/scroll-components.md",
+      "category": "frontend",
+      "subcategory": "scroll-driven",
+      "tags": [
+        "frontend",
+        "scroll-driven",
+        "motion"
+      ],
+      "stacks": [
+        "*"
+      ],
+      "aliases": [
+        "pinned gallery",
+        "horizontal scroll",
+        "scroll reveal",
+        "parallax drift",
+        "count-up",
+        "lightbox",
+        "scroll progress",
+        "expanding modal"
+      ],
+      "anchors": {
+        "reveal": "#section-1-usereveal-the-base-brick",
+        "pinned": "#section-2-pinned-horizontal-gallery",
+        "overlays": "#section-3-expanding-modal",
+        "parallax": "#section-5-parallax-drift",
+        "rules": "#section-9-cross-cutting-rules"
+      },
+      "digest": "Toolbox of scroll-driven interaction patterns, not a mandatory list: useReveal (fade/rise with once:true) covers most content; pinned horizontal gallery needs invalidateOnRefresh:true or the travel distance stays frozen after a resize; expanding modal and lightbox mount then add an .in class on the next frame, pause the scroller via window.__lenis?.stop(), and must render OUTSIDE any pinned section because the pin transform breaks position:fixed inside it; parallax drift stays subtle at 5-8% with overflow:hidden on the figure; count-up animates a plain object and formats per locale; scroll progress uses scaleX with transform-origin 0 50% to stay on the compositor; accordions use native <details>. Cross-cutting: anything clickable that is not a button or anchor gets role=button, tabIndex 0 and Enter/Space, Escape closes overlays, every effect has a static reduced-motion fallback and reverts on cleanup."
+    },
+    {
+      "id": "frontend-design-system-premium-finish",
+      "name": "premium finish",
+      "path": "frontend/design-system/premium-finish.md",
+      "category": "frontend",
+      "subcategory": "design-system",
+      "tags": [
+        "frontend",
+        "design-system"
+      ],
+      "stacks": [
+        "*"
+      ],
+      "aliases": [
+        "premium finish",
+        "polish layer",
+        "film grain",
+        "atmosphere",
+        "load-in stagger",
+        "scrim",
+        "text over video",
+        "metallic accent",
+        "looks like a template"
+      ],
+      "anchors": {
+        "typography": "#section-1-typography-with-character",
+        "atmosphere": "#section-2-atmosphere-never-flat-color",
+        "loadin": "#section-3-one-orchestrated-load-in-beats-ten-micro-interactions",
+        "legibility": "#section-4-legibility-over-video-close-to-a-hard-rule",
+        "order": "#section-7-order-of-application"
+      },
+      "digest": "The finish layer that separates a working build from one a client reads as expensive, applied from the start rather than as a final polish pass. Principles, never a fixed recipe, and never converge on the same choices across projects: commit to a display font chosen from the brand (stack defaults and the AI-tell faces like Space Grotesk/Playfair announce machine-generated); use atmosphere instead of flat color (feTurbulence film grain at low opacity, radial brand glow, vignette); concentrate effort on ONE orchestrated hero load-in with staggered animation-delay rather than scattered micro-interactions; text over media always gets a DIRECTIONAL scrim (dark where the copy lives, clear over the subject) plus text-shadow as insurance against bright frames; one precious accent used in three places or fewer. Define brand tokens as CSS variables first, then atmosphere, then hero, then accent, then details."
+    },
+    {
+      "id": "frontend-seo-meta-schema-audit",
+      "name": "meta schema audit",
+      "path": "frontend/seo/meta-schema-audit.md",
+      "category": "frontend",
+      "subcategory": "seo",
+      "tags": [
+        "frontend",
+        "seo",
+        "accessibility"
+      ],
+      "stacks": [
+        "*"
+      ],
+      "aliases": [
+        "seo",
+        "meta tags",
+        "open graph",
+        "og:image",
+        "schema.org",
+        "json-ld",
+        "rich results",
+        "lighthouse",
+        "go-live audit",
+        "canonical"
+      ],
+      "anchors": {
+        "meta": "#section-1-essential-meta",
+        "opengraph": "#section-2-open-graph-and-twitter-cards",
+        "schema": "#section-3-schemaorg-json-ld-by-business-type",
+        "a11y": "#section-4-accessibility-also-an-seo-signal",
+        "audit": "#section-5-pre-launch-audit"
+      },
+      "digest": "Head-level SEO is cheap and pays for itself: title/description/canonical/theme-color/favicon, correct lang, font preconnects, and a full Open Graph set with an absolute 1200x630 og:image (without it a pasted link renders as a bare card). Pick the JSON-LD @type from the business (ClothingStore/Store for retail, LocalBusiness for services, RealEstateAgent or Residence for property, SoftwareApplication for SaaS) and include ONLY true fields: aggregateRating goes in only with a real rating and review count from a real source, otherwise omit the block, because fabricated structured data is a trust and manual-action risk. Accessibility doubles as an SEO signal (alt text, contrast checked against the brightest frames, focus order, one h1, reduced-motion honored). Before go-live run Lighthouse, a clean-console check, a share-card check and cross-device; if a heavy frame sequence costs Performance, confirm the cost sits in the scrub and state the trade rather than letting a low score pass unexamined."
+    },
+    {
+      "id": "frontend-design-system-ai-video-generation",
+      "name": "AI Video Generation",
+      "path": "frontend/design-system/ai-video-generation.md",
+      "category": "frontend",
+      "subcategory": "design-system",
+      "tags": [
+        "video",
+        "seedance",
+        "asset",
+        "ai-generation",
+        "motion",
+        "mcp"
+      ],
+      "stacks": [
+        "*"
+      ],
+      "aliases": [
+        "video generation",
+        "seedance",
+        "img2vid",
+        "endImage",
+        "directional footage",
+        "loop video",
+        "E005",
+        "animate render",
+        "scroll scrub footage"
+      ],
+      "anchors": {
+        "loop-vs-directional": "#section-1-the-distinction-that-decides-everything",
+        "directional": "#section-2-building-directional-footage",
+        "moderation": "#section-3-faces-trip-moderation",
+        "cost-ladder": "#section-4-the-cost-ladder",
+        "prompt-skeleton": "#section-5-prompt-skeleton"
+      },
+      "digest": "The decisive rule: a perfect loop has an end frame identical to its start, which is right for a self-playing ambient background and WRONG for scroll scrubbing, because start and end look the same and the page reads as frozen while the user scrolls. Scroll-driven footage needs directional movement via generate_video with an endImage (push-in/dolly is the most reliable, then reveal, pull-back, slow tilt); avoid orbits and any movement that returns to its origin. Client architectural renders are animated with img2vid, never AI-recreated. Human faces repeatedly trip moderation (E005), so crop the face out of frame (neck down, hands, product) and reserve faces for static image generation. Always climb the cost ladder: fast/480p/4s draft to judge framing and movement, 1080p only after approval, then re-extract frames with a bumped cache-bust. Prompts read like director notes with no hype words, and must reserve a calm dark region for the page copy with the subject on the opposite side. Generation is async: generate_video returns a request_id polled via get_video; list_videos reads local history and spends no credits."
     }
   ],
   "sharedAliases": {