@polymorphism-tech/morph-spec 7.5.0 → 7.7.0

package/framework/hooks/claude-code/core/tasks-json-guard.js

@@ -0,0 +1,81 @@
+#!/usr/bin/env node
+/**
+ * tasks-json-guard.js — PostToolUse hook (validate-and-warn, never block)
+ *
+ * Event: PostToolUse | Matcher: Write|Edit
+ *
+ * After any Write/Edit that touches a tasks.json under .morph/features/,
+ * re-reads the file from disk and validates the schema (status enum, effort
+ * enum). Invalid → injects a warning so the LLM fixes the file immediately;
+ * valid → logs one activity line and stays silent.
+ *
+ * The production failure this guards: a leaf sub-agent wrote
+ * status:"completed" (not in the enum — the schema accepts "done") into
+ * tasks.json and nothing flagged it. The blocking pre-write validation for
+ * post-Gate-2 edits lives in protect-spec-files.js (PreToolUse); this
+ * PostToolUse pass also covers pre-gate authoring (morph-plan) and anything
+ * that landed on disk regardless.
+ *
+ * Fail-open: exits 0 on any error.
+ */
+
+import { readFileSync } from 'fs';
+import { isAbsolute, join } from 'path';
+import { stateExists } from '../../shared/state-reader.js';
+import { injectContext, pass } from '../../shared/hook-response.js';
+import { logHookActivity } from '../../shared/activity-logger.js';
+import { getFilePath } from '../../shared/payload-utils.js';
+import { isFeaturePath, getBasename } from '../../shared/phase-utils.js';
+import { VALID_TASK_STATUS, validateTasksDoc } from '../../shared/tasks-validator.js';
+
+function readStdin() {
+  try {
+    return JSON.parse(readFileSync(0, 'utf8') || '{}');
+  } catch {
+    return {};
+  }
+}
+
+function projectDir() {
+  return process.env.CLAUDE_PROJECT_DIR || process.cwd();
+}
+
+try {
+  const cwd = projectDir();
+  if (!stateExists(cwd)) pass();
+
+  const payload = readStdin();
+  const filePath = getFilePath(payload);
+  if (!filePath) pass();
+  if (!isFeaturePath(filePath)) pass();
+  if (getBasename(filePath) !== 'tasks.json') pass();
+
+  const absPath = isAbsolute(filePath) ? filePath : join(cwd, filePath);
+
+  let doc;
+  try {
+    doc = JSON.parse(readFileSync(absPath, 'utf-8'));
+  } catch {
+    logHookActivity('tasks-json-guard', 'PostToolUse', 'invalid', cwd);
+    injectContext(
+      '⚠️ [morph-spec] tasks.json INVÁLIDO — o arquivo gravado não parseia como JSON. ' +
+      'Corrija o arquivo antes de continuar.'
+    );
+  }
+
+  const { valid, errors } = validateTasksDoc(doc);
+  if (!valid) {
+    logHookActivity('tasks-json-guard', 'PostToolUse', 'invalid', cwd);
+    injectContext(
+      '⚠️ [morph-spec] tasks.json com schema inválido após o write:\n' +
+      errors.map(e => `  • ${e}`).join('\n') +
+      `\nStatus válidos: ${VALID_TASK_STATUS.join(', ')}. Corrija antes de marcar a task como done.`
+    );
+  }
+
+  logHookActivity('tasks-json-guard', 'PostToolUse', 'ok', cwd);
+  pass();
+} catch {
+  // Fail-open
+  process.exit(0);
+}

package/framework/hooks/shared/tasks-validator.js

@@ -0,0 +1,68 @@
+/**
+ * tasks-validator.js — minimal hook-side schema validation for tasks.json.
+ *
+ * Mirrors VALID_STATUS / VALID_EFFORT from src/lib/tasks/tasks-json-parser.js.
+ * Hooks are installed standalone into target projects (.morph/framework/hooks/),
+ * so they cannot import from src/ — the enum lives here, duplicated on purpose
+ * and covered by tests on both sides.
+ */
+
+export const VALID_TASK_STATUS = ['pending', 'in_progress', 'done', 'skipped', 'blocked'];
+export const VALID_TASK_EFFORT = ['S', 'M', 'L', 'XL'];
+
+/**
+ * Validate the parts of a tasks.json document that hooks care about:
+ * a tasks[] array whose entries carry a valid status (and effort, when set).
+ * The production failure this guards: a leaf agent writing status "completed"
+ * (not in the enum) without any validation.
+ *
+ * @param {object} doc - parsed tasks.json
+ * @returns {{ valid: boolean, errors: string[] }}
+ */
+export function validateTasksDoc(doc) {
+  if (!doc || typeof doc !== 'object' || !Array.isArray(doc.tasks)) {
+    return { valid: false, errors: ['tasks.json must be an object with a tasks[] array'] };
+  }
+
+  const errors = [];
+  for (const task of doc.tasks) {
+    const id = task?.id ?? '?';
+    if (!VALID_TASK_STATUS.includes(task?.status)) {
+      errors.push(`task '${id}': invalid status '${task?.status}' (valid: ${VALID_TASK_STATUS.join(', ')})`);
+    }
+    if (task?.effort !== undefined && !VALID_TASK_EFFORT.includes(task.effort)) {
+      errors.push(`task '${id}': invalid effort '${task.effort}' (valid: ${VALID_TASK_EFFORT.join(', ')})`);
+    }
+  }
+  return { valid: errors.length === 0, errors };
+}
+
+/**
+ * Planned-vs-real outputs divergence: tasks whose `outputs` changed relative
+ * to the previous document but whose `notes` is still empty. The divergence
+ * itself is legitimate (outputs is a mutable progress field) — shipping it
+ * without an explanatory note is what gets flagged.
+ *
+ * @param {object} oldDoc - parsed previous tasks.json
+ * @param {object} newDoc - parsed proposed tasks.json
+ * @returns {string[]} human-readable violation messages (empty = OK)
+ */
+export function outputsDivergenceViolations(oldDoc, newDoc) {
+  const violations = [];
+  const oldById = new Map((oldDoc?.tasks ?? []).map(t => [t.id, t]));
+
+  for (const task of newDoc?.tasks ?? []) {
+    const old = oldById.get(task.id);
+    if (!old) continue;
+    const outputsChanged =
+      JSON.stringify(old.outputs ?? []) !== JSON.stringify(task.outputs ?? []);
+    const hasNote = typeof task.notes === 'string' && task.notes.trim().length > 0;
+    if (outputsChanged && !hasNote) {
+      violations.push(
+        `task '${task.id}': outputs diverged from the plan but 'notes' is empty — ` +
+        `record why in 'notes' in the same edit`
+      );
+    }
+  }
+  return violations;
+}

package/framework/mcp/registry.json

@@ -58,50 +58,6 @@
         "setupGuide": null
       }
     },
-    "github": {
-      "phases": ["tasks", "implement"],
-      "tools": ["get_repo", "search_code", "create_issue", "create_pull_request", "search_issues"],
-      "detection": "mcpServers includes github",
-      "fallback": "Bash `gh` CLI commands",
-      "usage": "Repo metadata, code search, issue creation, PR management",
-      "healthCheck": {
-        "toolPattern": "github",
-        "testCall": "Call any read-only GitHub tool (e.g., search_repositories or get_repo) to verify connectivity",
-        "testParams": {},
-        "successIndicator": "Returns repository data or search results without auth errors",
-        "failureHint": "GitHub MCP not responding. If using Docker, ensure Docker Desktop is running. Verify GITHUB_PERSONAL_ACCESS_TOKEN env var is set. Ensure the token has not expired and has the required scopes (repo, read:org)."
-      },
-      "install": {
-        "autoInstall": false,
-        "transport": "stdio",
-        "config": {
-          "type": "stdio",
-          "command": "docker",
-          "args": ["run", "-i", "--rm", "-e", "GITHUB_PERSONAL_ACCESS_TOKEN", "ghcr.io/github/github-mcp-server"],
-          "env": {
-            "GITHUB_PERSONAL_ACCESS_TOKEN": ""
-          }
-        },
-        "credentials": [
-          {
-            "name": "GitHub Personal Access Token",
-            "envVar": "GITHUB_PERSONAL_ACCESS_TOKEN",
-            "secret": true,
-            "helpUrl": "https://github.com/settings/tokens"
-          }
-        ],
-        "prerequisites": [
-          {
-            "name": "Docker",
-            "checkCommand": "docker --version",
-            "installUrl": "https://docs.docker.com/get-docker/"
-          }
-        ],
-        "stackRelevance": ["*"],
-        "warnings": [],
-        "setupGuide": "Official GitHub MCP Server (github/github-mcp-server). Requires Docker."
-      }
-    },
     "vercel": {
       "phases": ["implement"],
       "tools": ["search_docs", "list_projects", "get_deployments", "get_deployment_logs", "manage_env_vars"],
@@ -234,7 +190,8 @@
           {
             "name": "Gemini API Key",
             "envVar": "GEMINI_API_KEY",
-            "source": "Google AI Studio (https://aistudio.google.com/apikey)"
+            "secret": true,
+            "helpUrl": "https://aistudio.google.com/apikey"
           }
         ],
         "prerequisites": ["Google AI Studio API key"],
@@ -247,8 +204,8 @@
   "phaseMatrix": {
     "proposal": ["context7"],
     "uiux": ["playwright", "context7", "stitch", "gemini-image"],
-    "design": ["context7", "github"],
-    "tasks": ["context7", "github"],
-    "implement": ["context7", "playwright", "github", "vercel", "gemini-image"]
+    "design": ["context7"],
+    "tasks": ["context7"],
+    "implement": ["context7", "playwright", "vercel", "gemini-image"]
   }
 }

package/framework/rubrics/backend.json

@@ -1,7 +1,7 @@
 {
   "id": "backend",
-  "version": "1.0.0",
-  "description": "Backend-focused rubric. Higher weight on architecture, security, and package health.",
+  "version": "1.1.0",
+  "description": "Backend-focused rubric. Higher weight on architecture, security, and package health. Deterministic-validator rubric — approve threshold aligned to the single bar 9 from MORPH.md §0.",
   "categories": {
     "functionality": {
       "weight": 0.25,
@@ -35,7 +35,7 @@
     }
   },
   "thresholds": {
-    "approve": 8.0,
+    "approve": 9.0,
     "retry": 6.0
   }
 }

package/framework/rubrics/default.json

@@ -1,7 +1,7 @@
 {
   "id": "default",
-  "version": "1.0.0",
-  "description": "Default rubric for general-purpose projects. Balanced weights across all categories.",
+  "version": "1.1.0",
+  "description": "Default rubric for general-purpose projects. Balanced weights across all categories. Deterministic-validator rubric — approve threshold aligned to the single bar 9 from MORPH.md §0 (the LLM eval rubrics live in framework/evals/rubrics/*.md).",
   "categories": {
     "functionality": {
       "weight": 0.30,
@@ -30,7 +30,7 @@
     }
   },
   "thresholds": {
-    "approve": 8.0,
+    "approve": 9.0,
     "retry": 6.0
   }
 }

package/framework/rubrics/frontend.json

@@ -1,7 +1,7 @@
 {
   "id": "frontend",
-  "version": "1.0.0",
-  "description": "Frontend-focused rubric. Higher weight on design system compliance and UI quality.",
+  "version": "1.1.0",
+  "description": "Frontend-focused rubric. Higher weight on design system compliance and UI quality. Deterministic-validator rubric — approve threshold aligned to the single bar 9 from MORPH.md §0.",
   "categories": {
     "functionality": {
       "weight": 0.25,
@@ -30,7 +30,7 @@
     }
   },
   "thresholds": {
-    "approve": 8.0,
+    "approve": 9.0,
     "retry": 6.0
   }
 }

package/framework/rules/infrastructure-standards.md

@@ -3,14 +3,14 @@ paths:
   - "**/Dockerfile*"
   - "**/docker-compose*"
   - "**/.github/**"
-  - "**/easypanel*"
+  - "**/coolify*"
 stacks:
   - docker
 ---
 
 # Infrastructure Standards
 
-@.morph/framework/standards/infrastructure/docker/easypanel-deploy.md
+@.morph/framework/standards/infrastructure/docker/coolify-deploy.md
 
 ## Infrastructure Templates
 
@@ -19,9 +19,9 @@ stacks:
 | .NET API Dockerfile | `.morph/framework/templates/infrastructure/docker/dockerfile-api.dockerfile` | Multi-stage .NET |
 | Next.js Dockerfile | `.morph/framework/templates/infrastructure/docker/dockerfile-web.dockerfile` | Multi-stage Next.js |
 | Docker Compose | `.morph/framework/templates/infrastructure/docker/docker-compose.template.yml` | Local dev env |
-| EasyPanel Config | `.morph/framework/templates/infrastructure/docker/easypanel.template.json` | Deployment config |
+| Coolify Config | `.morph/framework/templates/infrastructure/docker/coolify.template.json` | Deployment config |
 | .NET Build CI | `.morph/framework/templates/infrastructure/github/workflows/dotnet-build.yml.hbs` | CI workflow |
 | Docker Push CI | `.morph/framework/templates/infrastructure/github/workflows/docker-build-push.yml.hbs` | Build & push |
-| Deploy EasyPanel | `.morph/framework/templates/infrastructure/github/workflows/deploy-easypanel.yml.hbs` | CD webhook |
+| Deploy Coolify | `.morph/framework/templates/infrastructure/github/workflows/deploy-coolify.yml.hbs` | CD via SSH |
 
 Read the template and adapt to your project structure.

package/framework/skills/core/create-umbraco-lp/SKILL.md

@@ -4,7 +4,7 @@ description: Guia a criação de uma landing page nova ponta-a-ponta a partir do
 version: core
 when-to-invoke: ao iniciar um novo projeto de LP com o template Umbraco genérico
 user-invokable: true
-cliVersion: "7.5.0"
+cliVersion: "7.7.0"
 ---
 
 # create-umbraco-lp
@@ -82,17 +82,31 @@ UMBRACO_ADMIN_PASSWORD=<gerada>
 UMBRACO_GLOBAL_ID=<uuid-gerado>
 ALLOWED_ORIGINS=http://localhost:3000
 REVALIDATE_SECRET=<gerado>
+FRONTEND_URL=http://localhost:3000
 LEADS_INTEGRATION=<integração-escolhida>
 ```
 
+`FRONTEND_URL` (junto com `REVALIDATE_SECRET`) alimenta o `RevalidateOnPublishHandler` do
+backend: a cada publish no Umbraco, ele chama `/api/revalidate` do frontend sozinho, em
+código — não depende de configurar nada em Settings > Webhooks no backoffice. **Em
+produção, atualize `FRONTEND_URL` para o domínio público real do frontend.**
+
 E gera `backend/appsettings.Development.json` com o bloco Unattended install do Umbraco (usando o email/senha computados pelo script). Isso significa que um projeto recém-scaffoldado **auto-instala no `dotnet run`** — sem necessidade de rodar o instalador UI manualmente.
 
 E escreve `frontend/.env.local` com:
 ```
 NEXT_PUBLIC_UMBRACO_URL=https://localhost:44324
+NEXT_PUBLIC_SITE_URL=http://localhost:3000
 REVALIDATE_SECRET=<mesmo-secret>
 ```
 
+`NEXT_PUBLIC_SITE_URL` é usada por `robots.ts`/`sitemap.ts`. **Em produção, precisa ser
+setada como Build Variable no Coolify** — o `Dockerfile` do template
+declara `ARG NEXT_PUBLIC_SITE_URL` (e `ARG NEXT_PUBLIC_UMBRACO_URL`) justamente para isso;
+sem marcar como Build Variable, a env var não chega ao `next build` e o `robots.txt`/
+`sitemap.xml` publicam o domínio placeholder do template (`minha-landing-page.com.br`) em
+produção — já aconteceu num projeto real.
+
 > **Nota de overwrite:** se `.env` já existe, `new-lp.ps1` prompta (Read-Host) para sobrescrever — portanto, uma execução não-interativa em um diretório que já tem `.env` vai bloquear na prompt. Execute em um scaffold fresco, ou responda à prompt interativamente.
 
 > **Nota importante:** `ALLOWED_ORIGINS` é gravado com `http://localhost:3000` pelo script independentemente do que foi informado no passo 1. Se o usuário especificou um domínio de produção, a forma de aplicá-lo depende do modo de execução:
@@ -229,9 +243,15 @@ Antes de fazer deploy ou entregar o projeto ao cliente:
 - [ ] Delivery API responde com o node `lpHome` populado: `/umbraco/delivery/api/v2/content?contentType=lpHome&take=1`.
 - [ ] `.env` contém `ALLOWED_ORIGINS` com o domínio de produção correto (separado por vírgula se múltiplos).
 - [ ] `UMBRACO_GLOBAL_ID` é único para este projeto (gerado pelo script — não reutilizar de outro projeto).
-- [ ] SEO: preencher título, descrição e OG image no backoffice (campos do node `lpHome`).
+- [ ] SEO: preencher no backoffice, aba SEO do node `lpHome` — Page Title, Meta Title, Meta Description, **Social Image** (1200x630, sem ela não há `og:image` e o link não gera preview no WhatsApp/redes), Canonical Url (só a URL, sem tag HTML).
+- [ ] Favicon: preencher o campo **Favicon** no backoffice (aba Configuration) — `app/icon.tsx`/`apple-icon.tsx` já leem esse campo dinamicamente; sem ele, cai no favicon estático genérico do template.
+- [ ] `NEXT_PUBLIC_SITE_URL` **e** `NEXT_PUBLIC_UMBRACO_URL` setadas como **Build Variable** no provedor (não só runtime) — conferir `robots.txt`/`sitemap.xml` em produção com o domínio real após o primeiro deploy.
+- [ ] `FRONTEND_URL` + `REVALIDATE_SECRET` setadas no backend em produção (revalidação automática pós-publish via `RevalidateOnPublishHandler`) — testar: publicar algo no backoffice e conferir no log do backend a linha `RevalidateOnPublish: cache do frontend invalidado após publish.`
+- [ ] No Index: confirmar que está **desligado** no backoffice antes de ir pra produção (o campo é opt-in pra esconder do Google, não deveria vir ligado por padrão).
 - [ ] Variáveis sensíveis (`UMBRACO_ADMIN_PASSWORD`, `REVALIDATE_SECRET`, tokens de integração) não estão commitadas no repositório (`.env` deve estar no `.gitignore`).
 - [ ] Em produção com Docker Compose: `docker-compose up --build` e confirmar que backend e frontend sobem com as variáveis do `.env`.
+- [ ] `browserslist` presente em `frontend/package.json` — já vem do template; só confirmar que não foi removido/sobrescrito durante a customização.
+- [ ] Se o cliente vai subir fotos de câmera/celular pelo Media Picker (galeria, hero, etc.): confirmar que `ResizeLargeMediaUploadsHandler` está registrado em `backend/Program.cs` (já vem do template) — sem ele, upload cru de 10+ MB pode virar 500 intermitente sob concorrência no otimizador do Next. Setar `MEDIA_BACKFILL_SECRET` em produção se for preciso reprocessar mídia já publicada (ver seção "Mídia" do README do template).
 
 > **Nota Docker — `LEADS_INTEGRATION` e `SEED_DEMO_CONTENT`:** o `docker-compose.yml` **não** injeta essas duas variáveis no container do backend. Mesmo que estejam no `.env`, o seed sempre inicializa `leadIntegration` como `"none"` no boot Docker. Isso é esperado: o editor deve configurar a integração manualmente no backoffice após o primeiro boot. Se precisar seeding automático da integração via Docker, adicione a variável na seção `environment` do serviço `backend` em `docker-compose.yml` manualmente.
 

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: "7.5.0"
+cliVersion: "7.7.0"
 ---
 
 # migrate-lp-to-umbraco
@@ -100,6 +100,16 @@ O objetivo desta etapa não é "entender" a LP, é **capturar tudo o que é nece
 - Registrar o `sha256` de cada asset (vira a base da paridade de checksum no passo 6).
 - **Não reencodar nem otimizar** nenhum asset — qualquer reencode quebra a paridade.
 
+**SEO/GEO da origem — capturar para semear, não perder no lift:** a paridade visual não
+cobre isso sozinha — um lift perfeito que esquece o SEO da origem entrega uma LP idêntica
+visualmente mas invisível pra buscadores/IA no dia 1. Capturar da origem:
+- `<title>`, `<meta name="description">`, `<link rel="canonical">`.
+- Open Graph: `og:title`, `og:description`, `og:image` (baixar a imagem, idealmente 1200x630).
+- JSON-LD (`<script type="application/ld+json">`) — schema completo, se existir.
+- Favicon (todos os tamanhos/formatos disponíveis) e `apple-touch-icon`.
+- `robots.txt` e `sitemap.xml` da origem — confirmar se há regras além do default (bots de IA bloqueados? outras URLs?).
+- `llms.txt` da origem, se existir.
+
 **Formulário de captação** — campos presentes, validação no frontend, endpoint atual, integração de CRM/leads.
 
 **Origem apenas por URL (fallback):** se não houver código-fonte, scrapear o HTML renderizado, extrair o CSS computado dos elementos e baixar todos os assets referenciados (incluindo fontes). O lift parte do markup renderizado + CSS computado.
@@ -268,7 +278,22 @@ sectionNode.SetValue("videoFundo", mediaJson);
 
 Coloque os assets de seed em `backend/seed-assets/` (imagens, vídeos, ícones da LP de origem).
 
-**O que vai no SeedContentHandler:** textos de inauguração, mídia local (arquivos em `seed-assets/`), ordem das seções, configuração inicial. O conteúdo fica editável no backoffice após o primeiro boot — o seed é apenas o estado inicial.
+**Semear também o SEO/GEO capturado no passo 1** — não deixar em branco pra "o editor preencher depois" (isso já causou um site indo pro ar sem `og:image`, com favicon genérico e apontando pro domínio errado no sitemap num projeto real):
+
+```csharp
+content.SetValue("pageTitleSeo", "<título da origem>");
+content.SetValue("titleSeo", "<og:title da origem>");
+content.SetValue("descriptionSeo", "<meta description da origem>");
+content.SetValue("canonicalUrlSeo", "<URL canônica de produção>"); // só a URL, sem tag HTML
+content.SetValue("noIndexSeo", false); // é Mandatory=false a partir do fix de 2026-07-02 — não deixar true
+content.SetValue("jsonLDSchemaSeo", OrigemJsonLd); // JSON-LD capturado da origem, se existir
+// imageSeo (og:image) e favicon: importar como media (mesmo padrão de CreateOrGetMedia)
+// e setar via MediaPicker3, igual ao padrão de mídia acima.
+```
+
+`imageSeo` (1200x630) e `favicon` alimentam `app/icon.tsx`/`apple-icon.tsx` e o `<meta property="og:image">` automaticamente — não precisam de nenhum código extra no frontend, só o seed correto.
+
+**O que vai no SeedContentHandler:** textos de inauguração, mídia local (arquivos em `seed-assets/`), ordem das seções, configuração inicial, **e o SEO/GEO capturado no passo 1**. O conteúdo fica editável no backoffice após o primeiro boot — o seed é apenas o estado inicial.
 
 **O que NÃO vai no SeedContentHandler:** tokens de integração (GHL API Key, webhook URL). Esses ficam no nó `leadsConfig` que o operador preenche diretamente no backoffice após o boot (ver passo 5).
 
@@ -298,12 +323,58 @@ Copiar as variáveis de design da origem para `frontend/src/app/globals.css` no
 }
 ```
 
-Atualizar os `<link>` de Google Fonts em `frontend/src/app/layout.tsx` para carregar as fontes corretas.
+**Fontes — auto-hospedar, nunca `<link>` externo pro Google Fonts:** um `<link rel="stylesheet"
+href="https://fonts.googleapis.com/css2?...">` no `<head>` é render-blocking (round-trip
+externo antes de qualquer paint) e, combinado com `font-display: swap`, causa CLS quando a
+fonte troca depois do primeiro paint — foi 1.680ms de render-blocking estimado e 0.221 de CLS
+medidos num caso real (Barone_LP). **Não usar `next/font/google`** aqui (diferente do passo 4
+de `create-umbraco-lp`, que pode usar): o nome de família que ele gera é escopado/diferente do
+literal da origem, e o gate de paridade (passo 6b.2) compara `font-family` computado
+byte-a-byte contra a origem — `next/font` quebra esse check.
+
+O fix correto, que preserva a paridade:
+1. Buscar a CSS real do Google pra descobrir as URLs `.woff2` (`curl` na mesma URL que iria no
+   `<link>`) — geralmente **um arquivo por família+estilo já cobre todos os pesos estáticos**
+   usados (Google costuma reaproveitar o mesmo arquivo pra weight 400/500/600/700 de uma fonte
+   não-variável). Baixar só o subset `latin` (`unicode-range: U+0000-00FF, ...`) — cobre toda
+   acentuação do português (á, ã, ç, é... estão em U+00C0-00FF).
+2. Salvar os `.woff2` em `frontend/public/fonts/`.
+3. Declarar `@font-face` em `globals.css` (ou no arquivo de tema) com o **mesmo `font-family`
+   literal da origem** (`'Cormorant'`, `'Jost'`, etc. — não o nome gerado por uma lib) e
+   `font-display: optional` (não `swap`) — `optional` só troca pro custom font se ele chegar
+   quase instantaneamente; senão fica no fallback pra aquela visita, evitando o reflow visível
+   que gerou o CLS.
+4. `<link rel="preload" href="/fonts/arquivo.woff2" as="font" type="font/woff2" crossOrigin="anonymous">`
+   no `<head>` do `layout.tsx`, sem nenhum `<link>` pro domínio do Google.
+
+Verificar ao final: `getComputedStyle(el).fontFamily` no elemento de heading do hero deve
+retornar **a mesma string literal que a origem** (ex.: `"Cormorant, Georgia, serif"`) — só a
+origem do arquivo mudou (de `fonts.gstatic.com` pra same-origin), não o nome da família.
 
 #### 4d. Componentes frontend dos módulos novos
 
 Para cada módulo novo, criar o componente em `frontend/src/components/modules/NomeSection.tsx` **a partir do componente da origem copiado verbatim** — colar o JSX/markup/classes/CSS da origem e trocar só os literais de conteúdo por `data.*`:
 
+> **Exceção deliberada ao verbatim — imagens de mídia do Umbraco:** o componente `Picture`
+> lifted da origem provavelmente emite um `<img>` cru. Pra qualquer `src` que vier do Media
+> Picker (URL do backend, editável no backoffice — diferente de um asset estático em
+> `/public`), usar `next/image` (`fill`, com o container já dimensionado) desde o primeiro
+> lift, não um `<img>` cru. Isso **não** quebra o gate de paridade (passo 6b.3 só faz checksum
+> de assets em `/public`, nunca de URLs de mídia) — pelo contrário, sem isso qualquer foto que
+> o cliente trocar depois no backoffice chega crua (fotos de câmera/celular fácil 10+ MB) e
+> vira lento ou 500 sob concorrência (ver seção "Mídia" no README do template).
+>
+> **Pitfall a checar nesse lift:** `next/image fill` aplica `position/height/width` **inline**
+> no `<img>` renderizado — isso vence qualquer regra de classe (`.minha-grade img { height:
+> 116%; margin-top: -8% }`, por exemplo) que a origem use pra efeitos de oversize/parallax/zoom
+> em cima de um `<img>` cru, mesmo que a regra continue no CSS lifted verbatim. Se a origem tem
+> algum truque desses (imagem deliberadamente maior que o container + margin negativo, comum
+> em seções com parallax scroll-scrub), a troca pra `fill` abre um vão visível onde a "sobra"
+> da imagem deveria estar. Fix: `!important` na propriedade de classe que está sendo vencida
+> (normalmente só `height`) — é uma das poucas justificativas legítimas pra `!important`, já
+> que é o único jeito de vencer um inline style que você não controla diretamente. Checar isso
+> na hora do lift, não esperar aparecer como bug visual depois.
+
 ```tsx
 // Padrão: componente com 'use client', recebe { data: SectionProps },
 // faz cast para o tipo tipado, e lê props via data.property.
@@ -365,6 +436,12 @@ Objetivo: **provar** que a LP migrada é idêntica à origem. Com o lift verbati
 
 **Hierarquia do gate:** os checks **determinísticos** (6b) são o **bloqueio**. O **screenshot diff** (6c) é **corroboração secundária** — nunca o bloqueio único, porque font hinting/antialiasing diferem entre ambientes mesmo com CSS byte-idêntico.
 
+> Os dois pontos do passo 4c (fontes auto-hospedadas) e 4d (`next/image fill` pra mídia do
+> Umbraco) não são drift de paridade — são a paridade **certa** pedindo um detalhe extra de
+> implementação. O checksum de assets (6b.3) só cobre `/public`; o estilo computado (6b.2)
+> continua batendo porque `font-family` fica literal. Nenhum dos dois deveria fazer o gate
+> falhar quando bem aplicados.
+
 #### 6a. Boot + checklist manual (sanidade)
 
 ```bash
@@ -403,7 +480,9 @@ A migração é "exata" quando **todos** são verdade:
 - **6c screenshot diff** abaixo da tolerância em todos os breakpoints (mobile/tablet/desktop).
 - Todas as seções renderizam com conteúdo real (não placeholders) e na ordem da origem.
 - Formulário envia lead com sucesso para a integração configurada (testar com dado real em staging; `--demo-seed` popula a home com módulos de demonstração via `SEED_DEMO_CONTENT=true`, não envia lead de teste).
-- Backoffice: editar um campo de texto, publicar — a mudança reflete na página (revalidação por tag ou ISR) **sem** alterar o markup/estilo renderizado.
+- Backoffice: editar um campo de texto, publicar — a mudança reflete na página **em produção, sem precisar de deploy manual** (o `RevalidateOnPublishHandler` do backend chama `/api/revalidate` sozinho; só funciona com `FRONTEND_URL`/`REVALIDATE_SECRET` setados) e **sem** alterar o markup/estilo renderizado.
+- SEO/GEO da origem migrado, não perdido: `curl` a home de produção e conferir `<title>`, `<meta description>`, `og:image`, canonical e JSON-LD batendo com o que foi capturado no passo 1 — e que o favicon do browser não é o ícone genérico do template.
+- `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.
 
 ## Anti-padrões
@@ -415,7 +494,7 @@ A migração é "exata" quando **todos** são verdade:
 - Não saltear o smoke-boot (passo 3) — problemas de ambiente devem ser detectados antes de portar conteúdo.
 - Não reutilizar `customHtmlSection` para tudo — módulos dedicados permitem edição granular no backoffice e ISR por tag.
 - **Não reinterpretar layout/CSS nem "limpar" o markup** — portar verbatim; o módulo Umbraco só embrulha o mesmo markup da origem. Rebuild = drift.
-- **Não reencodar nem otimizar assets** na migração — quebra a paridade de checksum (6b) e altera o render.
+- **Não reencodar nem otimizar assets da origem** (o que vai pra `/public`/`seed-assets`) na migração — quebra a paridade de checksum (6b) e altera o render. Isso **não** se aplica a imagens que vêm do Media Picker do Umbraco (ver passo 4d) — essas não são asset da origem, não entram no checksum, e otimizá-las via `next/image` é o comportamento correto, não uma violação de paridade.
 - **Não assumir o tema do template** — portar o Tailwind/`@theme` (e as fontes) da origem; a mesma classe utilitária renderiza diferente entre versões/temas.
 - **Não tratar o screenshot diff como gate único** — o bloqueio são os checks determinísticos (6b); o diff visual é secundário.