iron-edge 1.2.0 → 2.0.0

package/skills/clone-site/package-lock.json

@@ -0,0 +1,360 @@
+{
+  "name": "clone-site-skill",
+  "version": "1.0.0",
+  "lockfileVersion": 3,
+  "requires": true,
+  "packages": {
+    "": {
+      "name": "clone-site-skill",
+      "version": "1.0.0",
+      "dependencies": {
+        "cheerio": "^1.0.0",
+        "playwright": "^1.50.0"
+      },
+      "engines": {
+        "node": ">=18"
+      }
+    },
+    "node_modules/boolbase": {
+      "version": "1.0.0",
+      "resolved": "https://registry.npmjs.org/boolbase/-/boolbase-1.0.0.tgz",
+      "integrity": "sha512-JZOSA7Mo9sNGB8+UjSgzdLtokWAky1zbztM3WRLCbZ70/3cTANmQmOdR7y2g+J0e2WXywy1yS468tY+IruqEww==",
+      "license": "ISC"
+    },
+    "node_modules/cheerio": {
+      "version": "1.2.0",
+      "resolved": "https://registry.npmjs.org/cheerio/-/cheerio-1.2.0.tgz",
+      "integrity": "sha512-WDrybc/gKFpTYQutKIK6UvfcuxijIZfMfXaYm8NMsPQxSYvf+13fXUJ4rztGGbJcBQ/GF55gvrZ0Bc0bj/mqvg==",
+      "license": "MIT",
+      "dependencies": {
+        "cheerio-select": "^2.1.0",
+        "dom-serializer": "^2.0.0",
+        "domhandler": "^5.0.3",
+        "domutils": "^3.2.2",
+        "encoding-sniffer": "^0.2.1",
+        "htmlparser2": "^10.1.0",
+        "parse5": "^7.3.0",
+        "parse5-htmlparser2-tree-adapter": "^7.1.0",
+        "parse5-parser-stream": "^7.1.2",
+        "undici": "^7.19.0",
+        "whatwg-mimetype": "^4.0.0"
+      },
+      "engines": {
+        "node": ">=20.18.1"
+      },
+      "funding": {
+        "url": "https://github.com/cheeriojs/cheerio?sponsor=1"
+      }
+    },
+    "node_modules/cheerio-select": {
+      "version": "2.1.0",
+      "resolved": "https://registry.npmjs.org/cheerio-select/-/cheerio-select-2.1.0.tgz",
+      "integrity": "sha512-9v9kG0LvzrlcungtnJtpGNxY+fzECQKhK4EGJX2vByejiMX84MFNQw4UxPJl3bFbTMw+Dfs37XaIkCwTZfLh4g==",
+      "license": "BSD-2-Clause",
+      "dependencies": {
+        "boolbase": "^1.0.0",
+        "css-select": "^5.1.0",
+        "css-what": "^6.1.0",
+        "domelementtype": "^2.3.0",
+        "domhandler": "^5.0.3",
+        "domutils": "^3.0.1"
+      },
+      "funding": {
+        "url": "https://github.com/sponsors/fb55"
+      }
+    },
+    "node_modules/css-select": {
+      "version": "5.2.2",
+      "resolved": "https://registry.npmjs.org/css-select/-/css-select-5.2.2.tgz",
+      "integrity": "sha512-TizTzUddG/xYLA3NXodFM0fSbNizXjOKhqiQQwvhlspadZokn1KDy0NZFS0wuEubIYAV5/c1/lAr0TaaFXEXzw==",
+      "license": "BSD-2-Clause",
+      "dependencies": {
+        "boolbase": "^1.0.0",
+        "css-what": "^6.1.0",
+        "domhandler": "^5.0.2",
+        "domutils": "^3.0.1",
+        "nth-check": "^2.0.1"
+      },
+      "funding": {
+        "url": "https://github.com/sponsors/fb55"
+      }
+    },
+    "node_modules/css-what": {
+      "version": "6.2.2",
+      "resolved": "https://registry.npmjs.org/css-what/-/css-what-6.2.2.tgz",
+      "integrity": "sha512-u/O3vwbptzhMs3L1fQE82ZSLHQQfto5gyZzwteVIEyeaY5Fc7R4dapF/BvRoSYFeqfBk4m0V1Vafq5Pjv25wvA==",
+      "license": "BSD-2-Clause",
+      "engines": {
+        "node": ">= 6"
+      },
+      "funding": {
+        "url": "https://github.com/sponsors/fb55"
+      }
+    },
+    "node_modules/dom-serializer": {
+      "version": "2.0.0",
+      "resolved": "https://registry.npmjs.org/dom-serializer/-/dom-serializer-2.0.0.tgz",
+      "integrity": "sha512-wIkAryiqt/nV5EQKqQpo3SToSOV9J0DnbJqwK7Wv/Trc92zIAYZ4FlMu+JPFW1DfGFt81ZTCGgDEabffXeLyJg==",
+      "license": "MIT",
+      "dependencies": {
+        "domelementtype": "^2.3.0",
+        "domhandler": "^5.0.2",
+        "entities": "^4.2.0"
+      },
+      "funding": {
+        "url": "https://github.com/cheeriojs/dom-serializer?sponsor=1"
+      }
+    },
+    "node_modules/domelementtype": {
+      "version": "2.3.0",
+      "resolved": "https://registry.npmjs.org/domelementtype/-/domelementtype-2.3.0.tgz",
+      "integrity": "sha512-OLETBj6w0OsagBwdXnPdN0cnMfF9opN69co+7ZrbfPGrdpPVNBUj02spi6B1N7wChLQiPn4CSH/zJvXw56gmHw==",
+      "funding": [
+        {
+          "type": "github",
+          "url": "https://github.com/sponsors/fb55"
+        }
+      ],
+      "license": "BSD-2-Clause"
+    },
+    "node_modules/domhandler": {
+      "version": "5.0.3",
+      "resolved": "https://registry.npmjs.org/domhandler/-/domhandler-5.0.3.tgz",
+      "integrity": "sha512-cgwlv/1iFQiFnU96XXgROh8xTeetsnJiDsTc7TYCLFd9+/WNkIqPTxiM/8pSd8VIrhXGTf1Ny1q1hquVqDJB5w==",
+      "license": "BSD-2-Clause",
+      "dependencies": {
+        "domelementtype": "^2.3.0"
+      },
+      "engines": {
+        "node": ">= 4"
+      },
+      "funding": {
+        "url": "https://github.com/fb55/domhandler?sponsor=1"
+      }
+    },
+    "node_modules/domutils": {
+      "version": "3.2.2",
+      "resolved": "https://registry.npmjs.org/domutils/-/domutils-3.2.2.tgz",
+      "integrity": "sha512-6kZKyUajlDuqlHKVX1w7gyslj9MPIXzIFiz/rGu35uC1wMi+kMhQwGhl4lt9unC9Vb9INnY9Z3/ZA3+FhASLaw==",
+      "license": "BSD-2-Clause",
+      "dependencies": {
+        "dom-serializer": "^2.0.0",
+        "domelementtype": "^2.3.0",
+        "domhandler": "^5.0.3"
+      },
+      "funding": {
+        "url": "https://github.com/fb55/domutils?sponsor=1"
+      }
+    },
+    "node_modules/encoding-sniffer": {
+      "version": "0.2.1",
+      "resolved": "https://registry.npmjs.org/encoding-sniffer/-/encoding-sniffer-0.2.1.tgz",
+      "integrity": "sha512-5gvq20T6vfpekVtqrYQsSCFZ1wEg5+wW0/QaZMWkFr6BqD3NfKs0rLCx4rrVlSWJeZb5NBJgVLswK/w2MWU+Gw==",
+      "license": "MIT",
+      "dependencies": {
+        "iconv-lite": "^0.6.3",
+        "whatwg-encoding": "^3.1.1"
+      },
+      "funding": {
+        "url": "https://github.com/fb55/encoding-sniffer?sponsor=1"
+      }
+    },
+    "node_modules/entities": {
+      "version": "4.5.0",
+      "resolved": "https://registry.npmjs.org/entities/-/entities-4.5.0.tgz",
+      "integrity": "sha512-V0hjH4dGPh9Ao5p0MoRY6BVqtwCjhz6vI5LT8AJ55H+4g9/4vbHx1I54fS0XuclLhDHArPQCiMjDxjaL8fPxhw==",
+      "license": "BSD-2-Clause",
+      "engines": {
+        "node": ">=0.12"
+      },
+      "funding": {
+        "url": "https://github.com/fb55/entities?sponsor=1"
+      }
+    },
+    "node_modules/fsevents": {
+      "version": "2.3.2",
+      "resolved": "https://registry.npmjs.org/fsevents/-/fsevents-2.3.2.tgz",
+      "integrity": "sha512-xiqMQR4xAeHTuB9uWm+fFRcIOgKBMiOBP+eXiyT7jsgVCq1bkVygt00oASowB7EdtpOHaaPgKt812P9ab+DDKA==",
+      "hasInstallScript": true,
+      "license": "MIT",
+      "optional": true,
+      "os": [
+        "darwin"
+      ],
+      "engines": {
+        "node": "^8.16.0 || ^10.6.0 || >=11.0.0"
+      }
+    },
+    "node_modules/htmlparser2": {
+      "version": "10.1.0",
+      "resolved": "https://registry.npmjs.org/htmlparser2/-/htmlparser2-10.1.0.tgz",
+      "integrity": "sha512-VTZkM9GWRAtEpveh7MSF6SjjrpNVNNVJfFup7xTY3UpFtm67foy9HDVXneLtFVt4pMz5kZtgNcvCniNFb1hlEQ==",
+      "funding": [
+        "https://github.com/fb55/htmlparser2?sponsor=1",
+        {
+          "type": "github",
+          "url": "https://github.com/sponsors/fb55"
+        }
+      ],
+      "license": "MIT",
+      "dependencies": {
+        "domelementtype": "^2.3.0",
+        "domhandler": "^5.0.3",
+        "domutils": "^3.2.2",
+        "entities": "^7.0.1"
+      }
+    },
+    "node_modules/htmlparser2/node_modules/entities": {
+      "version": "7.0.1",
+      "resolved": "https://registry.npmjs.org/entities/-/entities-7.0.1.tgz",
+      "integrity": "sha512-TWrgLOFUQTH994YUyl1yT4uyavY5nNB5muff+RtWaqNVCAK408b5ZnnbNAUEWLTCpum9w6arT70i1XdQ4UeOPA==",
+      "license": "BSD-2-Clause",
+      "engines": {
+        "node": ">=0.12"
+      },
+      "funding": {
+        "url": "https://github.com/fb55/entities?sponsor=1"
+      }
+    },
+    "node_modules/iconv-lite": {
+      "version": "0.6.3",
+      "resolved": "https://registry.npmjs.org/iconv-lite/-/iconv-lite-0.6.3.tgz",
+      "integrity": "sha512-4fCk79wshMdzMp2rH06qWrJE4iolqLhCUH+OiuIgU++RB0+94NlDL81atO7GX55uUKueo0txHNtvEyI6D7WdMw==",
+      "license": "MIT",
+      "dependencies": {
+        "safer-buffer": ">= 2.1.2 < 3.0.0"
+      },
+      "engines": {
+        "node": ">=0.10.0"
+      }
+    },
+    "node_modules/nth-check": {
+      "version": "2.1.1",
+      "resolved": "https://registry.npmjs.org/nth-check/-/nth-check-2.1.1.tgz",
+      "integrity": "sha512-lqjrjmaOoAnWfMmBPL+XNnynZh2+swxiX3WUE0s4yEHI6m+AwrK2UZOimIRl3X/4QctVqS8AiZjFqyOGrMXb/w==",
+      "license": "BSD-2-Clause",
+      "dependencies": {
+        "boolbase": "^1.0.0"
+      },
+      "funding": {
+        "url": "https://github.com/fb55/nth-check?sponsor=1"
+      }
+    },
+    "node_modules/parse5": {
+      "version": "7.3.0",
+      "resolved": "https://registry.npmjs.org/parse5/-/parse5-7.3.0.tgz",
+      "integrity": "sha512-IInvU7fabl34qmi9gY8XOVxhYyMyuH2xUNpb2q8/Y+7552KlejkRvqvD19nMoUW/uQGGbqNpA6Tufu5FL5BZgw==",
+      "license": "MIT",
+      "dependencies": {
+        "entities": "^6.0.0"
+      },
+      "funding": {
+        "url": "https://github.com/inikulin/parse5?sponsor=1"
+      }
+    },
+    "node_modules/parse5-htmlparser2-tree-adapter": {
+      "version": "7.1.0",
+      "resolved": "https://registry.npmjs.org/parse5-htmlparser2-tree-adapter/-/parse5-htmlparser2-tree-adapter-7.1.0.tgz",
+      "integrity": "sha512-ruw5xyKs6lrpo9x9rCZqZZnIUntICjQAd0Wsmp396Ul9lN/h+ifgVV1x1gZHi8euej6wTfpqX8j+BFQxF0NS/g==",
+      "license": "MIT",
+      "dependencies": {
+        "domhandler": "^5.0.3",
+        "parse5": "^7.0.0"
+      },
+      "funding": {
+        "url": "https://github.com/inikulin/parse5?sponsor=1"
+      }
+    },
+    "node_modules/parse5-parser-stream": {
+      "version": "7.1.2",
+      "resolved": "https://registry.npmjs.org/parse5-parser-stream/-/parse5-parser-stream-7.1.2.tgz",
+      "integrity": "sha512-JyeQc9iwFLn5TbvvqACIF/VXG6abODeB3Fwmv/TGdLk2LfbWkaySGY72at4+Ty7EkPZj854u4CrICqNk2qIbow==",
+      "license": "MIT",
+      "dependencies": {
+        "parse5": "^7.0.0"
+      },
+      "funding": {
+        "url": "https://github.com/inikulin/parse5?sponsor=1"
+      }
+    },
+    "node_modules/parse5/node_modules/entities": {
+      "version": "6.0.1",
+      "resolved": "https://registry.npmjs.org/entities/-/entities-6.0.1.tgz",
+      "integrity": "sha512-aN97NXWF6AWBTahfVOIrB/NShkzi5H7F9r1s9mD3cDj4Ko5f2qhhVoYMibXF7GlLveb/D2ioWay8lxI97Ven3g==",
+      "license": "BSD-2-Clause",
+      "engines": {
+        "node": ">=0.12"
+      },
+      "funding": {
+        "url": "https://github.com/fb55/entities?sponsor=1"
+      }
+    },
+    "node_modules/playwright": {
+      "version": "1.60.0",
+      "resolved": "https://registry.npmjs.org/playwright/-/playwright-1.60.0.tgz",
+      "integrity": "sha512-hheHdokM8cdqCb0lcE3s+zT4t4W+vvjpGxsZlDnikarzx8tSzMebh3UiFtgqwFwnTnjYQcsyMF8ei2mCO/tpeA==",
+      "license": "Apache-2.0",
+      "dependencies": {
+        "playwright-core": "1.60.0"
+      },
+      "bin": {
+        "playwright": "cli.js"
+      },
+      "engines": {
+        "node": ">=18"
+      },
+      "optionalDependencies": {
+        "fsevents": "2.3.2"
+      }
+    },
+    "node_modules/playwright-core": {
+      "version": "1.60.0",
+      "resolved": "https://registry.npmjs.org/playwright-core/-/playwright-core-1.60.0.tgz",
+      "integrity": "sha512-9bW6zvX/m0lEbgTKJ6YppOKx8H3VOPBMOCFh2irXFOT4BbHgrx5hPjwJYLT40Lu+4qtD36qKc/Hn56StUW57IA==",
+      "license": "Apache-2.0",
+      "bin": {
+        "playwright-core": "cli.js"
+      },
+      "engines": {
+        "node": ">=18"
+      }
+    },
+    "node_modules/safer-buffer": {
+      "version": "2.1.2",
+      "resolved": "https://registry.npmjs.org/safer-buffer/-/safer-buffer-2.1.2.tgz",
+      "integrity": "sha512-YZo3K82SD7Riyi0E1EQPojLz7kpepnSQI9IyPbHHg1XXXevb5dJI7tpyN2ADxGcQbHG7vcyRHk0cbwqcQriUtg==",
+      "license": "MIT"
+    },
+    "node_modules/undici": {
+      "version": "7.26.0",
+      "resolved": "https://registry.npmjs.org/undici/-/undici-7.26.0.tgz",
+      "integrity": "sha512-3O9Tf67pGhgOv9jM35AbhkXAKi13f3oy3aE4CSgr+TckGeY+/iu97ZXN+J7DpHPzLbVApFd1IFhcnBjREYXYcg==",
+      "license": "MIT",
+      "engines": {
+        "node": ">=20.18.1"
+      }
+    },
+    "node_modules/whatwg-encoding": {
+      "version": "3.1.1",
+      "resolved": "https://registry.npmjs.org/whatwg-encoding/-/whatwg-encoding-3.1.1.tgz",
+      "integrity": "sha512-6qN4hJdMwfYBtE3YBTTHhoeuUrDBPZmbQaxWAqSALV/MeEnR5z1xd8UKud2RAkFoPkmB+hli1TZSnyi84xz1vQ==",
+      "deprecated": "Use @exodus/bytes instead for a more spec-conformant and faster implementation",
+      "license": "MIT",
+      "dependencies": {
+        "iconv-lite": "0.6.3"
+      },
+      "engines": {
+        "node": ">=18"
+      }
+    },
+    "node_modules/whatwg-mimetype": {
+      "version": "4.0.0",
+      "resolved": "https://registry.npmjs.org/whatwg-mimetype/-/whatwg-mimetype-4.0.0.tgz",
+      "integrity": "sha512-QaKxh0eNIi2mE9p2vEdzfagOKHCcj1pJ56EEHGQOVxp8r9/iszLUUV7v89x9O1p/T+NlTM5W7jW6+cz4Fq1YVg==",
+      "license": "MIT",
+      "engines": {
+        "node": ">=18"
+      }
+    }
+  }
+}

package/skills/clone-site/package.json

@@ -0,0 +1,12 @@
+{
+  "name": "clone-site-skill",
+  "version": "1.0.0",
+  "private": true,
+  "type": "module",
+  "description": "Motor de clonagem 1:1 de sites (Playwright + cheerio) para a skill clone-site do Claude Code.",
+  "engines": { "node": ">=18" },
+  "dependencies": {
+    "playwright": "^1.50.0",
+    "cheerio": "^1.0.0"
+  }
+}

package/skills/clone-site/reference/lessons.md

@@ -0,0 +1,131 @@
+# clone-site — Lições, decisões técnicas e diagnóstico
+
+Conhecimento destilado de uma sessão real de clonagem (Next.js SSG com Adobe
+Typekit + GSAP ScrollSmoother) feita com wget, mais o motor de navegador que
+resolve as limitações encontradas. Carregue este arquivo quando algo no clone
+parecer errado.
+
+## 1. Por que o motor de navegador (e não wget)
+
+| Problema real | wget | navegador (Playwright) |
+|---|---|---|
+| SPA client-rendered (DOM vazio no HTML) | ❌ baixa shell vazio | ✅ captura DOM hidratado (`page.content()`) |
+| Fontes CDN travadas por domínio (Typekit) | ❌ 403/vazio em localhost | ✅ captura no domínio real e localiza |
+| Imagens lazy / scroll-triggered | ❌ não dispara | ✅ auto-scroll dispara o carregamento |
+| `url()` em CSS de CDN | ❌ resolve errado | ✅ resolve relativo à URL do CSS |
+| Animações (GSAP/Lenis) | parcial | ✅ chunks JS reais carregam |
+
+O insight central: **fontes Typekit só são servidas para domínios registrados.**
+Em `localhost` o kit (`use.typekit.net/XXXX.css`) e os binários `/af/...` dão 403 —
+foi por isso que, na sessão com wget, o CSS "parecia quebrado" (a fonte `degular`
+caía para fallback). O navegador captura essas fontes **enquanto está no domínio
+original**, salva localmente e reescreve o `@font-face src` para o arquivo local.
+
+## 2. Como a captura funciona (capture.mjs)
+
+1. Contexto Chromium com `serviceWorkers:'block'`, `bypassCSP:true`,
+   `ignoreHTTPSErrors:true`, UA Chrome fixa, `deviceScaleFactor:2`.
+2. **Um** `context.route('**/*')`: remove `if-none-match`/`if-modified-since`
+   (força corpo legível, evita 304) e — por padrão — aborta hosts de tracking.
+3. `context.on('response')`: salva cada corpo (`response.body()`), pulando
+   3xx/204/304/OPTIONS/`data:`. Gate de "quieto" via `requestfinished`.
+4. BFS de mesma origin: `goto` → `networkidle` → `autoScroll` → `document.fonts.ready`.
+   **HTML salvo por página:** se o site é SSG/SSR (`__NEXT_DATA__`, `__NUXT__`,
+   `data-reactroot`, WordPress…) salva a **resposta do servidor (pré-hidratação)** —
+   o React/Vue hidrata limpo, sem erros #418/#423. Se é CSR puro (shell vazio + JS),
+   salva o `page.content()` (DOM renderizado). Enfileira `<a href>` da mesma origin.
+5. **Gap-fill:** varre o HTML/CSS salvo por assets de mesma origin referenciados mas
+   não capturados (imagens lazy / disparadas por animação que o timing perdeu) e
+   busca-os direto via HTTP, completando o espelho.
+6. Escrita: host primário na raiz, terceiros em `_ext/<host>/...`, query foldada no
+   nome do arquivo. CSS é reescrito (url()/@import relativos à URL do CSS, beacon
+   `p.typekit.net` neutralizado). HTML via cheerio: `src/href/srcset/style/<style>`
+   viram **root-absolutos**; `<base>` removido; trackers inline removidos.
+
+Resultado: tudo root-absoluto (`/_ext/...`, `/assets/...`) → funciona em qualquer
+profundidade de rota, em `serve.py`, `npx serve` ou Vercel.
+
+## 3. Diagnóstico (quando algo parece errado)
+
+### "O CSS/as fontes estão quebradas"
+- Cheque `_verify/report.json` → `fontsMissingInClone`. Se listar a fonte do site
+  (ex: `degular`), ela não foi capturada.
+- Causa comum: rodou em modo `wget`. **Solução:** rode com `--engine browser`.
+- No modo navegador, confirme que `_ext/use.typekit.net/af/...` (ou
+  `_ext/fonts.gstatic.com/...`) existe. Se existir mas a fonte não aplica, verifique
+  se o `@font-face src url()` no `<style>`/CSS aponta para `/_ext/...` (o rewriter
+  faz isso; se o site usa um embed exótico, ajuste manualmente).
+
+### "Página em branco / conteúdo só aparece ao rolar"
+- Sites com **scroll virtual** (GSAP ScrollSmoother, Lenis, Locomotive): o `<main>`
+  fica `position:fixed; overflow:hidden; height:100vh` e o conteúdo é movido por
+  `transform` conforme o scroll. Screenshot em scroll=0 mostra só o header (100vh).
+  **Isso é o design do site, não um bug.** O `verify.mjs` rola antes do screenshot.
+- Se realmente vazio mesmo após rolar: o JS não hidratou. Cheque
+  `cloneConsoleErrors` no report e se os chunks `_next/static/...` foram salvos.
+- **Tela branca + React #423 (Next.js App Router):** o React falha ao hidratar,
+  descarta o HTML SSR e tenta render no client (que falha offline → branco).
+  Causas já corrigidas no `capture.mjs`, em ordem de descoberta:
+  1. **Detecção SSR** — App Router não tem `__NEXT_DATA__`, usa `__next_f`. A regex
+     de detecção inclui `__next_f` p/ salvar o HTML do servidor (pré-hidratação).
+  2. **Flight data apagado pelo filtro de tracker** (causa mais traiçoeira) — o RSC
+     payload é um `<script>self.__next_f.push([...])</script>` gigante (dezenas de
+     KB) cujo JSON pode CONTER "dataLayer"/"clarity"/"gtag(" no conteúdo da própria
+     página. O filtro de trackers o removia por engano → payload RSC incompleto →
+     #423. Fix: nunca remover `<script>` que casa `__next_f|__NEXT_DATA__|__NUXT__|
+     __remixContext|__sveltekit`. Sintoma diagnóstico: HTML salvo menor que o do
+     servidor (`curl`) e com 1 `__next_f.push` a menos.
+
+### "Erros 404 no console"
+- 404s de `google*/gtm/facebook/doubleclick/clarity` são **esperados** (tracking
+  offline) — por padrão removemos os scripts, mas alguns disparam mesmo assim.
+- 404 de chunk `_next/static/chunks/pages/...js` referenciado pelo `_buildManifest`
+  mas não visitado: o `fix_paths.py` cria stubs no modo wget; no modo navegador,
+  visite a rota correspondente (`--max-pages` maior) para capturá-lo de verdade.
+- 404 de imagem: confirme se também é 404 **no site original** antes de tratar como
+  defeito (sites frequentemente referenciam assets já removidos do servidor).
+- **404 de CSS/chunk `_next/static/...?dpl=...` (Vercel deployment ID):** o `?dpl=`
+  (e `?v=`) é cache-bust; o nome do arquivo já tem content-hash e é imutável. O
+  `localPathFor` NÃO folda a query no nome p/ `_next/static`/`_nuxt` (salva limpo),
+  e o `serve.py` ignora a query + tem fallback por prefixo (`stem.*.ext`). Assim os
+  chunks que o webpack pede em runtime (`foo.js?dpl=...`) resolvem para `foo.js`.
+- **`ENAMETOOLONG` abortando a captura inteira:** URLs com token longo no path
+  (ex.: `active_storage` do Rails, base64) estouravam o limite de 255 bytes do FS.
+  `localPathFor` trunca segmentos > 180 bytes (hash + extensão) e `writeAll` faz
+  try/catch por asset — um asset problemático nunca derruba o clone (cai p/ wget).
+
+### "Links internos não funcionam"
+- O `serve.py` resolve `/rota` → `/rota/index.html`. Se uma rota linkada não foi
+  capturada (fora do `--max-pages` ou de outra origin), ela 404. Aumente
+  `--max-pages` ou use `--include`.
+
+### "Site grande / crawl lento"
+- Rode `clone.sh` em **background**. Limite com `--max-pages`, `--include`/`--exclude`.
+- `--no-crawl` clona só a URL dada (1 página).
+
+## 4. Deploy do clone
+A saída é um site estático com refs root-absolutas:
+- Local: já sobe via `serve.py` (porta 8765).
+- Vercel: `cd <out> && vercel deploy --prod` (ou via Chrome Brain). Sem config —
+  `index.html` e `<rota>/index.html` resolvem como clean URLs.
+- Para SPA com roteamento client-side, adicione um rewrite catch-all → `/index.html`
+  (no Vercel: `vercel.json` com `{"rewrites":[{"source":"/(.*)","destination":"/index.html"}]}`)
+  e localmente use `clone.sh ... --spa`.
+
+## 5. Limites honestos
+- **Backends/forms**: login, contato, matrícula etc. não funcionam offline — não há
+  servidor. O clone é do front-end.
+- **Conteúdo atrás de auth / paywall / interação**: não é capturado.
+- **Vídeos/streams grandes**: o crawler ignora `.mp4/.mov/...` como links de página;
+  players que buscam mídia via JS podem não ter o arquivo localizado.
+- **Fontes Typekit no modo wget**: impossível localizar (domínio travado). Use o
+  navegador.
+- **Geração dinâmica baseada em estado** (ex: imagem que muda conforme seleção do
+  usuário): só o estado capturado é salvo.
+
+## 6. Mapa dos scripts
+- `clone.sh` — orquestra tudo (detecção → bootstrap → motor → servidor → verify).
+- `capture.mjs` — motor de navegador (Playwright + cheerio).
+- `serve.py` — servidor estático portátil (zero deps).
+- `verify.mjs` — original × clone (screenshots + relatório).
+- `wget_fallback.sh` / `fix_paths.py` — caminho rápido sem navegador.