similarbuild 0.1.0

package/CHANGELOG.md

@@ -0,0 +1,110 @@
+# Changelog
+
+Todas as mudanças notáveis deste projeto serão documentadas aqui.
+
+O formato segue [Keep a Changelog](https://keepachangelog.com/en/1.1.0/) e o
+versionamento segue [SemVer](https://semver.org/spec/v2.0.0.html).
+
+## [Unreleased]
+
+## [0.1.0] — 2026-05-05
+
+Primeira release pública. **MVP V1** — pipeline completo `live page → paste-ready
+WP/Shopify file`, validado e auto-corrigido, distribuído como plugin npm para
+Claude Code.
+
+### Added
+
+#### Entry points (12)
+
+- `/build-page <url>` — orchestrator single-page (WP ou Shopify).
+- `/build-site <url>` — orchestrator batch site-wide com checkpoint humano dual
+  (Pattern #35).
+- `/clip-section <url> --selector <css>` — orchestrator section-level via CSS
+  selector.
+- `sb-inspect-live` — Playwright + stealth, captura DOM/tokens/screenshot/bbox
+  da section, mobile-first (iPhone 14, DPR 3).
+- `sb-extract-assets` — download de imagens com strip metadata (EXIF/XMP/IPTC),
+  rename via content-hash, dedupe contra assets já em disco.
+- `sb-build-wp` — compositor WordPress/Elementor com defensive specificity,
+  mobile-first CSS, a11y/perf defaults.
+- `sb-build-shopify` — compositor Shopify Section `.liquid` com `{% schema %}`
+  editável, settings agrupadas, presets, sem `image_picker default`,
+  `{{ block.shopify_attributes }}` em iterações.
+- `sb-validate-render` — render offline via preset YAML, captura screenshot +
+  probe de tokens; suporta `--assets-map-path` pra Shopify mock context (resolve
+  `image_picker` settings via id-keyword × context-substring).
+- `sb-compare-visual` — pixelmatch + token cross-check, scope-aware com
+  `--crop-live-bbox` + `--crop-build-bbox` (crops simétricos, Pattern #27).
+- `sb-review-checks` — audit cheerio de 14 anti-patterns + 12 design checks
+  (5 a11y + 4 perf + 3 web-standards), confidence-tier no hero detection.
+- `sb-tweak` — edita arquivo entregue via pedido natural PT/EN, exit code 4
+  semântico pra needs-human-input, atomic revert em validation failure.
+- `sb-crawl-and-list` — descoberta de páginas sitemap-first com fallback HTML
+  crawl, classificação por path heuristic, ordering estável (home first,
+  depth ascendente, alfabético).
+
+#### Memória versionada (4 markdowns machine-parseable)
+
+- `templates/memory/anti-patterns.md` — **14 entries** (9 bootstrap +
+  5 descobertos em smoke tests reais example-store.com WP+Shopify).
+- `templates/memory/patterns.md` — 8 entries A-H com WP+Liquid variants
+  side-by-side.
+- `templates/memory/fixes.md` — 11 recipes (#22-#32).
+- `templates/memory/design-knowledge.md` — 12 checks
+  (5 a11y + 4 perf + 3 web-standards).
+
+Cascata Pattern #21 implementada em todas as skills consumers:
+`<plugin>/templates/memory → ~/.claude/similarbuild-memory → bundled fallback`.
+
+#### Decision matrix 2×2 (Pattern #28)
+
+Substituiu heurística frágil "diff>50 = catastrophic". Roteamento explícito por
+`review.passed` × `compare.passed`:
+
+| review.passed | compare.passed | Ação                                     |
+|---------------|----------------|------------------------------------------|
+| true          | true           | ✅ entrega                                |
+| false         | true           | ⚠️ escalate (audit estrutural)           |
+| true          | false          | ⚠️ escalate (drift visual sem fix)       |
+| false         | false          | 🔄 loop com fixHints (até max iter)      |
+
+#### Targets
+
+- **WordPress / Elementor** — HTML standalone, defensive specificity contra
+  Astra/Hello/temas custom.
+- **Shopify Section** — `.liquid` com schema editável, defensivo contra
+  Dawn / OS 2.0 / Sense.
+
+#### Distribution & infra
+
+- `bin/install.js` — CLI `npx similarbuild install` com 5 prompts via
+  `readline/promises` nativo (zero dep), idempotente, suporta `update`
+  subcommand preservando config + per-user memory.
+- `lib/{verify-env,prompt-config,copy-templates,install-deps}.mjs` —
+  modularização do installer (Pattern #1 lazy-import aplicado).
+- `scripts/sync-templates.mjs` — `.claude/{commands,skills/sb-*}` → `templates/`,
+  wired em `prepublishOnly`.
+- `templates/presets/{wp-elementor,shopify-section}.yaml` — theme reset CSS +
+  wrapper + head_extras + default_probe_root extraídos do fallback hardcoded
+  pra YAMLs declarativos.
+- `templates/reports/{report-template.html,report-renderer.mjs}` — single-file
+  HTML cumulativo com slider live⇆build interativo (`<input type=range>`,
+  keyboard ←/→, ARIA), JSON state embedado como `<script type="application/json">`
+  no próprio arquivo (Pattern #41), cap default 20 runs.
+
+### Validação
+
+- 153 unit/smoke tests passando (13 inspect-live + 20 validate-render +
+  34 anti-patterns + 15 cross-reference + 12 review-checks + 59 design-quality).
+- Smoke E2E rodado em 3 URLs reais (`iana.org/help/example-domains`,
+  `example-store.com --target wp`, `example-store.com --target shopify`).
+- Diff% medida (example-store hero WP track):
+  94.88% → 90.22% → 86.88% → 62.32% → 35.72% (-59.16pp em 4 fixes coordenados:
+  Pattern #22 DPR alignment, anti-pattern #10 scope crop, Pattern #27 simmetric
+  crop, defaults revisados).
+
+---
+
+[Unreleased]: https://github.com/eggonbassoli/similarbuild/compare/v0.1.0...HEAD
+[0.1.0]: https://github.com/eggonbassoli/similarbuild/releases/tag/v0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 SimilarBuild Authors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,301 @@
+# SimilarBuild
+
+> Visual migration framework para Claude Code — clona uma página live e entrega
+> arquivo pronto pra colar como **WordPress/Elementor HTML widget** ou **Shopify
+> section `.liquid`**, validado e auto-corrigido.
+
+[![npm version](https://img.shields.io/npm/v/similarbuild.svg)](https://www.npmjs.com/package/similarbuild)
+[![Node ≥20](https://img.shields.io/badge/node-%E2%89%A520-brightgreen.svg)](https://nodejs.org)
+[![License: MIT](https://img.shields.io/badge/license-MIT-blue.svg)](LICENSE)
+
+---
+
+## O que é
+
+SimilarBuild é uma framework distribuída como **plugin de skills do Claude Code**.
+Em vez de você manualmente abrir DevTools, copiar HTML, ajustar CSS, corrigir
+anti-patterns e medir diff visual, a framework orquestra **8 sub-skills
+determinísticas** atrás de **3 slash commands** que entregam o arquivo pronto:
+
+- `/build-page <url>` — clona **uma** página live → arquivo pronto.
+- `/build-site <url>` — descobre todas as páginas, confirma com você (único
+  checkpoint humano), clona em batch.
+- `/clip-section <url> --selector <css>` — clona **uma section específica** via
+  CSS selector → widget HTML / section Liquid.
+
+Pipeline padrão (cada step é uma sub-skill):
+
+```
+inspect-live → extract-assets → build-{wp|shopify} → validate-render
+            → compare-visual → review-checks → (auto-correct loop) → entrega
+```
+
+Características principais:
+
+- **Mobile-first** (iPhone 14, 390×844 CSS px, DPR 3) — alinhado live↔build.
+- **WordPress/Elementor** ou **Shopify Section** (com `{% schema %}` editável).
+- **Auto-correção**: review-checks + compare-visual alimentam fixHints num loop
+  determinístico (até `auto_correct_max_iterations`).
+- **Decision matrix 2×2** (review.passed × compare.passed) decide entrega vs
+  loop vs escalation — sem heurísticas frágeis baseadas só em diff%.
+- **Memória machine-parseable** (anti-patterns / patterns / fixes /
+  design-knowledge) lida via cascata `<plugin> → ~/.claude/similarbuild-memory
+  → bundled fallback`.
+- **Cumulative HTML report** com slider live⇆build interativo, history embutido
+  como `<script type="application/json">` no próprio arquivo.
+
+---
+
+## Quick start
+
+### Pré-requisitos
+
+- **Node.js ≥ 20** (usa `fetch` e `crypto` nativos).
+- **Claude Code** instalado (`claude.ai/code` ou CLI).
+- ~150MB livres pra `npx playwright install chromium`.
+
+### Instalar no seu projeto
+
+Dentro de qualquer diretório de projeto onde você quer usar a framework:
+
+```bash
+npx similarbuild install
+```
+
+O installer faz, em ordem:
+
+1. Verifica Node ≥ 20.
+2. Pergunta 5 configurações (com defaults sensatos):
+   - `output_folder` (default: `sb-output`)
+   - `default_target` (`wp` | `shopify`, default: `wp`)
+   - `default_viewport` (default: `iphone-14`)
+   - `auto_correct_max_iterations` (default: `3`)
+   - `diff_threshold_percent` (default: `10`)
+3. Copia templates pra `.claude/{commands,skills,skills/sb-shared/{memory,presets},templates/reports}`.
+4. Cria `.claude/sb-config.yaml` (seguro re-rodar — preserva config existente).
+5. Garante `~/.claude/similarbuild-memory/` pra auto-learn per-user.
+6. Cria stub `package.json` se faltar e instala 10 deps runtime
+   (`playwright`, `sharp`, `pixelmatch`, `cheerio`, `liquidjs`, etc.).
+7. Confirma e roda `npx playwright install chromium`.
+
+Flags úteis:
+
+| Flag             | Quando usar                                           |
+|------------------|-------------------------------------------------------|
+| `--yes`, `-y`    | usa defaults sem prompts (CI / re-install rápido)     |
+| `--no-deps`      | pula `npm install` (deps já instaladas)               |
+| `--no-chromium`  | pula download do Chromium (~150MB)                    |
+| `--dry-run`      | só imprime o que faria, sem escrever                  |
+
+### Atualizar
+
+```bash
+npx similarbuild update
+```
+
+Re-baixa templates novos preservando `.claude/sb-config.yaml` e
+`~/.claude/similarbuild-memory/`.
+
+### Primeira execução
+
+Abra o projeto no Claude Code e rode:
+
+```
+/build-page https://example.com
+```
+
+A framework dispara o pipeline ponta-a-ponta e entrega o arquivo em
+`<output_folder>/<project-slug>/{slug}/build.{html|liquid}`.
+
+---
+
+## Slash commands
+
+### `/build-page <url> [--target wp|shopify] [--selector <css>]`
+
+Clona **uma** página live e entrega arquivo pronto. Se `--selector` for passado,
+só extrai e clona aquele scope (equivalente a `/clip-section` por baixo).
+
+**Output:** `{output_folder}/{project-slug}/{page-slug}/build.{html|liquid}`,
+`render.json`, `compare.json`, `review.json`, screenshots, `report.html`.
+
+### `/build-site <url> [--target wp|shopify]`
+
+Descobre páginas via `sitemap.xml` (fallback: crawl HTML) → apresenta tabela →
+você aplica filtros (skip/only/exclude/include) → confirma → clona em batch
+sequencial.
+
+**Único checkpoint humano da framework.** Confirmação dupla pra reduzir erros em
+batches grandes (Pattern #35).
+
+**Output:** mesmo layout do `/build-page` por página, mais `report.html`
+cumulativo agregado e `auto-learn` consolidado no fim.
+
+### `/clip-section <url> --selector <css>`
+
+Single-shot section via CSS selector. Validação rigorosa do selector (escala se
+não casar — sem fabrication). Live é element-only (sem `--crop-live-bbox`).
+
+---
+
+## Configuração
+
+`.claude/sb-config.yaml` — gerado pelo installer, editável livremente:
+
+```yaml
+output_folder: sb-output
+default_target: wp                    # ou: shopify
+default_viewport: iphone-14
+auto_correct_max_iterations: 3
+diff_threshold_percent: 10
+```
+
+Skills usam defaults inline se a config estiver ausente — você pode deletar o
+arquivo e tudo continua funcionando.
+
+### Memória
+
+Três camadas, lidas em cascata (Pattern #21):
+
+1. `<plugin>/templates/memory/*.md` — versionada, vem com o release npm.
+2. `~/.claude/similarbuild-memory/*.md` — per-user, populada por `/build-site`
+   auto-learn batched.
+3. `<skill>/references/*.md` — bundled fallback dentro de cada skill.
+
+Cada arquivo é machine-parseable (campos
+`id/name/applies-to/applies-when/symptom/fix-recipe/detector/severity/origin`).
+
+---
+
+## Como funciona — sub-skills
+
+| Sub-skill              | Papel                                                              |
+|------------------------|--------------------------------------------------------------------|
+| `sb-inspect-live`      | Playwright + stealth → DOM, tokens, screenshot, bbox da section.   |
+| `sb-extract-assets`    | Baixa imagens, strip metadata (EXIF/XMP/IPTC), dedupe content-hash. |
+| `sb-build-wp`          | Compõe HTML/Elementor com defensive specificity + a11y/perf.       |
+| `sb-build-shopify`     | Compõe `.liquid` com `{% schema %}` editável + shims locais.       |
+| `sb-validate-render`   | Renderiza fragment offline (preset YAML), captura screenshot+tokens.|
+| `sb-compare-visual`    | pixelmatch + token cross-check, scope-aware crops simétricos.      |
+| `sb-review-checks`     | Cheerio audit de 14 anti-patterns + 12 design checks (a11y/perf/web).|
+| `sb-tweak`             | Edita arquivo entregue via pedido natural PT/EN, atomic-revert.    |
+| `sb-crawl-and-list`    | Sitemap-first + cheerio fallback, classifica + ordena pra UI.      |
+
+---
+
+## Targets suportados
+
+### WordPress / Elementor (`--target wp`)
+
+Saída: HTML standalone com defensive specificity (`#elementor-editor` /
+`.elementor-widget`), mobile-first CSS, alt text, `loading="lazy"`,
+`fetchpriority="high"` no hero img, `rel="preload"` quando bg-image.
+
+Cole no widget HTML do Elementor.
+
+### Shopify Section (`--target shopify`)
+
+Saída: `.liquid` com `{% schema %}` editável (settings, presets), imagem hero
+via `image_picker` setting (sem `default` — anti-pattern #12), fallback via
+SVG base64 inline (sem path absoluto — anti-pattern #16), `{{ block.shopify_attributes }}`
+em qualquer iteração, sem Google Fonts `<link>` inline (anti-pattern #14).
+
+Cole em `sections/<nome>.liquid` no tema Dawn / OS 2.0 / Sense.
+
+---
+
+## Anti-patterns que a framework previne
+
+A v0.1.0 codifica 14 anti-patterns descobertos em smoke tests reais
+(`example-store.com` WP+Shopify track):
+
+1. **`100vh` no hero** — quebra mobile (URL bar dinâmica).
+2. **Hero `<img>` sem `fetchpriority="high"` + `<link rel="preload">`** quando
+   é background-image (detection two-step com confidence-tier).
+3. **`<img>` sem `alt`** — bloqueia a11y.
+4. **CSS sem mobile-first** — desktop-first quebra responsive.
+5. **Defensive specificity ausente** (selectors que vazam pro tema host).
+6. **Caminho absoluto do dev em fallback** (`/Users/...`, `C:\Users\...`).
+7. **Schema `image_picker` com `default` fixo** — UX ruim (Shopify).
+8. **Block iteration sem `{{ block.shopify_attributes }}`** (Shopify).
+9. **Google Fonts `<link>` inline na section** (Shopify).
+10. **Inspector full-page com section específica** (scope mismatch no diff).
+11. **404 silencioso em CDN do source** — comportamento normal, não escalar.
+12. **Prettier corrompendo `{% schema %}` JSON** — fix via placeholder.
+13. **`{% style %}/{% javascript %}` em liquidjs vanilla** — shim local.
+14. **image_picker sem default + mock context vazio** infla diff —
+   `--assets-map-path` resolve.
+
+Veja `templates/memory/anti-patterns.md` pro contrato machine-parseable.
+
+---
+
+## CI / publishing
+
+Releases tagged via GitHub triggam `npm publish` automático
+(`.github/workflows/publish.yml`).
+
+**Setup obrigatório no repo (uma vez):**
+
+1. Settings → Secrets and variables → Actions → New repository secret.
+2. Nome: `NPM_TOKEN`.
+3. Valor: token gerado em https://www.npmjs.com/settings/<user>/tokens
+   (tipo: **Automation** — pula 2FA challenge no publish).
+
+Depois disso, `gh release create v0.1.0` (ou Releases → Draft new release →
+Publish) dispara o workflow e publica no npm.
+
+`prepublishOnly` roda `scripts/sync-templates.mjs` (`.claude/{commands,skills/sb-*}
+→ templates/{commands,skills/}`) — garante que o tarball sempre tem a versão
+mais nova das skills sem precisar lembrar.
+
+---
+
+## Roadmap V2 (próximos)
+
+A v0.1.0 cobre **MVP V1**: 12 entry points (3 slash commands + 9 sub-skills),
+14 anti-patterns codificados, 2 targets (WP + Shopify), decision matrix
+explícita.
+
+Itens em consideração pra V2:
+
+- **Paralelismo no `/build-site`** — hoje é sequencial (1 página por vez),
+  V2 com pool de N workers.
+- **`sb-tweak` em batch** — receber lista de pedidos PT/EN, aplicar todos
+  com two-phase confirmation (Pattern #35).
+- **Targets adicionais** — Webflow, Framer, raw HTML standalone, MDX.
+- **`sb-build-react`** — componente `.tsx` em vez de markup serializado.
+- **Detector de anti-pattern #16 em `sb-review-checks`** — regex pra
+  paths absolutos (`/Users/`, `/home/`, `C:\Users\\`) no output final.
+- **Visual regression suite** — `report.html` com diff cumulativo de N
+  runs, gráfico de evolução do diff%.
+- **i18n no `sb-tweak`** — hoje aceita PT/EN, expandir pra ES/FR.
+
+Issues e sugestões: https://github.com/eggonbassoli/similarbuild/issues
+
+---
+
+## Desenvolvimento
+
+```bash
+git clone https://github.com/eggonbassoli/similarbuild
+cd similarbuild
+npm install                          # instala devDependencies (deps reais das skills)
+npm run sync-templates               # .claude/* → templates/*
+npm run smoke:install                # bin/install.js --help
+```
+
+Cada sub-skill tem testes em `.claude/skills/sb-<nome>/scripts/tests/`. Rodar:
+
+```bash
+node .claude/skills/sb-inspect-live/scripts/tests/test-inspect-live.mjs
+# ... etc
+```
+
+Total V1: 153 unit/smoke tests passando.
+
+---
+
+## Licença
+
+MIT © 2026 SimilarBuild Authors — veja [LICENSE](LICENSE).

package/bin/install.js

@@ -0,0 +1,256 @@
+#!/usr/bin/env node
+// SimilarBuild installer — `npx similarbuild install` num projeto Claude Code
+// copia templates, cria config, instala deps e deixa a framework pronta pra uso.
+//
+// Pattern #1 — lazy import das libs internas pra `--help` e validação de args funcionarem
+// mesmo se algo no resto do pacote estiver quebrado.
+// Pattern #16 — todos os logs em stderr com prefixo `[similarbuild]`.
+
+import path from 'node:path';
+import fs from 'node:fs/promises';
+import { fileURLToPath } from 'node:url';
+
+const __dirname = path.dirname(fileURLToPath(import.meta.url));
+const PLUGIN_ROOT = path.resolve(__dirname, '..');
+const DEST = process.cwd();
+
+const HELP = `\
+similarbuild — installer da framework SimilarBuild
+
+Uso:
+  npx similarbuild install [flags]   instala templates + deps no projeto atual
+  npx similarbuild update            re-baixa templates novos preservando config + memória per-user
+  npx similarbuild --help            esta mensagem
+
+Flags do install:
+  --yes, -y       usa defaults sem prompts (CI / re-install rápido)
+  --no-deps       pula instalação de deps npm (já instaladas)
+  --no-chromium   pula download do Chromium do Playwright (~150MB)
+  --dry-run       só imprime o que faria, não escreve nada
+`;
+
+function out(msg) { process.stdout.write(msg + '\n'); }
+function err(msg) { process.stderr.write(`[similarbuild] ${msg}\n`); }
+
+function parseArgs(argv) {
+  const args = { _: [], yes: false, deps: true, chromium: true, dryRun: false, help: false };
+  for (const a of argv) {
+    if (a === '--help' || a === '-h') args.help = true;
+    else if (a === '--yes' || a === '-y') args.yes = true;
+    else if (a === '--no-deps') args.deps = false;
+    else if (a === '--no-chromium') args.chromium = false;
+    else if (a === '--dry-run') args.dryRun = true;
+    else if (a.startsWith('-')) { err(`flag desconhecida: ${a}`); process.exit(2); }
+    else args._.push(a);
+  }
+  return args;
+}
+
+function yamlEscape(v) {
+  // Strings simples não precisam quote; só quote quando contém caractere YAML-significativo.
+  if (typeof v === 'number') return String(v);
+  if (typeof v === 'boolean') return String(v);
+  const s = String(v);
+  if (/^[A-Za-z0-9_./-]+$/.test(s)) return s;
+  return JSON.stringify(s);
+}
+
+async function writeConfig(destRoot, cfg) {
+  const lines = [
+    '# Generated by `npx similarbuild install`',
+    '# Edit livremente — skills usam defaults inline se config ausente.',
+    `output_folder: ${yamlEscape(cfg.output_folder)}`,
+    `default_target: ${yamlEscape(cfg.default_target)}`,
+    `default_viewport: ${yamlEscape(cfg.default_viewport)}`,
+    `auto_correct_max_iterations: ${yamlEscape(cfg.auto_correct_max_iterations)}`,
+    `diff_threshold_percent: ${yamlEscape(cfg.diff_threshold_percent)}`,
+    '',
+  ];
+  await fs.mkdir(path.join(destRoot, '.claude'), { recursive: true });
+  await fs.writeFile(path.join(destRoot, '.claude', 'sb-config.yaml'), lines.join('\n'));
+}
+
+async function readConfigIfExists(destRoot) {
+  try {
+    const text = await fs.readFile(path.join(destRoot, '.claude', 'sb-config.yaml'), 'utf8');
+    const cfg = {};
+    for (const line of text.split('\n')) {
+      const m = line.match(/^([A-Za-z_][\w]*):\s*(.+?)\s*$/);
+      if (!m) continue;
+      let v = m[2];
+      if (v.startsWith('"') && v.endsWith('"')) {
+        try { v = JSON.parse(v); } catch {}
+      }
+      cfg[m[1]] = v;
+    }
+    return cfg;
+  } catch { return null; }
+}
+
+function normalizeConfig(raw) {
+  const { DEFAULTS } = { DEFAULTS: {
+    output_folder: './sb-output',
+    default_target: 'wp',
+    default_viewport: 390,
+    auto_correct_max_iterations: 2,
+    diff_threshold_percent: 15,
+  } };
+  const intOr = (v, def) => {
+    const n = parseInt(v, 10);
+    return Number.isFinite(n) ? n : def;
+  };
+  return {
+    output_folder: raw.output_folder || DEFAULTS.output_folder,
+    default_target: raw.default_target || DEFAULTS.default_target,
+    default_viewport: intOr(raw.default_viewport, DEFAULTS.default_viewport),
+    auto_correct_max_iterations: intOr(raw.auto_correct_max_iterations, DEFAULTS.auto_correct_max_iterations),
+    diff_threshold_percent: intOr(raw.diff_threshold_percent, DEFAULTS.diff_threshold_percent),
+  };
+}
+
+async function ensureMemoryDir() {
+  const home = process.env.HOME || process.env.USERPROFILE;
+  if (!home) {
+    err('HOME não detectado, pulando memória per-user');
+    return null;
+  }
+  const dir = path.join(home, '.claude', 'similarbuild-memory');
+  await fs.mkdir(dir, { recursive: true });
+  return dir;
+}
+
+async function writeOutputGitignore(destRoot, outputFolder) {
+  const dir = path.resolve(destRoot, outputFolder);
+  await fs.mkdir(dir, { recursive: true });
+  const gi = path.join(dir, '.gitignore');
+  try { await fs.access(gi); return false; } catch {}
+  await fs.writeFile(gi, '# Outputs derivados — não versione.\n**\n');
+  return true;
+}
+
+async function cmdInstall(args) {
+  const { verifyNode } = await import('../lib/verify-env.mjs');
+  if (!verifyNode()) process.exit(1);
+
+  err(`projeto destino: ${DEST}`);
+  if (args.dryRun) err('--dry-run: nada será escrito');
+
+  // 1. Config: existente ou interativo ou defaults.
+  const existing = await readConfigIfExists(DEST);
+  let cfg;
+  if (existing) {
+    err('config existente em .claude/sb-config.yaml — preservando');
+    cfg = normalizeConfig(existing);
+  } else {
+    const { promptConfig } = await import('../lib/prompt-config.mjs');
+    cfg = await promptConfig({ yes: args.yes });
+  }
+
+  if (args.dryRun) {
+    out('--- dry-run preview ---');
+    out(`config: ${JSON.stringify(cfg, null, 2)}`);
+    out(`would copy templates from ${PLUGIN_ROOT}/templates → ${DEST}/.claude/{commands,skills,...}`);
+    out(`would create ${DEST}/${cfg.output_folder}/.gitignore`);
+    out(`would mkdir ~/.claude/similarbuild-memory/`);
+    if (args.deps) out('would npm install <deps>');
+    if (args.chromium) out('would prompt + npx playwright install chromium');
+    return;
+  }
+
+  // 2. Copia templates.
+  const { copyTemplates } = await import('../lib/copy-templates.mjs');
+  await copyTemplates({ pluginRoot: PLUGIN_ROOT, destRoot: DEST });
+
+  // 3. Escreve config (se já existia, re-escreve normalizado).
+  await writeConfig(DEST, cfg);
+
+  // 4. .gitignore no output_folder.
+  await writeOutputGitignore(DEST, cfg.output_folder);
+
+  // 5. Memória per-user.
+  const memDir = await ensureMemoryDir();
+
+  // 6. npm install.
+  if (args.deps) {
+    const { ensurePackageJson, installDeps } = await import('../lib/install-deps.mjs');
+    await ensurePackageJson(DEST);
+    try {
+      await installDeps(DEST);
+    } catch (e) {
+      err(`npm install falhou: ${e.message}`);
+      err('rode `npm install` manualmente quando puder e re-rode `npx similarbuild install --no-deps` se precisar.');
+      process.exit(1);
+    }
+  } else {
+    err('--no-deps: pulando npm install');
+  }
+
+  // 7. Chromium.
+  if (args.chromium) {
+    const { confirm } = await import('../lib/prompt-config.mjs');
+    const go = await confirm('Baixar Chromium do Playwright agora (~150MB)?', { defaultYes: true, yes: args.yes });
+    if (go) {
+      const { installChromium } = await import('../lib/install-deps.mjs');
+      try { await installChromium(DEST); }
+      catch (e) {
+        err(`chromium install falhou: ${e.message}`);
+        err('rode `npx playwright install chromium` quando puder.');
+      }
+    } else {
+      err('Chromium pulado. Rode `npx playwright install chromium` quando precisar.');
+    }
+  }
+
+  // 8. Próximos passos.
+  out('');
+  out('✅ SimilarBuild instalado.');
+  out(`   Config:  .claude/sb-config.yaml`);
+  out(`   Output:  ${cfg.output_folder}/`);
+  if (memDir) out(`   Memória per-user: ${memDir}/`);
+  out('');
+  out('Próximo: claude → /build-page https://exemplo.com');
+  out('Docs:    https://github.com/eggonbassoli/similarbuild');
+}
+
+async function cmdUpdate(args) {
+  const { verifyNode } = await import('../lib/verify-env.mjs');
+  if (!verifyNode()) process.exit(1);
+
+  const existing = await readConfigIfExists(DEST);
+  if (!existing) {
+    err('nenhum sb-config.yaml encontrado — rode `similarbuild install` primeiro.');
+    process.exit(1);
+  }
+
+  err(`atualizando templates em ${DEST}`);
+  if (args.dryRun) {
+    out(`would re-copy templates from ${PLUGIN_ROOT}/templates → ${DEST}`);
+    out(`would preserve .claude/sb-config.yaml + ~/.claude/similarbuild-memory/`);
+    return;
+  }
+
+  const { copyTemplates } = await import('../lib/copy-templates.mjs');
+  await copyTemplates({ pluginRoot: PLUGIN_ROOT, destRoot: DEST });
+  await ensureMemoryDir();
+
+  out('');
+  out('✅ SimilarBuild atualizado.');
+  out('   Config preservado em .claude/sb-config.yaml');
+  out('   Memória per-user preservada em ~/.claude/similarbuild-memory/');
+}
+
+async function main() {
+  const args = parseArgs(process.argv.slice(2));
+  if (args.help) { out(HELP); return; }
+  const sub = args._[0] || 'install';
+  if (sub === 'install') return cmdInstall(args);
+  if (sub === 'update') return cmdUpdate(args);
+  err(`subcommand desconhecido: ${sub}`);
+  out(HELP);
+  process.exit(2);
+}
+
+main().catch((e) => {
+  err(`erro fatal: ${e.stack || e.message}`);
+  process.exit(1);
+});