@jaimevalasek/aioson 1.6.0 → 1.7.0

package/docs/pt/site-forge.md

@@ -0,0 +1,309 @@
+# `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`

package/docs/pt/spec-learnings-pipeline.md

@@ -0,0 +1,265 @@
+# Spec & Learnings Pipeline
+
+> Sincroniza specs Markdown com o SQLite e exporta learnings para memória procedural do projeto.
+
+O AIOSON mantém duas representações do estado de desenvolvimento: os arquivos `spec-{slug}.md` em `.aioson/context/` (editados pelos agentes) e o banco SQLite `aios.sqlite` (lido pelo dashboard). Este pipeline conecta os dois automaticamente.
+
+---
+
+## Visão geral do fluxo
+
+```
+@dev escreve spec-checkout.md
+  └─ ## Session Learnings: [process] commit por step
+  └─ frontmatter: phase_gates: {plan: approved}
+  └─ last_checkpoint: "Criando migration cart_items — step 3 de 5"
+
+aioson spec:sync .
+  └─ project_learnings ← learnings upserted (frequency++)
+  └─ plan_phases ← phase_gates mapeadas para status
+
+aioson spec:status .
+  └─ tabela de features com fase, agente, checkpoint
+
+aioson learning:export . --min-frequency=2
+  └─ .aioson/brains/process-commit-por-step.md  ← node Zettelkasten
+
+aioson learning:evolve .
+  └─ genome ← learnings com frequency ≥ 5 promovidos
+```
+
+---
+
+## `aioson spec:sync`
+
+Sincroniza learnings e phase gates de todos os specs para o SQLite.
+
+```bash
+aioson spec:sync [path] [opções]
+```
+
+**Opções:**
+
+| Opção | Descrição |
+|---|---|
+| `--json` | Retorna JSON com contagem de learnings e fases sincronizadas |
+| `--verbose` | Mostra detalhes de cada arquivo processado |
+
+**Exemplo:**
+
+```bash
+aioson spec:sync .
+```
+
+Saída:
+
+```
+Spec Sync — meu-projeto
+──────────────────────────────────────────────────
+spec-checkout.md
+  Learnings synced: 3
+  Plan phases updated: 1
+  last_checkpoint: "Criando migration cart_items"
+spec.md
+  Learnings synced: 2
+──────────────────────────────────────────────────
+Summary: 5 learnings synced, 1 plan phases updated
+```
+
+**Formato dos learnings no spec:**
+
+```markdown
+## Session Learnings
+- [process] Fazer commit após cada step atômico, não só no final
+- [domain] cart_items deve ter UNIQUE(cart_id, product_id)
+- [quality] Rodar testes com --filter isola o módulo rapidamente
+```
+
+Prefixos aceitos: `[process]`, `[domain]`, `[quality]`, `[preference]`.  
+Linhas sem prefixo são classificadas automaticamente como `[process]`.
+
+**Idempotência:** rodar `spec:sync` duas vezes no mesmo spec não duplica learnings. Se o título já existe em `project_learnings`, o campo `frequency` é incrementado (`frequency++`).
+
+---
+
+## `aioson spec:status`
+
+Exibe o estado atual de todas as features com dados do SQLite.
+
+```bash
+aioson spec:status [path] [opções]
+```
+
+**Opções:**
+
+| Opção | Descrição |
+|---|---|
+| `--json` | Retorna JSON com array de features e contagem de learnings |
+
+**Exemplo:**
+
+```bash
+aioson spec:status .
+```
+
+Saída:
+
+```
+Project Status — meu-projeto
+────────────────────────────────────────────────────────────────────────────────
+Feature             Phase     Status          Last Agent      Checkpoint
+────────────────────────────────────────────────────────────────────────────────
+checkout            2/5       in_progress     dev             Criando migration...
+auth                5/5       done            qa              QA sign-off 2026-03-28
+onboarding          0/5       not_started     —               —
+────────────────────────────────────────────────────────────────────────────────
+Active learnings: 12  |  Promotable (freq≥3): 4
+```
+
+---
+
+## `aioson spec:checkpoint`
+
+Registra manualmente o `last_checkpoint` de um spec no SQLite. Útil quando a sessão caiu sem `agent:done`.
+
+```bash
+aioson spec:checkpoint [path] --feature=<slug> [--agent=<agent>]
+```
+
+**Opções:**
+
+| Opção | Descrição |
+|---|---|
+| `--feature=<slug>` | Feature cujo spec será lido (obrigatório) |
+| `--agent=<name>` | Agente da run ativa (padrão: `dev`) |
+| `--json` | Retorna JSON com run_key e checkpoint registrado |
+
+**Exemplo:**
+
+```bash
+# Sessão do @dev em checkout caiu sem agent:done
+aioson spec:checkpoint . --feature=checkout
+```
+
+Saída:
+
+```
+Reading spec-checkout.md...
+last_checkpoint: "Criando migration cart_items — step 3 of 5"
+phase_gates: {"plan":"approved","requirements":"approved","design":"pending"}
+
+Checkpoint registered:
+  run_key: dev-1711234567890
+  summary: "Criando migration cart_items — step 3 of 5"
+  status: in_progress (checkpoint only — use agent:done to close)
+
+Next: continue with /dev — start from last_checkpoint
+```
+
+O comando procura a run mais recente do agente no SQLite e registra um evento `plan_checkpoint` nela. O run permanece `in_progress` — use `agent:done` para fechá-la quando terminar.
+
+---
+
+## `aioson learning:export`
+
+Exporta `project_learnings` do SQLite para `.aioson/brains/` como nodes no formato Zettelkasten.
+
+```bash
+aioson learning:export [path] [--min-frequency=N] [--json]
+```
+
+**Opções:**
+
+| Opção | Descrição |
+|---|---|
+| `--min-frequency=N` | Exporta apenas learnings com `frequency >= N` (padrão: 1) |
+| `--json` | Retorna JSON com lista de nodes exportados |
+
+**Exemplos:**
+
+```bash
+# Exportar todos os learnings ativos
+aioson learning:export .
+
+# Apenas learnings reforçados em 2+ sessões
+aioson learning:export . --min-frequency=2
+```
+
+Saída:
+
+```
+Learning Export — min-frequency: 2
+──────────────────────────────────────────────────
+  process-commit-por-step.md ✓ (frequency: 4)
+  domain-cart-uniqueness.md ✓ (frequency: 3)
+  process-test-isolation.md ✓ (frequency: 2)
+──────────────────────────────────────────────────
+3 nodes written to .aioson/brains/
+2 learning(s) with frequency ≥ 5 — run: aioson learning:evolve to promote to genome
+```
+
+**Formato do node exportado** (`.aioson/brains/process-commit-por-step.md`):
+
+```markdown
+---
+id: process-commit-por-step
+type: process
+title: Fazer commit após cada step atômico, não só no final
+frequency: 4
+last_reinforced: 2026-04-01
+source_feature: checkout
+promoted_to: null
+created_at: 2026-03-15
+---
+
+# Fazer commit após cada step atômico
+
+**Evidence:** Detected in 4 session(s).
+
+## Applications
+- Review and apply this learning in future sessions of type: process
+
+## Links
+<!-- Add cross-references here -->
+```
+
+---
+
+## Fluxo recomendado após cada sessão do @dev
+
+```bash
+# 1. Sincronizar spec com o SQLite
+aioson spec:sync .
+
+# 2. Ver estado atual das features
+aioson spec:status .
+
+# 3. Quando learnings se acumularem (≥ 2 sessões), exportar para brains
+aioson learning:export . --min-frequency=2
+
+# 4. Quando um learning atingir frequency ≥ 5, promover para genome
+aioson learning:evolve .
+```
+
+---
+
+## Integração com o spec.md
+
+O `spec:sync` procura esses elementos em cada `spec-{slug}.md`:
+
+| Elemento | Onde fica | O que faz |
+|---|---|---|
+| `## Session Learnings` | Corpo do arquivo | Cria/atualiza `project_learnings` |
+| `phase_gates` | Frontmatter YAML | Atualiza `plan_phases.status` |
+| `last_checkpoint` | Frontmatter ou seção | Exibido em `spec:status` |
+
+**Exemplo de frontmatter de spec:**
+
+```markdown
+---
+feature: checkout
+status: in_progress
+phase_gates: {"plan": "approved", "requirements": "approved", "design": "pending"}
+last_checkpoint: "Criando migration cart_items — step 3 de 5"
+---
+```

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@jaimevalasek/aioson",
-  "version": "1.6.0",
+  "version": "1.7.0",
   "description": "AI operating framework for hyper-personalized software.",
   "keywords": [
     "ai",