@jaimevalasek/aioson 1.7.2 → 1.9.0

package/docs/pt/{site-forge.md → _arquivo/site-forge.md}

@@ -1,309 +1,318 @@
-# `site-forge`
-
-Agente de clonagem inteligente do AIOSON — estuda um site real e reconstrói como projeto Next.js, forja uma skill de design, ou ambos.
-
-## O que ele faz
-
-- recebe uma URL e guia você até o modo certo com um **questionário de onboarding**
-- captura screenshots, assets (img, background-image, srcset, lazy-loaded, video) via browser MCP
-- faz crawl de links internos para capturar assets e padrões de sub-páginas
-- extrai estrutura, comportamento e interações
-- forja design skills, mescla tokens, ou aplica skills existentes conforme o modo escolhido
-- constrói um projeto Next.js com worktrees paralelas
-
-## Pré-requisitos
-
-### 1. Browser MCP
-
-O agente precisa de automação de browser para navegar, capturar screenshots, disparar lazy loads e testar interações. Configure um antes de usar:
-
-```bash
-# Playwright MCP (recomendado)
-npx @playwright/mcp@latest
-
-# Puppeteer MCP (alternativa)
-npx @modelcontextprotocol/server-puppeteer
-```
-
-Adicione o browser MCP escolhido nas configurações de MCP do seu cliente AI. O agente detecta automaticamente qual está disponível.
-
-### 2. Design skill (quando aplicável)
-
-Modos que usam uma skill existente precisam de uma skill já instalada. Use uma das skills nativas:
-
-```text
-.aioson/skills/design/aurora-command-ui/
-.aioson/skills/design/cognitive-core-ui/
-.aioson/skills/design/glassmorphism-ui/
-.aioson/skills/design/bold-editorial-ui/
-.aioson/skills/design/neo-brutalist-ui/
-.aioson/skills/design/warm-craft-ui/
-.aioson/skills/design/clean-saas-ui/
-```
-
-Ou use uma skill gerada pelo `@design-hybrid-forge`:
-
-```text
-.aioson/installed-skills/{slug}/
-```
-
-## Modos de operação
-
-O agente tem **5 modos**. Se você não especificar o modo, ele roda o **onboarding inteligente** e te guia até o certo.
-
-| Modo | Entrada | Output |
-|------|---------|--------|
-| **A — Transform** | URL + skill | Site construído com a skill aplicada à estrutura clonada |
-| **B — Faithful clone** | URL | Réplica fiel + nova skill forjada do site |
-| **C — Content harvest** | URL + skill | Site construído com conteúdo/imagens do site + layout da skill |
-| **D — Skill only** | URL | Só a skill forjada — nenhum site é construído |
-| **E — Blend** | URL + skill + ratio | Site com tokens misturados entre o site e a skill |
-
-## Onboarding inteligente
-
-Quando você chamar `/site-forge` sem especificar o modo, o agente pergunta:
-
-```
-O que você quer fazer com este site?
-
-  A — Extrair conteúdo e imagens → construir um novo site com uma das suas skills
-  B — Clonar fielmente → réplica visual + forjar uma skill com o design do site
-  C — Extrair somente o design (CSS, animações) → criar uma skill reutilizável (sem construir o site)
-  D — Clonar com textos e imagens originais + mesclar com uma das suas skills (50/50)
-```
-
-Depois coleta os dados que faltam (URL, skill, ratio) e já avança.
-
-## Como invocar
-
-```text
-/site-forge <url> <skill>              → Modo A (transform)
-/site-forge <url>                      → Onboarding guiado
-/site-forge <url> --skill-only         → Modo D (só a skill)
-/site-forge <url> <skill> --blend      → Modo E (blend 50/50)
-/site-forge <url> <skill> --blend=70   → Modo E (70% site / 30% skill)
-```
-
-Com flags opcionais:
-
-```text
---viewport=desktop    # só desktop (padrão: todos os três)
---no-download         # pular download de assets
---no-crawl            # pular crawl de links internos
---crawl-depth=N       # seguir N níveis de links (padrão: 1)
---output=./dir        # diretório customizado
---verbose             # log detalhado
-```
-
-## Extração de assets melhorada
-
-O agente captura imagens de **todas as fontes**, não só `<img>`:
-
-- `<img>` com `srcset` e `data-src` (lazy loading)
-- `background-image` em **qualquer elemento** via `getComputedStyle`
-- `<picture> <source srcset>`
-- `<video poster>` e `<source>` de vídeo
-- `<use href>` de SVG externos
-- `style=""` com `background-image` inline
-- meta tags `og:image` e `twitter:image`
-
-Antes de extrair, o agente faz scroll completo pela página para **disparar todos os lazy loads**.
-
-## Crawl de links internos
-
-Por padrão o agente segue links internos para capturar assets e padrões de sub-páginas:
-
-| Modo | Links seguidos (padrão) |
-|------|------------------------|
-| A, C (content harvest) | até 10 |
-| B, D, E | até 5 |
-
-Use `--no-crawl` para desativar ou `--crawl-depth=N` para ajustar.
-
-## Fluxo por fase
-
-| Fase | O que acontece | Modos |
-|------|---------------|-------|
-| **0 — Preflight** | Browser MCP, skill, projeto Next.js | Todos |
-| **1 — Reconnaissance** | Screenshots, deep asset extraction, crawl, interações | Todos |
-| **2 — Extraction** | Spec de estrutura + conteúdo; valores estéticos (modos B/D/E) | Todos |
-| **3A — Transform** | Mapa componente → skill com tokens | A, C |
-| **3B — Skill forge** | Extrai design system e forja skill em `.aioson/installed-skills/` | B, D, E |
-| **3E — Blend** | Mescla tokens do site com tokens da skill no ratio definido | E |
-| **4 — Build** | Constrói componentes com worktrees, verifica `npm run build` | A, B, C, E |
-| **5 — QA** | Screenshot diff, testes de interação, fidelidade de tokens | A, B, C, E |
-
-**Modo D** termina após a Fase 3B — nenhum site é construído.
-
-## Output por modo
-
-```text
-Todos os modos:
-  docs/research/<hostname>/
-    reconnaissance.json        ← dados da navegação
-    crawl-manifest.json        ← URLs visitadas e assets por página
-    structure-spec.md          ← topologia e layout
-    interaction-spec.md        ← modelo de interação
-    qa-report.md               ← resultado do QA (modos A/B/C/E)
-
-Modo A, C:
-    component-map.md           ← mapeamento componente → skill
-
-Modo B, D, E:
-    aesthetics-raw.json        ← valores CSS extraídos
-
-Modo E:
-    blend-map.md               ← decisões de blend por token
-    blended-tokens.css         ← tokens mesclados prontos para uso
-
-Modos A, B, C, E (constrói site):
-  src/components/[todos os componentes]
-  src/app/page.tsx
-  src/app/globals.css
-  public/images/<hostname>/[assets baixados]
-
-Modos B, D, E (forja skill):
-  .aioson/installed-skills/<hostname>/
-    SKILL.md
-    references/design-tokens.md
-    references/components.md
-    references/patterns.md
-    references/motion.md
-    references/websites.md
-    .skill-meta.json
-```
-
-## Fluxo completo: forge + clone
-
-O caminho mais poderoso é criar uma skill sob medida com `design-hybrid-forge` e aplicá-la.
-
-### Passo 1 — Gerar o preset visual
-
-```bash
-aioson design-hybrid:options . --locale=pt-BR
-```
-
-### Passo 2 — Forjar a skill híbrida
-
-```text
-/design-hybrid-forge
-→ skills primárias: aurora-command-ui + cognitive-core-ui
-→ nome: aurora-cognitive-command
-```
-
-### Passo 3 — Aplicar no clone
-
-```text
-/site-forge https://datadog.com aurora-cognitive-command
-```
-
-Resultado: estrutura e interações do Datadog, visual da `aurora-cognitive-command`.
-
----
-
-Veja a documentação completa do seletor interativo em: [`design-hybrid-forge.md`](design-hybrid-forge.md)
-
----
-
-## Exemplos práticos
-
-### Modo A — Clone com skill existente
-
-```text
-/site-forge https://stripe.com aurora-command-ui
-```
-
-Estrutura e fluxo do Stripe, visual da `aurora-command-ui`.
-
----
-
-### Modo B — Réplica fiel + nova skill
-
-```text
-/site-forge https://linear.app
-```
-
-Forja uma skill em `.aioson/installed-skills/linear.app/` e constrói uma réplica fiel.
-
----
-
-### Modo C — Colher conteúdo + nova estrutura com skill
-
-Perguntar o modo via onboarding:
-
-```text
-/site-forge https://framer.com
-→ escolha A no onboarding
-→ skill: clean-saas-ui
-```
-
-Textos e imagens do Framer, layout e visual do `clean-saas-ui`.
-
----
-
-### Modo D — Só a skill, sem construir
-
-```text
-/site-forge https://resend.com --skill-only
-```
-
-Forja `.aioson/installed-skills/resend.com/`. Nenhuma página é construída.
-
----
-
-### Modo E — Blend 50/50
-
-```text
-/site-forge https://vercel.com neo-brutalist-ui --blend
-```
-
-Tokens mesclados 50% Vercel / 50% `neo-brutalist-ui`.
-
----
-
-### Blend assimétrico (70% site)
-
-```text
-/site-forge https://notion.so glassmorphism-ui --blend=70
-```
-
-70% tokens do Notion, 30% tokens da `glassmorphism-ui`.
-
----
-
-### Clone em projeto existente
-
-```bash
-cd meu-projeto-nextjs
-/site-forge https://loom.com cognitive-core-ui
-```
-
-O agente detecta o `package.json` com `next` e usa o projeto existente.
-
-## Diferença em relação a clonar manualmente
-
-| Aspecto | Clone manual | site-forge |
-|---------|-------------|--------------|
-| Extração de imagens | Só `<img>` visíveis | img + CSS bg + srcset + lazy + video + SVG |
-| Sub-páginas | Ignoradas | Crawl automático |
-| Estética | Replica o original | Skill tokens, blend, ou extração fiel |
-| Interações | Esquecidas facilmente | Mapeadas antes de construir |
-| Build | Erros no final | Verificado após cada worktree |
-| QA | Manual | Screenshot diff + checklist formal |
-
-## Nota sobre conteúdo e assets
-
-Os textos e imagens extraídos são apenas para estruturar o clone durante o desenvolvimento. **Substitua todo o conteúdo antes de publicar.** O agente avisa ao final da Fase 1.
-
-## Quando usar
-
-- você quer o comportamento/layout de um site de referência
-- quer prototipar rapidamente com estrutura testada
-- quer extrair o design de um site como skill reutilizável
-- quer mesclar o visual de um site com sua brand
-- o cliente mostrou um concorrente como referência de fluxo
-
-## Quando não usar
-
-- o site tem proteção pesada (SPA autenticada, bot protection agressivo)
-- você quer criar a estrutura do zero com total liberdade → use `/deyvin` ou `/dev`
+# [Arquivado] `site-forge`
+
+> **Esta doc foi substituída.**
+> A ficha do `@site-forge` agora vive em [`../4-agentes/site-forge.md`](../4-agentes/site-forge.md).
+> Para a receita prática, veja [`../3-receitas/clonar-design-de-site.md`](../3-receitas/clonar-design-de-site.md).
+> Conteúdo abaixo preservado para referência histórica.
+
+---
+
+# `site-forge`
+
+Agente de clonagem inteligente do AIOSON — estuda um site real e reconstrói como projeto Next.js, forja uma skill de design, ou ambos.
+
+## O que ele faz
+
+- recebe uma URL e guia você até o modo certo com um **questionário de onboarding**
+- captura screenshots, assets (img, background-image, srcset, lazy-loaded, video) via browser MCP
+- faz crawl de links internos para capturar assets e padrões de sub-páginas
+- extrai estrutura, comportamento e interações
+- forja design skills, mescla tokens, ou aplica skills existentes conforme o modo escolhido
+- constrói um projeto Next.js com worktrees paralelas
+
+## Pré-requisitos
+
+### 1. Browser MCP
+
+O agente precisa de automação de browser para navegar, capturar screenshots, disparar lazy loads e testar interações. Configure um antes de usar:
+
+```bash
+# Playwright MCP (recomendado)
+npx @playwright/mcp@latest
+
+# Puppeteer MCP (alternativa)
+npx @modelcontextprotocol/server-puppeteer
+```
+
+Adicione o browser MCP escolhido nas configurações de MCP do seu cliente AI. O agente detecta automaticamente qual está disponível.
+
+### 2. Design skill (quando aplicável)
+
+Modos que usam uma skill existente precisam de uma skill já instalada. Use uma das skills nativas:
+
+```text
+.aioson/skills/design/aurora-command-ui/
+.aioson/skills/design/cognitive-core-ui/
+.aioson/skills/design/glassmorphism-ui/
+.aioson/skills/design/bold-editorial-ui/
+.aioson/skills/design/neo-brutalist-ui/
+.aioson/skills/design/warm-craft-ui/
+.aioson/skills/design/clean-saas-ui/
+```
+
+Ou use uma skill gerada pelo `@design-hybrid-forge`:
+
+```text
+.aioson/installed-skills/{slug}/
+```
+
+## Modos de operação
+
+O agente tem **5 modos**. Se você não especificar o modo, ele roda o **onboarding inteligente** e te guia até o certo.
+
+| Modo | Entrada | Output |
+|------|---------|--------|
+| **A — Transform** | URL + skill | Site construído com a skill aplicada à estrutura clonada |
+| **B — Faithful clone** | URL | Réplica fiel + nova skill forjada do site |
+| **C — Content harvest** | URL + skill | Site construído com conteúdo/imagens do site + layout da skill |
+| **D — Skill only** | URL | Só a skill forjada — nenhum site é construído |
+| **E — Blend** | URL + skill + ratio | Site com tokens misturados entre o site e a skill |
+
+## Onboarding inteligente
+
+Quando você chamar `/site-forge` sem especificar o modo, o agente pergunta:
+
+```
+O que você quer fazer com este site?
+
+  A — Extrair conteúdo e imagens → construir um novo site com uma das suas skills
+  B — Clonar fielmente → réplica visual + forjar uma skill com o design do site
+  C — Extrair somente o design (CSS, animações) → criar uma skill reutilizável (sem construir o site)
+  D — Clonar com textos e imagens originais + mesclar com uma das suas skills (50/50)
+```
+
+Depois coleta os dados que faltam (URL, skill, ratio) e já avança.
+
+## Como invocar
+
+```text
+/site-forge <url> <skill>              → Modo A (transform)
+/site-forge <url>                      → Onboarding guiado
+/site-forge <url> --skill-only         → Modo D (só a skill)
+/site-forge <url> <skill> --blend      → Modo E (blend 50/50)
+/site-forge <url> <skill> --blend=70   → Modo E (70% site / 30% skill)
+```
+
+Com flags opcionais:
+
+```text
+--viewport=desktop    # só desktop (padrão: todos os três)
+--no-download         # pular download de assets
+--no-crawl            # pular crawl de links internos
+--crawl-depth=N       # seguir N níveis de links (padrão: 1)
+--output=./dir        # diretório customizado
+--verbose             # log detalhado
+```
+
+## Extração de assets melhorada
+
+O agente captura imagens de **todas as fontes**, não só `<img>`:
+
+- `<img>` com `srcset` e `data-src` (lazy loading)
+- `background-image` em **qualquer elemento** via `getComputedStyle`
+- `<picture> <source srcset>`
+- `<video poster>` e `<source>` de vídeo
+- `<use href>` de SVG externos
+- `style=""` com `background-image` inline
+- meta tags `og:image` e `twitter:image`
+
+Antes de extrair, o agente faz scroll completo pela página para **disparar todos os lazy loads**.
+
+## Crawl de links internos
+
+Por padrão o agente segue links internos para capturar assets e padrões de sub-páginas:
+
+| Modo | Links seguidos (padrão) |
+|------|------------------------|
+| A, C (content harvest) | até 10 |
+| B, D, E | até 5 |
+
+Use `--no-crawl` para desativar ou `--crawl-depth=N` para ajustar.
+
+## Fluxo por fase
+
+| Fase | O que acontece | Modos |
+|------|---------------|-------|
+| **0 — Preflight** | Browser MCP, skill, projeto Next.js | Todos |
+| **1 — Reconnaissance** | Screenshots, deep asset extraction, crawl, interações | Todos |
+| **2 — Extraction** | Spec de estrutura + conteúdo; valores estéticos (modos B/D/E) | Todos |
+| **3A — Transform** | Mapa componente → skill com tokens | A, C |
+| **3B — Skill forge** | Extrai design system e forja skill em `.aioson/installed-skills/` | B, D, E |
+| **3E — Blend** | Mescla tokens do site com tokens da skill no ratio definido | E |
+| **4 — Build** | Constrói componentes com worktrees, verifica `npm run build` | A, B, C, E |
+| **5 — QA** | Screenshot diff, testes de interação, fidelidade de tokens | A, B, C, E |
+
+**Modo D** termina após a Fase 3B — nenhum site é construído.
+
+## Output por modo
+
+```text
+Todos os modos:
+  docs/research/<hostname>/
+    reconnaissance.json        ← dados da navegação
+    crawl-manifest.json        ← URLs visitadas e assets por página
+    structure-spec.md          ← topologia e layout
+    interaction-spec.md        ← modelo de interação
+    qa-report.md               ← resultado do QA (modos A/B/C/E)
+
+Modo A, C:
+    component-map.md           ← mapeamento componente → skill
+
+Modo B, D, E:
+    aesthetics-raw.json        ← valores CSS extraídos
+
+Modo E:
+    blend-map.md               ← decisões de blend por token
+    blended-tokens.css         ← tokens mesclados prontos para uso
+
+Modos A, B, C, E (constrói site):
+  src/components/[todos os componentes]
+  src/app/page.tsx
+  src/app/globals.css
+  public/images/<hostname>/[assets baixados]
+
+Modos B, D, E (forja skill):
+  .aioson/installed-skills/<hostname>/
+    SKILL.md
+    references/design-tokens.md
+    references/components.md
+    references/patterns.md
+    references/motion.md
+    references/websites.md
+    .skill-meta.json
+```
+
+## Fluxo completo: forge + clone
+
+O caminho mais poderoso é criar uma skill sob medida com `design-hybrid-forge` e aplicá-la.
+
+### Passo 1 — Gerar o preset visual
+
+```bash
+aioson design-hybrid:options . --locale=pt-BR
+```
+
+### Passo 2 — Forjar a skill híbrida
+
+```text
+/design-hybrid-forge
+→ skills primárias: aurora-command-ui + cognitive-core-ui
+→ nome: aurora-cognitive-command
+```
+
+### Passo 3 — Aplicar no clone
+
+```text
+/site-forge https://datadog.com aurora-cognitive-command
+```
+
+Resultado: estrutura e interações do Datadog, visual da `aurora-cognitive-command`.
+
+---
+
+Veja a documentação completa do seletor interativo em: [`design-hybrid-forge.md`](design-hybrid-forge.md)
+
+---
+
+## Exemplos práticos
+
+### Modo A — Clone com skill existente
+
+```text
+/site-forge https://stripe.com aurora-command-ui
+```
+
+Estrutura e fluxo do Stripe, visual da `aurora-command-ui`.
+
+---
+
+### Modo B — Réplica fiel + nova skill
+
+```text
+/site-forge https://linear.app
+```
+
+Forja uma skill em `.aioson/installed-skills/linear.app/` e constrói uma réplica fiel.
+
+---
+
+### Modo C — Colher conteúdo + nova estrutura com skill
+
+Perguntar o modo via onboarding:
+
+```text
+/site-forge https://framer.com
+→ escolha A no onboarding
+→ skill: clean-saas-ui
+```
+
+Textos e imagens do Framer, layout e visual do `clean-saas-ui`.
+
+---
+
+### Modo D — Só a skill, sem construir
+
+```text
+/site-forge https://resend.com --skill-only
+```
+
+Forja `.aioson/installed-skills/resend.com/`. Nenhuma página é construída.
+
+---
+
+### Modo E — Blend 50/50
+
+```text
+/site-forge https://vercel.com neo-brutalist-ui --blend
+```
+
+Tokens mesclados 50% Vercel / 50% `neo-brutalist-ui`.
+
+---
+
+### Blend assimétrico (70% site)
+
+```text
+/site-forge https://notion.so glassmorphism-ui --blend=70
+```
+
+70% tokens do Notion, 30% tokens da `glassmorphism-ui`.
+
+---
+
+### Clone em projeto existente
+
+```bash
+cd meu-projeto-nextjs
+/site-forge https://loom.com cognitive-core-ui
+```
+
+O agente detecta o `package.json` com `next` e usa o projeto existente.
+
+## Diferença em relação a clonar manualmente
+
+| Aspecto | Clone manual | site-forge |
+|---------|-------------|--------------|
+| Extração de imagens | Só `<img>` visíveis | img + CSS bg + srcset + lazy + video + SVG |
+| Sub-páginas | Ignoradas | Crawl automático |
+| Estética | Replica o original | Skill tokens, blend, ou extração fiel |
+| Interações | Esquecidas facilmente | Mapeadas antes de construir |
+| Build | Erros no final | Verificado após cada worktree |
+| QA | Manual | Screenshot diff + checklist formal |
+
+## Nota sobre conteúdo e assets
+
+Os textos e imagens extraídos são apenas para estruturar o clone durante o desenvolvimento. **Substitua todo o conteúdo antes de publicar.** O agente avisa ao final da Fase 1.
+
+## Quando usar
+
+- você quer o comportamento/layout de um site de referência
+- quer prototipar rapidamente com estrutura testada
+- quer extrair o design de um site como skill reutilizável
+- quer mesclar o visual de um site com sua brand
+- o cliente mostrou um concorrente como referência de fluxo
+
+## Quando não usar
+
+- o site tem proteção pesada (SPA autenticada, bot protection agressivo)
+- você quer criar a estrutura do zero com total liberdade → use `/deyvin` ou `/dev`