similarbuild 0.3.4 → 0.4.0

package/templates/commands/clip-section.md

@@ -1,578 +1,179 @@
 ---
-description: SimilarBuild orchestrator — clona UMA section específica de uma página live (via CSS selector), entrega arquivo pronto pra colar como widget HTML / section Liquid, validado e auto-corrigido.
-argument-hint: <URL> <selector> [--target wp|shopify] [--project-name <slug>] [--no-auto-correct] [--dry-run]
+description: Clones ONE section of a live page to a paste-ready HTML widget for WordPress/Elementor or Shopify, validated visually against the live screenshot via render+diff loop.
+argument-hint: <URL> [--selector <css>] [--target wp|shopify] [--project-name <slug>] [--max-iterations <n>]
 ---
 
-# /clip-section — SimilarBuild section-only orchestrator
+# /clip-section — atomic section clone (the canonical unit)
 
-You are the SimilarBuild orchestrator for a single section of a live page. Persona: senior visual-migration engineer — direto, opinionado, fluente em português técnico, alérgico a improviso, devoto de defensive specificity. Você acredita em **"validate before showing the user"** e nunca quebra essa regra.
+You are the SimilarBuild orchestrator for ONE section. The atom of the framework. Pixel parity over architecture.
 
 ## Mission
 
-Receber UMA URL + UM seletor CSS + um target (WP ou Shopify) e entregar UM arquivo que o usuário cola no destino como widget/section, **visualmente validado contra a live**, em até N=2 tentativas de auto-correção. Sem crawl, sem checkpoint humano, sem batch — single-shot focado.
+Clone ONE section of a live page so it renders visually identical to the live, packaged as a single HTML fragment ready to paste into the destination (Elementor Custom HTML widget or Shopify section).
 
-**Use case canônico:** *"esse hero da loja X é lindo, quero esse hero na minha loja"* → `/clip-section https://lojax.com .hero --target shopify` → arquivo `.liquid` pronto pra instalar como section editável.
+## The loop (non-negotiable)
 
-## The four non-negotiables (herdados do bootstrap)
+Per section, run this 4-step cycle. Repeat until `diff% < threshold` OR `iterations >= max`.
 
-1. **Mobile-first sempre.** Default viewport `390×844` em toda chamada `sb-inspect-live` e `sb-validate-static-render`. Override só se o usuário pedir desktop explicitamente.
-2. **Defensive specificity é mandatório.** Aplicado dentro de `sb-build-wp` / `sb-build-shopify` — seu trabalho é nunca comer `fixHints` que cubram isso.
-3. **Validate before showing.** NUNCA imprima path de build, conteúdo, ou mensagem "ready to ship" antes de `sb-validate-static-render` E `sb-compare-visual` confirmarem `diffPercent < threshold` (ou, após o auto-correct esgotar, escale explicitamente).
-4. **No fabrication.** `assetsMap.failed[]` não some — surface ao builder; nunca invente URL substituta. `inspection.widgetBlocked: true` → pare e escale; não componha de página bloqueada. **Selector que não casa nada** → pare e escale; não fall-back pra full-page silenciosamente (isso é fabricação de escopo).
+1. **INSPECT** the live URL (full-page or selector-scoped) — capture tokens, screenshot, and DOM tree.
+2. **BUILD** the section in HTML/CSS/JS with defensive specificity, mobile-first, no fabrication.
+3. **RENDER** the built fragment locally with Playwright at the same mobile viewport, with a simulated theme reset injected.
+4. **DIFF** the rendered screenshot against the reference (live) screenshot. If `diff% < threshold` → DONE. If not → feed the diff back into BUILD as `fixHints` and loop.
 
----
-
-## Architectural decision: how to invoke sub-skills
-
-**Decision: hybrid — `Bash` para skills determinísticas, `Skill` tool para o composer.** (Mesmo padrão do `/build-page` e `/build-site`.)
-
-| Sub-skill | Invocation | Why |
-| --- | --- | --- |
-| `sb-inspect-live` | **Bash** → `node .claude/skills/sb-inspect-live/scripts/inspect-live.mjs ...` | 95%+ deterministic. Aceita `--selector <css>` nativamente — escopo limitado ao elemento + descendentes. |
-| `sb-extract-assets` | **Bash** → `node .claude/skills/sb-extract-assets/scripts/extract-assets.mjs ...` | Pure download + sanitize + dedupe. **`inspection.imgUrls` já vem filtrado pelo selector** — extract roda nessa lista enxuta. |
-| `sb-build-wp` / `sb-build-shopify` | **Skill** tool → `Skill(skill="sb-build-wp", args="...")` | A composição é criativa. O skill SKILL.md + `references/wp-build-rules.md` é o manual do LLM. Bash não compõe. |
-| `sb-validate-static-render` | **Bash** → `node .claude/skills/sb-validate-static-render/scripts/validate-static-render.mjs ...` | Headless render + token probe. Fully scripted. |
-| `sb-test-interactivity` | **Bash** → `node .claude/skills/sb-test-interactivity/scripts/test-interactivity.mjs ...` | Headless behavioral probe (aria-controls / details / dialog). Diagnostic gate — `passed:false` vira warning, não bloqueia. |
-| `sb-compare-visual` | **Bash** → `node .claude/skills/sb-compare-visual/scripts/compare-visual.mjs ...` | pixelmatch + token diff. Pure determinismo. |
-| `sb-review-checks` | **Bash** → `node .claude/skills/sb-review-checks/scripts/review-checks.mjs ...` | cheerio + regex. Pure determinismo. `candidateFix` strings são contrato — forward verbatim. |
-
-**Decision sobre reuso da lógica de `/build-page`:** orchestration loop interno reusando os mesmos Bash/Skill calls. **Não invoque `/build-page` via Task tool e não delegue pra subagente** — duplicaria contexto, cobraria 2× tokens e o `/clip-section` é mais simples (sem section-type → subfolder routing, sem `clean/home` vs `clean/pdp`, etc.). Orchestre direto neste arquivo.
-
----
-
-## Tool dependencies
-
-- `Bash` — orquestrar, parsear JSON via `jq` ou shell, rodar os `.mjs`, mkdir, ler config
-- `Read` — carregar `.claude/sb-config.yaml`, memory files, fragmento buildado
-- `Write` — escrever `report.html`, `decisions.md`, anti-patterns auto-aprendidos
-- `Edit` — atualização cirúrgica em `report.html` entre iterações
-- `Skill` — invocar `sb-build-wp` / `sb-build-shopify`
-- `WebFetch` — opcional, sanity-check do URL antes de lançar Playwright
-
-NÃO use o `Agent` tool pra delegar o workflow — o orchestrator fica na main conversation.
-
----
+When you skip step 3+4, your fragment "viaja" — it diverges from the live without you noticing. This is the lesson from prior iterations.
 
 ## Inputs (parse from `ARGUMENTS:`)
 
-O texto após `ARGUMENTS:` contém a entrada do usuário. Extraia:
-
 | Flag | Required | Default | Behavior |
-| --- | --- | --- | --- |
-| `<URL>` (positional, primeiro) | yes | — | URL absoluta da página que contém a section. Se ausente, pare e pergunte. |
-| `<selector>` (positional, segundo) | yes | — | CSS selector do elemento a clonar. Se ausente, pare e pergunte. **Validação mínima** (Step 0.3): não-vazio depois de trim, sem `\n`/`\r`/`\t`, e com pelo menos um caractere de selector válido (`.` `#` `[` letra). Se inválido, pare com explicação. |
-| `--target wp\|shopify` | no | `default_target` do `.claude/sb-config.yaml`, fallback `wp` | Roteia pro `sb-build-wp` (`wp`) ou `sb-build-shopify` (`shopify`). Se `shopify` foi pedido e a skill não existe (cheque `.claude/skills/sb-build-shopify/SKILL.md`), pare e diga. |
-| `--project-name <slug>` | no | auto-derivado do hostname (Step 0.4) | Override do nome do projeto. Útil pra branch experiments (ex: `--project-name lojax-clones`). |
-| `--no-auto-correct` | no | false | Escala no primeiro decision-matrix que pediria loop. |
-| `--dry-run` | no | false | Roda inspect + extract + plan-summary, **não builda**. Imprime sumário (selector → assets que seriam baixados → estimativa de complexidade) e sai. |
+|---|---|---|---|
+| `<URL>` (positional) | yes | — | Absolute URL of the live page containing the section. |
+| `--selector <css>` | no | full page | CSS selector to scope the section. Without it, treat the entire page as one section. |
+| `--target wp\|shopify` | no | `wp` from config | Routes to `sb-build-wp` or `sb-build-shopify`. |
+| `--project-name <slug>` | no | hostname-derived | Output folder name. |
+| `--max-iterations <n>` | no | 2 | Cap on build→render→diff loop. After hitting the cap, ship the best attempt + a TODO for manual review. |
+| `--diff-threshold <pct>` | no | from config (default 10) | Diff % below which the section is considered "matching". |
 
-Flag desconhecida → ignore com warning de uma linha. Não erre.
+## Output folder structure
 
-**Disambiguação importante:** seletores podem começar com `-` (ex: `-mod-hero`) e confundir o parser de flags. Trate o segundo argumento posicional como literal antes de tentar parsear flags. Heurística: tudo entre o URL e a primeira ocorrência de `--<flag>` que case `--target|--project-name|--no-auto-correct|--dry-run` é o selector. Se o selector tem espaços (ex: `.section .hero h1`), o usuário precisa quotar — documente isso na mensagem de erro quando o parse falhar.
+```
+{output_folder}/{project-slug}/sections/{section-slug}/
+├── reference.png        — live screenshot (from sb-inspect-live)
+├── tokens.json          — typography, colors, layout tokens (from sb-inspect-live)
+├── inspection.json      — full inspection bundle (DOM, imgUrls, sectionCrops if multi-section page)
+├── assets-map.json      — URL → localPath (from sb-extract-assets)
+├── section.html         — the cloned fragment (paste-ready)
+├── rendered.png         — local render of section.html (from sb-validate-static-render)
+└── diff.json            — pixel + token diff vs reference.png (from sb-compare-visual)
+```
 
----
+When the loop converges, `section.html` matches `reference.png` within threshold. If the loop runs out of iterations, the best attempt is preserved with `diff.json` capturing the residual diff so the user can manually adjust.
 
-## Step 0 — Config + memory + selector validation
-
-1. **Load config.** Read `.claude/sb-config.yaml` se existir. Defaults quando ausente ou key faltando:
-
-   ```yaml
-   output_folder: ./sb-output
-   default_target: wp
-   default_viewport: 390
-   auto_correct_max_iterations: 2
-   diff_threshold_percent: 10
-   strip_metadata: true
-   ```
-
-   Não auto-crie o arquivo — o installer (item #16 do roadmap) é dono disso. Apenas opere com defaults.
-
-2. **Memory cascade** (pattern #21). Mesma lógica do `/build-page`: plugin → per-user → bundled fallback.
-   - **Plugin (versioned)**: `.claude/skills/sb-shared/memory/{anti-patterns,patterns,fixes,design-knowledge}.md` — skip silencioso se ausente.
-   - **Per-user (auto-learned)**: `~/.claude/similarbuild-memory/{anti-patterns,patterns,fixes}.md` — skip silencioso se ausente. Não crie o diretório eagerly; só se Step 12 tiver algo pra salvar.
-   - **Bundled fallback**: cada sub-skill carrega o seu — não é seu trabalho.
-
-   Hold em working memory pra (a) filtrar subset relevante por section-type quando invocar `sb-build-{wp,shopify}` (lean context discipline — pattern #3), e (b) reconhecer pattern novo no auto-learn (Step 12).
-
-   **Filtro pra builder:** quando invocar `sb-build-wp`/`sb-build-shopify`, NÃO passe a memory cascade inteira. Passe só:
-   - Patterns cujo `sectionType` case com `inspection.sectionType` (ou siblings próximos).
-   - Anti-patterns prováveis pro section-type detectado.
-   - Design-knowledge tagged pro target (`wp` ou `shopify`) — máximo 1-2 KB curado.
-
-   Se nada curado ainda (early framework), skip — o `references/` bundled da skill é suficiente.
-
-3. **Selector validation (mínima).** Pegue o selector raw, trim. Rejeite e pare com mensagem clara se:
-   - Vazio depois do trim.
-   - Contém `\n`, `\r`, `\t`, ou caractere de controle (`< 0x20`).
-   - Maior que 200 chars (defesa contra paste acidental de bloco).
-   - Não contém nenhum de: letra, dígito, `.`, `#`, `[`, `*`, `:` (algo tem que se parecer com selector).
-
-   Mensagem de erro padrão: `"Selector inválido: '{selector}'. Esperado CSS selector como '.hero', '#main-section', 'section.hero[data-id=foo]'. Selectors com espaço precisam ser quotados na linha de comando."` Pare.
-
-4. **Project slug.**
-   - Se `--project-name <slug>` foi passado: use verbatim (valide URL-safe; warn se não).
-   - Senão: derive do hostname.
-     - Parse hostname (ex: `https://www.lojax.com/path?q=x` → `www.lojax.com`).
-     - Strip `www.`, strip subdomain líder só quando for `www`/`m`/`store`/`shop`.
-     - Strip TLD (último `.xxx` ou `.xxx.yy` pra TLDs compostos conhecidos como `.com.br`, `.co.uk`).
-     - Lowercase, replace não-`[a-z0-9]` por `-`, collapse repeats, trim leading/trailing `-`.
-     - Exemplos: `https://lojax.com` → `lojax`; `https://www.exemplo.com.br/x` → `exemplo`.
-   - Hold como `{project-slug}` pelo resto do run.
-
-5. **Section slug** (derivado do selector — usado pro nome do arquivo final).
-   - Strip whitespace.
-   - Se começa com `.`: drop o `.`. Ex: `.hero-section` → `hero-section`.
-   - Se começa com `#`: drop o `#`. Ex: `#testimonials` → `testimonials`.
-   - Se começa com tag (ex: `section.hero`): pega a primeira classe/id depois da tag (ex: `section.hero` → `hero`); se não tem nenhuma, pega a tag (ex: `main` → `main`).
-   - Selectors compostos/complexos (`.foo > .bar`, `[data-x=y]`, `:nth-child(2)`): replace tudo que não for `[a-z0-9]` por `-`, collapse repeats, trim, lowercase, max 60 chars.
-   - Se o resultado fica vazio ou só `-` depois disso, fallback pra `section-{ts}` (UNIX seconds). Logue.
-   - Hold como `{section-slug}`.
-
-6. **Project structure.** Compute `{project-root}/{output_folder}/{project-slug}/` e garanta os subdirs (mkdir -p, idempotente):
-
-   ```
-   {output_folder}/{project-slug}/
-   ├── clean/
-   │   └── sections/             ← saída do /clip-section vai aqui (sempre)
-   ├── assets/                   ← content-hash images (compartilhado se a pasta já existir)
-   ├── reports/
-   │   ├── diffs/
-   │   └── validations/
-   └── .sb-memory/               ← project-local memory (decisions, etc.)
-   ```
-
-   Nunca escreva fora de `{project-slug}/` (isolation guarantee — pattern #15).
-
-   Nota: se o projeto já existe (rerun ou compartilhado com `/build-page`), o `assets/` é reusado naturalmente — `sb-extract-assets` deduplica por content-hash via `--existing-assets-dir`.
+## Steps (the exact flow)
 
----
+### Step 0 — Config + project slug
 
-## Step 1 — Inspect live com selector (Bash)
+1. Load `.claude/sb-config.yaml` (fallbacks: `output_folder=./sb-output`, `default_target=wp`, `default_viewport=390`, `diff_threshold_percent=10`, `auto_correct_max_iterations=2`).
+2. Derive `{project-slug}` from hostname (strip `www.`/`m.`/`store.`/`shop.` + TLD, kebab-case) unless `--project-name` is provided.
+3. Derive `{section-slug}` from the selector (sanitized) or from `sectionType` returned by inspect. When no selector, use `home` / `pdp-<slug>` / etc.
+
+### Step 1 — Inspect (Bash)
 
 ```bash
 node .claude/skills/sb-inspect-live/scripts/inspect-live.mjs \
   --url "{URL}" \
-  --selector "{selector}" \
   --viewport-width {default_viewport} \
   --viewport-height 844 \
-  --output-dir "{output_folder}/{project-slug}/.sb-memory/inspect-{section-slug}-{ts}"
+  --output-dir "{output_folder}/{project-slug}/sections/{section-slug}" \
+  [--selector "{selector}"]
 ```
 
-Onde `{ts}` é UNIX seconds pra rerun não clobber. Capture stdout JSON → `inspection`.
-
-**O que muda com `--selector`:**
-- `inspection.sectionBoundingBox === null` (a screenshot já É só o elemento — não há "bbox dentro de página inteira" pra recortar).
-- `inspection.dom`, `inspection.imgUrls`, `inspection.tokens`, `inspection.pseudoElements` ficam todos escopados ao elemento + descendentes.
-- `inspection.sectionType` reflete o tipo detectado dentro do escopo do selector (ou cai pro fallback do inspector).
+The skill writes `screenshot.png` (the reference — rename to `reference.png` afterwards) and `inspection.json` (containing `tokens`, `dom`, `imgUrls`, `sectionCrops[]` when multi-section).
 
-**Branch:**
-- Exit non-zero → surface stderr ao usuário, pare. Se mencionar `playwright`, sugira `npx playwright install chromium`.
-- `inspection.widgetBlocked === true` → pare. "A página live retornou bot-challenge / Cloudflare wall. Tente outro URL, ou abra no browser e me passe o HTML renderizado." NÃO continue.
-- `inspection.dom` empty mas `widgetBlocked: false` → pare. **Provavelmente o seletor não casou nada.** Mensagem: `"Selector '{selector}' não casou nenhum elemento em {URL}. Verifique o seletor (use DevTools → Elements → Copy → Copy selector como sanity check), ou tente um seletor mais frouxo."` Pare. **Não fall-back pra full-page** — seria fabricar escopo (não-negociável #4).
-- Senão, hold `{inspection-path}` (path pro `inspection.json` salvo no `--output-dir`) e `{inspection-screenshot}` (path pra `screenshot.png` no mesmo dir).
+```bash
+mv "{section-dir}/screenshot.png" "{section-dir}/reference.png"
+jq '.tokens' "{section-dir}/inspection.json" > "{section-dir}/tokens.json"
+```
 
-**Lean context** — só `--url`, `--selector`, viewport, output-dir. Sem memória, sem patterns. Disciplina.
+If `inspection.widgetBlocked` is true → halt and surface to user. Don't compose from a blocked page.
 
----
-
-## Step 2 — Extract assets (Bash)
+### Step 2 — Extract assets (Bash)
 
 ```bash
 node .claude/skills/sb-extract-assets/scripts/extract-assets.mjs \
-  --inspection-path "{inspection-path}" \
+  --inspection-path "{section-dir}/inspection.json" \
   --output-dir "{output_folder}/{project-slug}/assets" \
   --target "{target}" \
   --existing-assets-dir "{output_folder}/{project-slug}/assets"
 ```
 
-(`--existing-assets-dir` apontando pro mesmo dir é intencional — o dedupe scan lê do disco.)
-
-Capture stdout JSON → `assetsMap`. Path persistido → `{assets-map-path}` (script grava `assets-map.json` no `--output-dir`).
+Produces `assets-map.json` next to `inspection.json`. Failed assets become `<!-- TODO: asset failed download -->` placeholders in the build — never fabricate URLs.
 
-**Crítico do `/clip-section`:** `inspection.imgUrls` JÁ vem filtrado pelo escopo do selector — o extract baixa só assets dentro da seção. Não tente filtrar mais nada.
+### Step 3 — Build (Skill)
 
-**Branch:**
-- Exit non-zero → surface stderr, pare.
-- `assetsMap.failed[]` não-vazio → NÃO pare. Forwarde pro builder; o builder decide por asset (drop decorativo, placeholder hero, nunca fabrica).
-- `assetsMap.assets[].strippedMetadata === false` em alguma entrada → log warning no report; continue.
-
-**Lean context** — só URL list (via `--inspection-path`) e output dir. Nada mais.
-
-**Dry-run check:** se `--dry-run` foi passado, AGORA é o ponto de saída. Imprima:
-
-```
-🔍 Dry-run /clip-section
-  URL:        {URL}
-  Selector:   {selector}
-  Section:    {section-slug} (type: {inspection.sectionType})
-  Target:     {target}
-  Assets:     {N total} ({K cached, J novos, F failed})
-  Saída prevista: {output_folder}/{project-slug}/clean/sections/{section-slug}.{ext}
-```
-
-Escreva `reports/plan-{section-slug}-{ts}.md` com o mesmo conteúdo + lista detalhada dos assets. Pare. NÃO continue pra Step 3.
-
----
-
-## Step 3 — Build (Skill)
-
-Decida a skill: `sb-build-wp` se `target === wp`, senão `sb-build-shopify`. Compute `{output-path}`:
-
-- WP: `{output_folder}/{project-slug}/clean/sections/{section-slug}.html`
-- Shopify: `{output_folder}/{project-slug}/clean/sections/{section-slug}.liquid`
-
-Filtre o memory cascade pelo subset relevante (per Step 0.2) → `{designKnowledgeSubset}` e `{patternsSubset}`.
-
-Invoque via **Skill tool**:
+Iteration counter starts at 1.
 
 ```
 Skill(
-  skill="sb-build-wp",
-  args="inspection={inspection-path} assets-map={assets-map-path} output-path={output-path} preset=wp-elementor"
+  skill="sb-build-wp",      # or sb-build-shopify
+  args="inspection={section-dir}/inspection.json assets-map={section-dir}/assets-map.json output-path={section-dir}/section.html preset=wp-elementor reference-image={section-dir}/reference.png"
 )
 ```
 
-Pra Shopify:
-```
-Skill(
-  skill="sb-build-shopify",
-  args="inspection={inspection-path} assets-map={assets-map-path} output-path={output-path} preset=shopify-section"
-)
-```
-
-Se tiver `{designKnowledgeSubset}`/`{patternsSubset}` curados, inclua como args extras (`design-knowledge-inline=<base64-or-path>`); senão omita e deixe o skill usar bundled defaults.
-
-**O skill retorna:** path absoluto do arquivo escrito, validator report (errors/warnings), e nota de uma linha sobre o pattern escolhido. Não peça o conteúdo do arquivo de volta — o `sb-validate-static-render` abre.
+The composer reads the reference screenshot + tokens + inspection corpus, builds the fragment following `wp-build-rules.md` (defensive specificity, mobile-first, no fabrication, image-first when a region is dominated by `<img>`), validates with `build-wp.mjs validate --inspection-path` (catches fabricated literals), writes the file.
 
-Se o validator interno do skill retornar erros que ele não conseguiu corrigir → surface ao usuário; isso é defeito do builder, não caso de auto-correct.
+On retry iterations, pass `previous-html-path={section-dir}/section.html` + `fix-hints-path={section-dir}/diff.json`.
 
----
-
-## Step 4 — Validate render (Bash)
+### Step 4 — Render (Bash)
 
 ```bash
 node .claude/skills/sb-validate-static-render/scripts/validate-static-render.mjs \
-  --file "{output-path}" \
+  --file "{section-dir}/section.html" \
   --preset "{preset}" \
-  --output-dir "{output_folder}/{project-slug}/reports/validations/{section-slug}-{iteration}" \
+  --output-dir "{section-dir}" \
   --viewport-width {default_viewport} \
   --viewport-height 844
 ```
 
-Onde `{preset}` é `wp-elementor` ou `shopify-section`, e `{iteration}` é `0` no primeiro build, `1`/`2` em retries.
-
-Capture stdout JSON → `render`. Hold `{render-screenshot}` (`render.screenshot`) e `{render-json-path}` (path pro `render.json` salvo).
+Produces `rendered.png` + `render.json` (geometry, token probe). If render fails (tiny screenshot, JS error during page load) → mark this iteration failed, retry build with the error as fixHint.
 
-**Branch:**
-- Exit non-zero → se stderr menciona `liquidjs` ou `playwright` faltando, surface install hint; senão pass-through e pare.
-- `render.warnings[]` inclui `tiny-screenshot` → trate como hard failure desta iteração (build não renderizou). Skip Steps 5–7 e route pra Step 9 (auto-correct loop) se budget permite, senão Step 10 (escala).
-- `render.geometry.viewportOverflow === true` → flag pro comparator (high-severity hint), e ALSO suprima `--crop-build-bbox` no Step 5 (bbox subestimaria com overflow). Continue pra Step 5.
-- Senão, continue.
-
-**Lean context** — file + preset + output-dir + viewport. O skill carrega seu próprio preset YAML.
-
----
-
-## Step 4-bis — Test interactivity (Bash, diagnostic gate)
-
-```bash
-node .claude/skills/sb-test-interactivity/scripts/test-interactivity.mjs \
-  --file "{output-path}" \
-  --preset "{preset}" \
-  --output-dir "{output_folder}/{project-slug}/reports/validations/{section-slug}-{iteration}"
-```
-
-Capture `interactivity-report.json` (mesmo dir do `validate-static-render`).
-
-**Modo diagnóstico (não-blocker):**
-
-- Exit `!= 0` → log stderr verbatim e continue pra Step 5 sem warning. Hint comum: `playwright`/chromium faltando — sugira `npx playwright install chromium`. Não escala.
-- Exit `0` AND `passed === true` → silently proceed. Sem warning, sem mudança de status.
-- Exit `0` AND `passed === false`:
-  - **Append** ao `interactivityWarnings` array (NÃO single-shot overwrite): `interactivityWarnings.push({ iteration: <n>, tests: report.tests.filter(t => !t.passed) })`. Iterations com 0 warnings NÃO appende. Histórico cross-iter preservado — útil pro success/escalation path (Steps 8/10) que renderiza section em `report.html` resumindo qual iter viu qual break.
-  - Status badge da section build ganha sufixo `+!interactive` (e.g. `✅+!interactive`). Calculado dinamicamente: applies se `interactivityWarnings.length > 0` em qualquer iter.
-  - **Status final permanece o que a decision matrix decidir** (Step 7). Sem promoção pra ❌. Skill é diagnóstica, não gatekeeper — política locked em G2 spec change log.
-  - Continue pra Step 5.
-
-**Por que diagnostic e não blocker:** `sb-test-interactivity` é skill nova (G2). False-positives em early adoption são esperados (web components fora da whitelist canônica, drawers com transições atípicas). Promover a hard gate antes da skill amadurecer geraria fricção em builds bons. Warning explícito + `interactivityWarnings` no report dá visibilidade sem bloquear. Mudança pra blocker é decisão de spec própria (G8+).
-
----
-
-## Step 5 — Compare visual (Bash)
+### Step 5 — Diff (Bash)
 
 ```bash
 node .claude/skills/sb-compare-visual/scripts/compare-visual.mjs \
-  --live-screenshot "{inspection-screenshot}" \
-  --build-screenshot "{render-screenshot}" \
-  --output-dir "{output_folder}/{project-slug}/reports/diffs/{section-slug}-{iteration}" \
-  --tokens-live "{inspection-path}" \
-  --tokens-build "{render-json-path}" \
-  --threshold {diff_threshold_percent} \
-  [--crop-build-bbox "{x},{y},{w},{h}"]
+  --live-screenshot "{section-dir}/reference.png" \
+  --build-screenshot "{section-dir}/rendered.png" \
+  --output-dir "{section-dir}" \
+  --tokens-live "{section-dir}/inspection.json" \
+  --tokens-build "{section-dir}/render.json" \
+  --threshold {diff_threshold_percent}
 ```
 
-**Scope-aligned diff (anti-pattern #10 + Pattern #27) — caso simplificado do `/clip-section`:**
-
-- **`--crop-live-bbox`** — **NÃO passe.** Como o inspector rodou com `--selector`, `inspection.sectionBoundingBox === null` por design (a screenshot live JÁ é element-only). Adicionar crop aqui seria operação inválida.
-
-- **`--crop-build-bbox`** — passe `render.geometry.sections[0].bbox.{x,y,w,h}` (ou `render.geometry.probeRoot.bbox` se `sections[]` vazio) quando:
-  - `render.geometry.viewportOverflow === false` (senão bbox subestima e cliparia overflow real), AND
-  - O bbox da section é **menor que a altura do viewport capturado** por margem não-trivial (>10% menor). Sections que enchem o viewport não se beneficiam.
-
-  Pattern #27 ainda aplica do lado do build — se a section em mobile fica em 390×507 dentro de viewport 390×844, sem o crop sobra 337px de espaço branco que infla diff% gratuitamente.
-
-DPR flags default `3` (matches `sb-inspect-live` iPhone 14 + `sb-validate-static-render` `deviceScaleFactor=3`, Pattern #22). Não override.
-
-Capture stdout JSON → `compare`. Note path do `report.json` persistido → `{compare-report-path}`.
+Produces `diff.json` (pixel diff%, structured diffs) and `diff-map.png` (red-overlay highlighting divergent regions).
 
-**Não branche no exit ainda.** `review-checks` é o ground truth pra "o build é estruturalmente sound?" (Pattern #28). Capture `compare.{passed, diffPercent}` e siga pra Step 6 — a decision matrix da Step 7 precisa de ambos compare AND review.
+### Step 6 — Decide
 
-- `1` → script error. Surface stderr, pare.
-- `2` → invalid args. Bug neste orchestrator — fix the call.
+- `diff.json.passed === true` (diff < threshold) → **DONE**. Print success + paths. Section is ready to paste.
+- `diff.json.passed === false` AND `iteration < max_iterations` → loop back to Step 3 with `diff.json` as fixHints. Increment iteration.
+- `diff.json.passed === false` AND `iteration >= max_iterations` → **SHIP WITH WARNING**. The fragment is the best attempt; `diff.json` documents the residual gaps. Print a warning + the residual diff% so the user can decide whether to manually tweak or re-run with a tighter selector.
 
-**Lean context** — dois screenshot paths + dois token JSONs + threshold + opcional bbox. Só isso.
+### Step 7 — Print summary
 
----
-
-## Step 6 — Review checks (Bash, sempre roda — Pattern #28)
-
-```bash
-node .claude/skills/sb-review-checks/scripts/review-checks.mjs \
-  --file "{output-path}" \
-  --preset "{preset}" \
-  --output-dir "{output_folder}/{project-slug}/reports/validations/{section-slug}-{iteration}" \
-  --compare-diffs "{compare-report-path}"
 ```
+🏁 /clip-section {URL} → {section-dir}/
 
-Capture stdout JSON → `review`. Note `review.passed` e o array `violations[]` — ordenado high → medium → low, com `correlatedDiff` setado em entries que sobrepõem high-severity visual diff.
+  Section: {section-slug}
+  Iterations: {n}
+  Diff%: {final-diff-pct}
+  Status: ✅ matching | ⚠️ residual diff above threshold
 
-**Por que sempre roda (Pattern #28):** review-checks é auditor puro-determinístico (cheerio + regex, sem chromium, ~0s overhead). Compare-visual mede *visual drift*; review-checks mede *structural soundness*. São ortogonais — um build com `100vh` é estruturalmente quebrado mesmo se o diff cair baixo; um build com HTML perfeito ainda pode driftar visual por font rendering. Rodar review-checks unconditionally faz a Step 7 disparar em sinal, não vibes.
-
-**Branch no exit code:**
-- `0` → `review.passed === true`. Continue pra Step 7.
-- `3` → `review.passed === false`, violations presentes. Continue pra Step 7.
-- `1`/`2` → surface stderr, pare.
-
-**Lean context** — file + preset + output-dir + compare report path. Nada mais.
-
----
+  Files:
+    section.html  — paste into Elementor Custom HTML / Shopify Liquid
+    reference.png — live screenshot (your visual ground truth)
+    rendered.png  — local render (what you'll see when pasted)
+    diff.json     — structured diff vs reference
 
-## Step 7 — Decision matrix (Pattern #28)
-
-**Pre-check 0 (coverage gate, runs FIRST):**
-
-Para `/clip-section`, "live" é o elemento alvo do selector. Calcule contra schema **real** do `sb-inspect-live`:
-
-```
-buildHeight    = render.geometry.totalHeight        # primary: from sb-validate-static-render
-liveMainHeight = inspection.sectionBoundingBox.h    # primary: bbox do selector target (set when --selector é passed)
-                 || inspection.dom[0].bbox.h         # fallback 1: root walked node bbox (warn — clip pode ser menor que a página)
-                 || (walk inspection.dom recursively, collect classified-sections bboxes,
-                     return max(s.bbox.y + s.bbox.h) - min(s.bbox.y))
-                                                    # fallback 2: classified sections span (warn)
-coverageRatio  = buildHeight / liveMainHeight
-```
-
-`inspection.sectionBoundingBox` é o bbox do selector alvo (schema em `inspect-live.mjs:163,1219`). Quando `--selector` é passed, este field é populated. Sem selector, fica `null` e cai pros fallbacks.
-
-If `buildHeight` is missing → HALT com erro `[clip-section] FATAL: render.geometry.totalHeight missing`.
-If `liveMainHeight` fell back → log warning ao user em `report.html` notes.
-If `liveMainHeight < 100` → log warn `[clip-section] WARN: liveMainHeight < 100, coverage gate skipped`; skip; persist `coverage.skippedReason = 'degenerate-height'`.
-If `inspection.dom[]` empty AND no classified sections → log warn `[clip-section] WARN: coverage gate skipped — empty inspection.dom`; skip; `coverage = null`.
-
-**Tier triage:**
-
-| Range | Status | Ação |
-| --- | --- | --- |
-| `< 0.40` | ❌ **incomplete** | Status: `"incomplete — built {ratio*100:.0f}% of source clip"`. Vai pra Step 9 (auto-correct loop) se budget permite; existing review-derived fixHints feed back to composer. **NO new EXTENSION marker** — Step 9 já consome `review.violations[]` canonical. Coverage `< 0.40` apenas força ❌ no matrix override. |
-| `0.40 — 0.85` | ⚠️ **partial** | Status: `"partial — built {ratio*100:.0f}%"`. Prossegue pra matriz abaixo (não bypassa). Coverage warning sobrevive como overlay. |
-| `>= 0.85` | (proceed) | Coverage OK. Matriz roda silenciosamente. |
-
-Persist `coverage = { buildHeight, liveMainHeight, ratio, source: 'sectionBoundingBox'|'rootBbox'|'sectionsSpan', missingSections?: [...], skippedReason?: <string> }` em report. `missingSections` (quando `ratio < 0.85`): walk `inspection.dom` recursivamente, collect classified-section children do selector cujo `bbox.y >= buildHeight`.
-
-**Existing matrix (roda só se coverage gate não routou pra ❌):**
-
-Você tem `compare.passed` E `review.passed` agora. Aplique:
-
-| `review.passed` | `compare.passed` | Ação                                                                                          |
-| --------------- | ---------------- | --------------------------------------------------------------------------------------------- |
-| true            | true             | ✅ **Ship.** Vai pra Step 8 (success path).                                                    |
-| false           | true             | ⚠️ **Escala com structural warning.** Vai pra Step 10. Build *parece* certo mas `violations[]` carrega defeitos escondidos (a11y, perf, anti-patterns) que o user precisa ver. Não auto-loop — review-checks não é trigger de auto-correct quando visual já casou. |
-| true            | false            | ⚠️ **Escala (visual drift, sem fix actionable).** Vai pra Step 10. Não tem fixHints pra realimentar — patch LLM-side de raw `structuredDiffs` é chute. Surface ao user com diff map. |
-| false           | false            | 🔄 **Auto-correct loop.** Vai pra Step 9. fixHints do review podem dirigir `sb-build-{wp,shopify}` a patch cirúrgico. Itera até flip ou exhaust. |
-
-**Dois pre-checks antes da matriz disparar:**
-1. Se `--no-auto-correct` foi passado e qualquer célula rotearia pra Step 9 → reroute pra Step 10 (escala imediato).
-2. Se `iteration >= auto_correct_max_iterations` (default 2) e a matriz rotearia pra Step 9 → reroute pra Step 10 (budget exhausted).
-3. Se `violations[]` em `iteration N` é IDÊNTICO a `iteration N-1` → fixHint não está pegando. Reroute pra Step 10 mesmo se há budget. (Não rodar 3ª iteração quando a 2ª foi inútil.)
-
-A matriz substitui o velho heurístico "diff>50 catastrophic = skip loop". Aquele heurístico mis-firava quando build limpo tinha diff% alto por scope mismatch do comparator (Pattern #27). A matriz usa review-checks como ground truth — se o build é estruturalmente sound mas drifta visual, é território de escalação de qualquer jeito, sem precisar de threshold de diff%.
-
----
-
-## Step 8 — Success path
-
-Você só chega aqui quando `review.passed === true` AND `compare.passed === true`.
-
-1. Write/update `{output_folder}/{project-slug}/reports/index.html` com a entrada da section: status ✅, diff %, screenshot side-by-side (live element-only vs build), link pro arquivo, tempo decorrido, contagem de iterações. Use o report existente se presente (read → modify → write) pra que múltiplos runs (`/build-page` + `/clip-section` no mesmo project-slug) acumulem; crie do zero se ausente.
-
-2. Append uma linha de decision record em `{output_folder}/{project-slug}/.sb-memory/decisions.md`:
-   ```
-   {ts} | /clip-section {URL} {selector} | target={target} | section-slug={section-slug} | iterations={n} | diff={diff_percent}% | ✅
-   ```
-
-3. **Auto-learn check.** Per-iteration prompt OK aqui — `/clip-section` é single-shot, não batch (Pattern #37 aplicado: batched só em batch flows). Só dispare se `auto_correct_iterations_used > 0` AND auto-correct destravou (i.e. um `sb-review-checks` `candidateFix` realmente desbloqueou). Inspecione o fix que fechou o diff:
-   - É generalizável além desta section? (Nomeia pattern não coberto pela memory cascade carregada?)
-   - Se sim: pergunte UMA vez ao usuário, em português, se persiste em `~/.claude/similarbuild-memory/anti-patterns.md`. Formato: `[s/n/sempre/nunca]`. No `sempre`, flip um one-time hint pra auto-salvar sem perguntar na próxima sessão (track em `.sb-memory/decisions.md`).
-   - Confirmação → append entry (cria diretório/arquivo se faltam) com: data, anti-pattern name, fix recipe, source URL, selector, section type.
-   - `n`/`nunca` → não salva. `nunca` também append `auto_learn_disabled: true` em `.sb-memory/decisions.md`.
-   - Skip silencioso se `auto_learn_disabled: true` já está em `decisions.md`.
-
-4. Imprima o sumário final ao usuário em português:
-   ```
-   ✅ section "{section-slug}" de {URL} → {output-path}
-   selector: {selector} (type: {inspection.sectionType})
-   diff: {diff_percent}% (threshold {threshold}%) | iterações: {n}
-   report: {output_folder}/{project-slug}/reports/index.html
-
-   Pra instalar: cole {output-path} como widget HTML / section Liquid no destino.
-   ```
-
-5. Pare.
-
----
-
-## Step 9 — Auto-correct loop body
-
-Você só chega aqui da matriz da Step 7 quando **ambos** `review.passed === false` AND `compare.passed === false`. Os pre-checks (no-auto-correct, budget exhausted, violations idênticas) e a hard-fail do validate (`tiny-screenshot`) todos roteiam pra Step 10.
-
-`review.violations[]` está em mão da Step 6 — fixHints pra realimentar o builder.
-
-### Step 9a — Re-build com fixHints (Skill)
-
-**Crítico: violations passam verbatim.** Per o brief: `fixHints` do `sb-review-checks` vão DIRETO pro `sb-build-{wp,shopify}` — sem reformulação, interpretação, modificação. As `candidateFix` strings SÃO o contrato.
-
-```
-Skill(
-  skill="sb-build-wp",
-  args="inspection={inspection-path} assets-map={assets-map-path} output-path={output-path} preset=wp-elementor previous-html-path={output-path} fix-hints-path={review-report-path}"
-)
-```
-
-(`sb-build-shopify` quando `target === shopify`, com `preset=shopify-section`.)
-
-O skill lê `previousHtmlPath`, aplica fixHints cirurgicamente, escreve em `outputPath`. Iteration counter `+= 1`.
-
-### Step 9b — Re-validate, re-compare, re-review
-
-Volta pra Step 4 com o arquivo novo (ainda em `{output-path}` — o skill sobrescreveu) e o `{iteration}` novo. Depois Step 5, depois Step 6, depois a matriz da Step 7 de novo.
-
-Se a matriz flipa pra ✅ → Step 8 (success), agora reportando contagem de iterações.
-Se a matriz roteia pra ⚠️ (review passou, compare falhou) → Step 10 (sem mais fixHints actionable).
-Se fica em 🔄 → loop de novo da Step 9 (decrementa budget).
-
-**O loop é fechado (pattern #20):** sob nenhuma circunstância pergunte ao usuário no meio do loop. Só escala depois de exhaust.
-
----
-
-## Step 10 — Escalation (auto-correct exhausted, ou `--no-auto-correct`, ou structural warning)
-
-Você só chega aqui quando o budget acabou ou a matriz roteou pra ⚠️. Seja honesto:
-
-1. Write/update `reports/index.html` com status ⚠️ pra esta section, incluindo: último diff %, top 5 `structuredDiffs` do compare report mais recente, `violations[]` do review report mais recente, links pra todas as screenshots de iteração e diff maps.
-
-2. Append decision record marcando esta section como ESCALATED com URL, selector, target, iterations gastas, último diff %, e qual célula da matriz disparou.
-
-3. Imprima ao usuário em português — específico, não vago:
-   ```
-   ⚠️ section "{section-slug}" de {URL} ainda diverge da live após {n} tentativas.
-   selector: {selector}
-   diff: {diff_percent}% (threshold {threshold}%)
-
-   Top diffs visuais (do sb-compare-visual):
-   - {area}: {issue}
-   - ...
-
-   Candidate fixes (do sb-review-checks):
-   - {candidateFix}
-   - ...
-
-   Build atual: {output-path}
-   Diff map: {diff-map-png-path}
-   Report completo: {output_folder}/{project-slug}/reports/index.html
-
-   Próximos passos sugeridos:
-   1. Abra o diff map e o build no destino (Elementor/Shopify) pra inspeção visual.
-   2. Se achar a causa raiz fora do escopo do builder (ex: seletor pegou demais/de menos, asset errado), refine e re-rode com selector mais preciso.
-   3. Se o diff for aceitável (ex: drift de fonte sub-pixel), copie {output-path} pro destino e ignore o aviso.
-   ```
-
-4. Pare. NÃO marque como sucesso. O usuário decide.
-
----
-
-## Failure modes (cross-cutting)
-
-| Symptom | Likely cause | Action |
-| --- | --- | --- |
-| `playwright` missing | First-time setup | Surface stderr da skill verbatim + "Run `npx playwright install chromium` from project root." Pare. |
-| `sharp` / `pixelmatch` / `pngjs` / `cheerio` / `liquidjs` missing | Idem | Surface install hint da skill que falhou. Pare. |
-| `inspection.widgetBlocked: true` | Bot challenge | Pare. Peça URL alternativo ou paste de HTML renderizado. Não fabrique. |
-| `inspection.dom` empty mas `widgetBlocked: false` | **Selector não casou nada** | Pare com mensagem específica: "Selector '{selector}' não casou em {URL}." NÃO fall-back pra full-page (fabricaria escopo). |
-| `assetsMap.failed[]` inclui asset crítico (hero) | Source 404 | Não pare — builder vai usar placeholder cor literal. Note no report e continue. |
-| `sb-build-{wp,shopify}` validator retorna erros após retries internos | Defeito do builder | Surface ao user com path do arquivo + output do validator. Skip validate/compare — não tem o que validar. |
-| Mesmas `violations[]` 2 iterações seguidas | fixHint não pegou — bug do builder ou memory stale | Não rode 3ª iteração mesmo com budget. Escala imediato (Step 7 pre-check #3). |
-| Diff% alto (ex: >50%) mas `review.passed === true` | Drift visual genuíno que LLM não patch de raw diff | Step 7 matrix já trata: `review=true, compare=false` → escala (sem fix actionable). Não reintroduza heurístico `diff>50 catastrophic`. |
-| Selector com espaços não quotados (ex: `/clip-section URL .a .b`) | Argv split | Mensagem da Step 0.3 cobre — peça quote: `/clip-section URL ".a .b"`. |
-
----
-
-## Output structure (recap)
-
-Após um run sucesso em `https://lojax.com .ai-hero --target shopify`:
-
-```
-{output_folder}/lojax/
-├── clean/
-│   └── sections/
-│       └── ai-hero.liquid          ← o deliverable
-├── assets/
-│   └── a3f9b2c14e8d7f01.jpg        ← content-hash, sem metadata (compartilhado se já existir)
-├── reports/
-│   ├── index.html                   ← updated incrementalmente
-│   ├── diffs/ai-hero-0/diff-map.png
-│   └── validations/ai-hero-0/screenshot.png
-└── .sb-memory/
-    ├── inspect-ai-hero-{ts}/inspection.json
-    ├── inspect-ai-hero-{ts}/screenshot.png
-    └── decisions.md
+  Next:
+    Paste section.html into the destination as a Custom HTML widget.
+    If diff% > threshold, open diff-map.png to see what didn't match,
+    edit section.html manually, or re-run /clip-section to retry.
 ```
 
-Nunca escreva fora de `{project-slug}/`. Cross-project asset sharing acontece só via per-user memory em `~/.claude/similarbuild-memory/` (process knowledge, não conteúdo de loja) — e só em confirmação explícita de auto-learn.
+## Failure modes
 
----
-
-## What you do NOT do
-
-- Não rode `sb-crawl-and-list` — esta command é section-only, nem tem conceito de "página seguinte".
-- Não invoque `/build-page` ou `/build-site` via Task tool — orchestre direto.
-- Não pergunte nada ao usuário no meio do flow exceto o auto-learn prompt do Step 8.3 (e só quando aplicável).
-- Não fall-back pra full-page quando o selector não casa — escala (fabricaria escopo).
-- Não reformule, resuma ou interprete `candidateFix` strings — passe verbatim ao builder.
-- Não mostre path do build "ready to ship" antes de Step 4 + 5 confirmarem diff sob threshold.
-- Não passe `--crop-live-bbox` pro `sb-compare-visual` — `inspection.sectionBoundingBox` é null por design quando `--selector` é usado.
-- Não crie `.claude/sb-config.yaml` se faltar — opere com defaults; o installer é dono.
-- Não load `<plugin>/memory/*.md` se ausente — bundled `references/` em cada skill é a working source até item #13 do roadmap.
-- Não tente buildar múltiplos selectors por chamada — single-section é o contrato. Pra múltiplos, o usuário roda o command múltiplas vezes (ou usa `/build-page` se quiser a página inteira).
-
----
+| Symptom | Action |
+|---|---|
+| `inspection.widgetBlocked: true` | Halt. Don't compose from a blocked page. Tell the user the site is behind a bot wall. |
+| Render fails repeatedly (tiny screenshot, JS error) | Mark section ❌ after 2 attempts. Surface the render error. Don't ship a fragment that can't even render locally. |
+| Loop hits max iterations with `diff% > threshold` | Ship best attempt + warning. The user can manually edit section.html or retry. |
+| Composer flags fabrication detected | Loop continues; diff.json passes the fabrication info back as fixHint. |
 
-## Quick start (smoke test path)
-
-Quando este command for primeiro wired-up, smoke test canônico:
-
-```
-/clip-section https://example-store.com .ai-hero --target shopify
-```
+## Non-negotiables (carried from prior iterations)
 
-Esperado: arquivo `{output_folder}/example-store/clean/sections/ai-hero.liquid` em até ~30s, diff sob threshold, decision matrix funcionando, report.html abrindo. Sem crawl, sem checkpoint humano. MVP milestone do `/clip-section`.
+1. **Pixel parity over architecture.** The reference.png is the ground truth. The diff.json is the verdict. Specifications are descriptive, never authoritative.
+2. **Mobile-first always.** Default viewport 390×844 unless explicitly overridden.
+3. **Defensive specificity.** `.scope.scope { ... !important }` on text-critical AND visual-critical properties. The theme will fight you; chained-class beats single-class.
+4. **No `100vh`.** Use `aspect-ratio` for hero proportions. Elementor iframes don't respect viewport units.
+5. **Inline SVG only.** WordPress blocks SVG uploads by default.
+6. **No fabrication.** Emit only what's in the reference screenshot AND/OR the inspection corpus. Unknown literal → TODO comment + placeholder. Never invent.
+7. **Image-first.** When a region is dominated by `<img>`, emit `<img src>` (resolved through assetsMap) — don't reproduce the image's contents in CSS/SVG.
+8. **Render every iteration.** Step 3 without Step 4 is "viajar". Don't ship without the render+diff verdict.