iron-edge 1.2.0 → 2.0.0

package/skills/clone-site/scripts/fix_paths.py

@@ -0,0 +1,118 @@
+#!/usr/bin/env python3
+"""
+fix_paths.py - Pos-processamento do espelho gerado por wget.
+
+1. Converte caminhos relativos (../  ./) para root-absolutos (/...) em todos
+   os HTMLs, para que os assets carreguem em qualquer profundidade de rota
+   (o <base href=""> vazio do Next.js quebra paths relativos quando a URL muda).
+2. Conserta o CSS do Typekit corrompido pelo wget: o bloco
+   <style data-href="https://use.typekit.net/XXXX.css">...url('')...</style>
+   vira um <link rel="stylesheet" href="https://use.typekit.net/XXXX.css"/>
+   (NOTA: kits Typekit sao travados por dominio e NAO carregam em localhost;
+    so funcionam no dominio registrado. Para fontes 100% locais use o motor
+    de navegador - veja reference/lessons.md).
+
+Uso: python3 fix_paths.py <rootDir>
+"""
+import os, re, sys
+
+ROOT = os.path.abspath(sys.argv[1]) if len(sys.argv) > 1 else os.getcwd()
+
+SKIP = ('http://', 'https://', '//', 'data:', '#', 'mailto:', 'tel:', 'javascript:', '/')
+
+# Runtime injetado no fim do <body> (igual ao capture.mjs):
+#  tk() ativa classes `tk-*` no <html> (kits Typekit); toast (opt-in via env) avisa
+#  que forms nao enviam offline. CLONE_FORM_TOAST=1 liga o toast.
+FORM_TOAST = os.environ.get('CLONE_FORM_TOAST') == '1'
+_TK = r"""function tk(){try{var c=new Set();for(var i=0;i<document.styleSheets.length;i++){var s=document.styleSheets[i],R;try{R=s.cssRules}catch(e){continue}if(!R)continue;for(var j=0;j<R.length;j++){var t=R[j].selectorText;if(!t)continue;var m=t.match(/\.tk-[\w-]+/g);if(m)for(var k=0;k<m.length;k++)c.add(m[k].slice(1))}}c.forEach(function(x){document.documentElement.classList.add(x)})}catch(e){}}if(document.readyState==='complete')tk();else window.addEventListener('load',tk);"""
+_TOAST = r"""document.addEventListener('submit',function(e){var f=e.target,a=((f.getAttribute&&f.getAttribute('action'))||'').trim();if(!/^(https?:|mailto:)/i.test(a)){e.preventDefault();var t=document.createElement('div');t.textContent='Clone estatico — formularios nao enviam (sem backend).';t.style.cssText='position:fixed;left:50%;bottom:24px;transform:translateX(-50%);background:#111;color:#fff;padding:12px 18px;border-radius:8px;font:14px/1.4 system-ui,sans-serif;z-index:2147483647;max-width:90vw;box-shadow:0 4px 20px rgba(0,0,0,.3);opacity:0;transition:opacity .2s';document.body.appendChild(t);requestAnimationFrame(function(){t.style.opacity='1'});setTimeout(function(){t.style.opacity='0';setTimeout(function(){t.remove()},300)},3500)}},true);""" if FORM_TOAST else ""
+INJECT = '<script data-clone-site="runtime">(function(){' + _TK + _TOAST + '})();</script>'
+
+def to_abs(p, rel_dir):
+    if not p or p.startswith(SKIP):
+        return p
+    if p.startswith('./'):
+        p = p[2:]
+    ups = 0
+    while p.startswith('../'):
+        ups += 1; p = p[3:]
+    dirs = [d for d in rel_dir.split('/') if d]
+    base = dirs[:len(dirs) - ups] if ups <= len(dirs) else []
+    out = '/' + '/'.join(base + [p]) if base else '/' + p
+    return re.sub(r'/{2,}', '/', out)
+
+ATTR_RE = re.compile(r'\b(href|src|poster)=(["\'])(.*?)\2', re.IGNORECASE)
+SRCSET_RE = re.compile(r'\b(srcset|imagesrcset)=(["\'])(.*?)\2', re.IGNORECASE)
+URLCSS_RE = re.compile(r'url\(\s*([\'"]?)([^\'")]*)\1\s*\)', re.IGNORECASE)
+TYPEKIT_STYLE_RE = re.compile(
+    r'<style[^>]*data-href="(https://use\.typekit\.net/[^"]+\.css)"[^>]*>.*?</style>',
+    re.IGNORECASE | re.DOTALL)
+
+def fix_html(path):
+    rel_dir = os.path.relpath(os.path.dirname(path), ROOT).replace('\\', '/')
+    if rel_dir == '.':
+        rel_dir = ''
+    with open(path, 'r', encoding='utf-8', errors='ignore') as f:
+        html = f.read()
+    orig = html
+
+    # Typekit corrompido -> link externo (1:1 do kit)
+    html = TYPEKIT_STYLE_RE.sub(lambda m: f'<link rel="stylesheet" href="{m.group(1)}"/>', html)
+
+    def attr(m):
+        return f'{m.group(1)}={m.group(2)}{to_abs(m.group(3), rel_dir)}{m.group(2)}'
+    html = ATTR_RE.sub(attr, html)
+
+    def srcset(m):
+        parts = []
+        for chunk in m.group(3).split(','):
+            seg = chunk.strip().split()
+            if seg:
+                seg[0] = to_abs(seg[0], rel_dir)
+                parts.append(' '.join(seg))
+        return f'{m.group(1)}={m.group(2)}{", ".join(parts)}{m.group(2)}'
+    html = SRCSET_RE.sub(srcset, html)
+
+    def urlcss(m):
+        return f'url("{to_abs(m.group(2), rel_dir)}")'
+    html = URLCSS_RE.sub(urlcss, html)
+
+    # injeta runtime (tk-* / toast) uma vez por página
+    # (replacement como função: INJECT contém \. \w que quebrariam re.sub com string)
+    if 'data-clone-site="runtime"' not in html:
+        html = re.sub(r'</body>', lambda _m: INJECT + '</body>', html, count=1, flags=re.IGNORECASE)
+
+    if html != orig:
+        with open(path, 'w', encoding='utf-8') as f:
+            f.write(html)
+        return True
+    return False
+
+n = 0
+for r, dirs, files in os.walk(ROOT):
+    dirs[:] = [d for d in dirs if not d.startswith('.')]
+    for fn in files:
+        if fn.endswith('.html'):
+            if fix_html(os.path.join(r, fn)):
+                n += 1
+print(f'[fix_paths] {n} HTMLs corrigidos em {ROOT}')
+
+# Stubs para chunks _next referenciados mas ausentes (evita 404 no console)
+bm = None
+for r, _, files in os.walk(ROOT):
+    for fn in files:
+        if fn == '_buildManifest.js':
+            bm = os.path.join(r, fn)
+if bm:
+    static_root = os.path.dirname(os.path.dirname(bm))  # .../_next/static
+    with open(bm, encoding='utf-8', errors='ignore') as f:
+        content = f.read()
+    chunks = set(re.findall(r'"(static/chunks/[^"]+\.js)"', content))
+    stubbed = 0
+    for c in chunks:
+        p = os.path.join(static_root, c.replace('static/', '', 1))
+        if not os.path.exists(p):
+            os.makedirs(os.path.dirname(p), exist_ok=True)
+            open(p, 'w').close()
+            stubbed += 1
+    print(f'[fix_paths] {stubbed} chunks _next stub-ados')

package/skills/clone-site/scripts/serve.py

@@ -0,0 +1,129 @@
+#!/usr/bin/env python3
+"""
+serve.py - Servidor estatico para o espelho clonado.
+
+Resolve o que quebrava no servidor padrao:
+- /rota  (sem barra) -> serve /rota/index.html
+- /rota.html quando existe
+- MIME correto p/ .js .mjs .css .woff2 .woff .ttf .webp .svg .json .wasm
+- no-cache (dev) + CORS p/ fontes
+- ignora BrokenPipe/ConnectionReset (cliente fechou)
+- --spa: fallback de qualquer rota desconhecida p/ /index.html
+
+Uso: python3 serve.py [--root DIR] [--port N] [--spa]
+"""
+import http.server, socketserver, os, sys, posixpath, glob
+from urllib.parse import unquote, urlsplit
+
+ROOT = os.getcwd()
+PORT = 8765
+SPA = False
+args = sys.argv[1:]
+i = 0
+while i < len(args):
+    a = args[i]
+    if a == '--root': ROOT = os.path.abspath(args[i + 1]); i += 2
+    elif a == '--port': PORT = int(args[i + 1]); i += 2
+    elif a == '--spa': SPA = True; i += 1
+    else: i += 1
+
+REAL_ROOT = os.path.realpath(ROOT)
+
+EXTRA_MIME = {
+    '.js': 'application/javascript', '.mjs': 'application/javascript',
+    '.css': 'text/css', '.json': 'application/json', '.map': 'application/json',
+    '.woff2': 'font/woff2', '.woff': 'font/woff', '.ttf': 'font/ttf',
+    '.otf': 'font/otf', '.eot': 'application/vnd.ms-fontobject',
+    '.svg': 'image/svg+xml', '.webp': 'image/webp', '.avif': 'image/avif',
+    '.ico': 'image/x-icon', '.wasm': 'application/wasm', '.webmanifest': 'application/manifest+json',
+    '.html': 'text/html; charset=utf-8',
+}
+
+class Handler(http.server.SimpleHTTPRequestHandler):
+    def __init__(self, *a, **k): super().__init__(*a, directory=ROOT, **k)
+
+    def end_headers(self):
+        self.send_header('Access-Control-Allow-Origin', '*')
+        self.send_header('Cache-Control', 'no-cache, no-store, must-revalidate')
+        super().end_headers()
+
+    def guess_type(self, path):
+        ext = posixpath.splitext(path)[1].lower()
+        if ext in EXTRA_MIME: return EXTRA_MIME[ext]
+        return super().guess_type(path)
+
+    def _within(self, p):
+        """Retorna o realpath se estiver dentro de ROOT; senao None (anti path-traversal)."""
+        try:
+            rp = os.path.realpath(p)
+        except OSError:
+            return None
+        return rp if (rp == REAL_ROOT or rp.startswith(REAL_ROOT + os.sep)) else None
+
+    def _resolve(self, urlpath):
+        p = unquote(urlsplit(urlpath).path)
+        # descarta segmentos vazios / '.' / '..' antes de montar o caminho
+        segs = [s for s in p.split('/') if s and s not in ('.', '..')]
+        fs = os.path.join(ROOT, *segs) if segs else ROOT
+        for cand in (fs, os.path.join(fs, 'index.html'), fs + '.html'):
+            safe = self._within(cand)
+            if safe and os.path.isfile(safe):
+                return safe
+        # fallback: asset pedido pelo nome-base (ex.: runtime do webpack pede
+        # `foo.css?dpl=...`) mas salvo no disco com hash-de-query no nome
+        # (`foo.<hash>.ext`). Casa por prefixo dentro do mesmo diretorio.
+        stem, ext = posixpath.splitext(fs)
+        if ext and os.path.isdir(os.path.dirname(fs)):
+            for m in sorted(glob.glob(glob.escape(stem) + '.*' + ext)):
+                safe = self._within(m)
+                if safe and os.path.isfile(safe):
+                    return safe
+        if SPA:
+            safe = self._within(os.path.join(ROOT, 'index.html'))
+            if safe and os.path.isfile(safe):
+                return safe
+        return None
+
+    def send_head(self):
+        target = self._resolve(self.path)
+        if target is None:
+            self.send_error(404, 'Not Found')
+            return None
+        try:
+            f = open(target, 'rb')
+        except OSError:
+            self.send_error(404, 'Not Found'); return None
+        try:
+            fs = os.fstat(f.fileno())
+            self.send_response(200)
+            self.send_header('Content-Type', self.guess_type(target))
+            self.send_header('Content-Length', str(fs.st_size))
+            self.end_headers()
+            return f
+        except Exception:
+            f.close(); raise
+
+    def do_GET(self):
+        try:
+            f = self.send_head()
+            if f:
+                try: self.copyfile(f, self.wfile)
+                finally: f.close()
+        except (BrokenPipeError, ConnectionResetError): pass
+
+    def log_message(self, fmt, *a):
+        try: msg = (fmt % a)
+        except Exception: msg = ''
+        if ' 404 ' in msg or ' 500 ' in msg:
+            sys.stderr.write('[serve] %s %s\n' % (self.address_string(), msg))
+
+class Server(socketserver.ThreadingMixIn, http.server.HTTPServer):
+    daemon_threads = True
+    allow_reuse_address = True
+
+if __name__ == '__main__':
+    os.chdir(ROOT)
+    with Server(('127.0.0.1', PORT), Handler) as httpd:
+        print(f'[serve] http://localhost:{PORT}  root={ROOT}  spa={SPA}')
+        try: httpd.serve_forever()
+        except KeyboardInterrupt: pass

package/skills/clone-site/scripts/verify.mjs

@@ -0,0 +1,126 @@
+#!/usr/bin/env node
+/**
+ * verify.mjs — Compara visualmente o ORIGINAL e o CLONE local.
+ *
+ * Para cada rota: tira screenshot full-page de ambos (desktop + opcional mobile),
+ * coleta erros de console e requests 404 do clone, e cruza a cobertura de fontes.
+ * Gera _verify/report.json + _verify/*.png para inspeção.
+ *
+ * Uso: node verify.mjs <originalUrl> <cloneBaseUrl> <outDir> [--routes "/,/sobre/"] [--mobile]
+ */
+import { chromium } from 'playwright';
+import { mkdir, writeFile, readFile, readdir, stat } from 'node:fs/promises';
+import path from 'node:path';
+
+const [originalUrl, cloneBase, outDir] = process.argv.slice(2);
+if (!originalUrl || !cloneBase || !outDir) {
+  console.error('uso: node verify.mjs <originalUrl> <cloneBaseUrl> <outDir> [--routes "..."] [--mobile]');
+  process.exit(2);
+}
+const argv = process.argv.slice(2);
+const ri = argv.indexOf('--routes');
+const ROUTES = ri !== -1 && argv[ri + 1] ? argv[ri + 1].split(',').map(s => s.trim()) : ['/'];
+const MOBILE = argv.includes('--mobile');
+const UA = 'Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/124.0.0.0 Safari/537.36';
+const vdir = path.join(outDir, '_verify');
+
+async function shoot(context, url, file, collect) {
+  const page = await context.newPage();
+  const errors = [], failed = [];
+  page.on('console', m => { if (m.type() === 'error') errors.push(m.text().slice(0, 200)); });
+  page.on('pageerror', e => errors.push(e.message.slice(0, 200)));
+  page.on('requestfailed', r => {
+    const u = r.url();
+    if (!/google|gtm|facebook|doubleclick|clarity|hotjar/.test(u)) failed.push(u);
+  });
+  let fonts = [];
+  try {
+    await page.goto(url, { waitUntil: 'load', timeout: 45000 });
+    await page.waitForLoadState('networkidle').catch(() => {});
+    await page.evaluate(async () => {
+      await new Promise(r => { let t = 0; const s = setInterval(() => { window.scrollBy(0, 800); t += 800; if (t > document.body.scrollHeight) { clearInterval(s); window.scrollTo(0, 0); r(); } }, 100); setTimeout(() => { clearInterval(s); r(); }, 6000); });
+    }).catch(() => {});
+    await page.evaluate(() => document.fonts && document.fonts.ready).catch(() => {});
+    await page.waitForTimeout(1200);
+    fonts = await page.evaluate(() => { try { return [...document.fonts].filter(f => f.status === 'loaded').map(f => `${f.family}/${f.weight}/${f.style}`); } catch { return []; } }).catch(() => []);
+    await page.screenshot({ path: file, fullPage: true });
+  } catch (e) {
+    if (collect) collect.note = 'goto falhou: ' + e.message;
+  } finally { await page.close().catch(() => {}); }
+  return { errors, failed, fonts: [...new Set(fonts)] };
+}
+
+// Checagens estáticas no espelho em disco (baratas, do método manual):
+// integridade de <style> (CSS truncado) e cobertura de chunks do _buildManifest.
+async function walkFiles(dir) {
+  const out = [];
+  async function rec(d) {
+    let ents; try { ents = await readdir(d, { withFileTypes: true }); } catch { return; }
+    for (const e of ents) {
+      if (e.name === '_verify' || e.name === 'node_modules' || e.name.startsWith('.')) continue;
+      const p = path.join(d, e.name);
+      if (e.isDirectory()) await rec(p); else out.push(p);
+    }
+  }
+  await rec(dir);
+  return out;
+}
+async function staticChecks(outDir) {
+  const res = { cssTruncated: [], chunks: { ok: 0, missing: [] } };
+  const files = await walkFiles(outDir);
+  for (const f of files.filter(x => x.endsWith('.html'))) {
+    try {
+      const h = await readFile(f, 'utf8');
+      const open = (h.match(/<style[\s>]/gi) || []).length;
+      const close = (h.match(/<\/style>/gi) || []).length;
+      if (open !== close) res.cssTruncated.push({ file: path.relative(outDir, f), open, close });
+    } catch {}
+  }
+  const manifest = files.find(x => x.endsWith('_buildManifest.js'));
+  if (manifest) {
+    try {
+      const txt = await readFile(manifest, 'utf8');
+      const nextDir = path.dirname(path.dirname(path.dirname(manifest))); // .../_next
+      const refs = [...new Set((txt.match(/"(static\/chunks\/[^"]+\.js)"/g) || []).map(m => m.slice(1, -1)))];
+      for (const ref of refs) {
+        const p = path.join(nextDir, ref);
+        try { const s = await stat(p); if (s.size > 0) res.chunks.ok++; else res.chunks.missing.push({ ref, reason: 'stub vazio' }); }
+        catch { res.chunks.missing.push({ ref, reason: 'ausente' }); }
+      }
+    } catch {}
+  }
+  return res;
+}
+
+(async () => {
+  await mkdir(vdir, { recursive: true });
+  const browser = await chromium.launch({ headless: true });   // sandbox ON
+  const report = { originalUrl, cloneBase, routes: [], generatedAt: new Date().toISOString() };
+  const ctx = await browser.newContext({ userAgent: UA, viewport: { width: 1440, height: 900 }, deviceScaleFactor: 1, ignoreHTTPSErrors: true, serviceWorkers: 'block' });
+  try {
+    for (const route of ROUTES) {
+      const slug = route.replace(/[^a-z0-9]+/gi, '_').replace(/^_|_$/g, '') || 'home';
+      const o = await shoot(ctx, originalUrl.replace(/\/$/, '') + route, path.join(vdir, `${slug}_original.png`));
+      const c = await shoot(ctx, cloneBase.replace(/\/$/, '') + route, path.join(vdir, `${slug}_clone.png`));
+      const missingFonts = o.fonts.filter(f => !c.fonts.includes(f));
+      report.routes.push({
+        route,
+        cloneConsoleErrors: c.errors,
+        cloneFailedRequests: c.failed,
+        fontsOriginal: o.fonts, fontsClone: c.fonts, fontsMissingInClone: missingFonts,
+        screenshots: { original: `_verify/${slug}_original.png`, clone: `_verify/${slug}_clone.png` },
+      });
+      const ok = c.failed.length === 0 && missingFonts.length === 0 && c.errors.length === 0;
+      console.log(`[verify] ${route}  ${ok ? 'OK' : 'ATENÇÃO'}  | 404s:${c.failed.length} erros:${c.errors.length} fontesFaltando:${missingFonts.length}`);
+      if (missingFonts.length) console.log('   fontes faltando no clone:', missingFonts.join(', '));
+      c.failed.slice(0, 5).forEach(f => console.log('   404:', f));
+    }
+  } finally { await ctx.close().catch(() => {}); await browser.close().catch(() => {}); }
+  report.staticChecks = await staticChecks(outDir);
+  const sc = report.staticChecks;
+  console.log(`[verify] estático | CSS truncado: ${sc.cssTruncated.length} | chunks ok: ${sc.chunks.ok} faltando: ${sc.chunks.missing.length}`);
+  sc.cssTruncated.slice(0, 5).forEach(c => console.log(`   <style> desbalanceado: ${c.file} (${c.open}/${c.close})`));
+  sc.chunks.missing.slice(0, 5).forEach(c => console.log(`   chunk ${c.reason}: ${c.ref}`));
+  await writeFile(path.join(vdir, 'report.json'), JSON.stringify(report, null, 2));
+  console.log(`[verify] relatório: ${path.join(vdir, 'report.json')}`);
+})().catch(e => { console.error('[verify] FALHA:', e); process.exit(1); });

package/skills/clone-site/scripts/wget_fallback.sh

@@ -0,0 +1,38 @@
+#!/usr/bin/env bash
+# wget_fallback.sh - Caminho rapido (sem navegador) para sites estaticos/SSG.
+# NAO captura conteudo client-side de SPAs nem fontes de CDN travadas por dominio
+# (ex: Adobe Typekit). Use o motor de navegador (capture.mjs) para fidelidade 1:1.
+#
+# Uso: wget_fallback.sh <url> <outDir>
+set -uo pipefail
+
+URL="${1:?url}"; OUT="${2:?outDir}"
+HOST="$(printf '%s' "$URL" | sed -E 's#^https?://([^/]+).*#\1#')"
+BARE="$(printf '%s' "$HOST" | sed -E 's/^www\.//')"
+SKILL_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")/.." && pwd)"
+
+mkdir -p "$OUT"
+echo "[wget] espelhando $URL (dominios: $HOST,$BARE,www.$BARE)"
+
+wget \
+  --mirror --convert-links --adjust-extension --page-requisites --no-parent \
+  --domains="$HOST,$BARE,www.$BARE" \
+  --tries=3 --timeout=30 --waitretry=2 --no-check-certificate -e robots=off \
+  --reject-regex '(gtm\.js|gtag|google-analytics|doubleclick|facebook\.com/tr|clarity\.ms)' \
+  --user-agent="Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/124.0.0.0 Safari/537.36" \
+  -P "$OUT" "$URL" 2>&1 | tail -20
+
+# wget cria OUT/<host>/...  -> achata para a raiz de OUT
+SRC=""
+for h in "$HOST" "www.$BARE" "$BARE"; do
+  [ -d "$OUT/$h" ] && SRC="$OUT/$h" && break
+done
+if [ -n "$SRC" ]; then
+  echo "[wget] achatando $SRC -> $OUT"
+  ( shopt -s dotglob nullglob; mv "$SRC"/* "$OUT"/ 2>/dev/null; rmdir "$SRC" 2>/dev/null )
+fi
+
+echo "[wget] corrigindo caminhos + Typekit + chunks"
+python3 "$SKILL_DIR/scripts/fix_paths.py" "$OUT"
+
+echo "[wget] concluido. (Aviso: fontes Typekit nao carregam em localhost neste modo.)"

package/skills/clone-transplant/SKILL.md

@@ -0,0 +1,50 @@
+---
+name: clone-transplant
+description: Veste a estrutura de um site clonado com a marca de um cliente. Lê o inventory.json da origem (cores por papel) e um brand.css de destino, troca cor por PAPEL (fundo→fundo, texto→texto), troca as fontes, e checa contraste no fim. Escreve numa pasta nova, nunca sobrescreve a origem. Use quando o usuário quiser o site do outro com a marca dele ("aquele site, com a minha cara").
+argument-hint: <origem> <inventory.json> <brand.css> --out <pasta> [--nivel raso|fundo]
+allowed-tools: Bash(node ${CLAUDE_SKILL_DIR}/scripts/transplant.mjs *), Read, Write
+---
+
+# clone-transplant — a estrutura do outro, a marca do cliente
+
+Troca as decisões de cor e fonte de um site clonado pelas da marca do cliente,
+**por papel**. A estrutura e o layout continuam sendo do original; a alma passa a
+ser da marca. Nunca inventa cor e nunca toca na origem.
+
+## Fluxo (caso A)
+1. `clone-site <url>` → pasta com o site do outro.
+2. `clone-inventory <url>` → `inventory.json` (cores da origem por papel).
+3. `clone-transplant <pasta> <inventory.json> <brand.css> --out <nova-pasta>`.
+
+## Como rodar
+```bash
+node ${CLAUDE_SKILL_DIR}/scripts/transplant.mjs \
+  <origem: arquivo.html|pasta> <inventory.json> <brand.css> --out <pasta-nova> \
+  [--nivel raso|fundo] [--so paleta,tipografia] [--roles fundo=--crema,texto=--tartufo]
+```
+
+## Profundidade (fundo é o padrão, escolhível)
+| Nível | Troca |
+|---|---|
+| `raso` | só a cor primária + as fontes |
+| `fundo` (padrão) | paleta inteira por papel + tipografia (cor e fonte) |
+| `--so a,b,c` | item a item (ex: `--so paleta` mantém as fontes do original) |
+| `--roles ...` | força o mapa de papéis (ex: `texto=--tartufo`) |
+
+> Troca **cor e fonte**. Raio e sombra ainda NÃO são trocados (ficam os do
+> original) — não são prometidos aqui de propósito.
+
+## Regras (as travas que protegem a marca)
+- **Mapa por papel, mostrado antes de aplicar.** O papel de cada cor do brand é
+  inferido do comentário da variável + luminância. Confira o mapa impresso.
+- **Respeita negação no comentário.** `--oro: NUNCA texto` não vira cor de texto.
+- **Texto = maior contraste sobre o fundo** quando há vários candidatos (o
+  `--tartufo` real vence o dourado de texto).
+- **Contraste é check obrigatório.** Se o par texto/fundo da marca reprova AA, o
+  relatório marca BLOQUEADOR — não entregue assim.
+- **Cores órfãs são reportadas** (apareceram no site, sem papel no inventário).
+- **A origem nunca é tocada.** Sempre escreve em `--out` (pasta nova).
+
+## Saída
+Pasta nova com o site transplantado + `_transplante.md` (mapa de cores aplicado,
+tipografia, contraste do resultado, cores órfãs). Rode o `gate` antes do cliente.