@jaimevalasek/aioson 1.5.1 → 1.7.0

package/docs/pt/design-hybrid-forge.md

@@ -0,0 +1,356 @@
+# `design-hybrid-forge`
+
+Página canônica do fluxo de criação de skills híbridas de design do AIOSON.
+
+Esse fluxo existe para transformar 2 skills de design já existentes em uma nova skill local do projeto, com suporte opcional a um preset visual temporário gerado por `design-hybrid:options`.
+
+## O que ele faz
+
+- cria uma nova skill em `.aioson/installed-skills/{slug}/`
+- exige 2 skills primárias
+- aceita 0 a 2 modificadores por padrão
+- aceita 0 a 3 modificadores no modo avançado
+- pode aplicar um overlay visual mais extravagante, clássico, animado ou CSS-forward
+- registra autor, modelo e origem quando esses dados estiverem disponíveis
+- preserva histórico da geração em `.aioson/context/history/design-variation-presets/`
+
+## Fluxo recomendado
+
+1. Escolha ou confirme as 2 skills primárias.
+2. Se quiser uma direção visual mais marcada, rode `aioson design-hybrid:options`.
+3. O comando monta um preset em `.aioson/context/design-variation-preset.md`.
+4. O agente `@design-hybrid-forge` lê esse preset e conduz a síntese.
+5. A skill final nasce em `.aioson/installed-skills/{slug}/`.
+6. Depois da geração, o preset ativo deve sair do contexto e ficar só o histórico.
+
+## Locale
+
+O seletor usa `conversation_language` do `project.context.md` quando existir.
+
+Se você quiser forçar a interface, use:
+
+```bash
+aioson design-hybrid:options . --locale=pt-BR
+```
+
+Use `--locale` como override, não como regra principal.
+
+## Modificadores
+
+Por padrão, o sistema trabalha com até 2 modificadores. Eles servem para lanes pequenas:
+
+- motion
+- textura
+- tipografia
+- navegação secundária
+- detalhes de componentes
+
+No modo avançado, `aioson design-hybrid:options --advanced` libera um 3º modificador. Mesmo assim, ele continua sem poder assumir substrato ou estrutura.
+
+## Preset temporário
+
+O arquivo `.aioson/context/design-variation-preset.md` não é configuração permanente do projeto.
+
+Ele deve ser tratado como:
+
+- input temporário para a próxima geração
+- referência de execução para a skill híbrida
+- artefato descartável após a geração
+
+A cópia em `.aioson/context/history/design-variation-presets/` é a trilha de auditoria e pode ficar arquivada.
+
+## Onde a skill nasce
+
+O destino padrão é sempre:
+
+```text
+.aioson/installed-skills/{slug}/
+```
+
+Esse é o local que o AIOSON usa para skills instaladas ou geradas localmente no projeto. Se houver promoção para o core ou marketplace, isso é uma segunda etapa separada.
+
+## Quando usar
+
+Use esse fluxo quando você quiser:
+
+- criar uma skill de design nova a partir de duas já existentes
+- evitar resultado genérico ou "mais do mesmo"
+- combinar estrutura de uma skill com a expressão visual de outra
+- gerar uma skill local versionada no projeto
+
+Não use esse fluxo para aplicar uma skill em um produto já existente. Nesse caso, use a skill final gerada em seu próprio `SKILL.md`.
+
+---
+
+## Como funciona o `aioson design-hybrid:options`
+
+O comando abre um seletor interativo no terminal com 7 grupos de perguntas. Cada grupo é apresentado um de cada vez — você responde, confirma, e avança para o próximo.
+
+### Navegação
+
+```
+↑ / ↓    mover o cursor entre opções
+espaço   marcar / desmarcar uma opção
+enter    confirmar as seleções do grupo atual e avançar
+q        cancelar tudo
+```
+
+Cada grupo permite múltiplas seleções. Ao pressionar enter, você avança para o próximo grupo automaticamente.
+
+---
+
+### Grupo 1 — Modos de estilo
+
+> Escolha de 1 a 3 atitudes visuais gerais.
+
+| Opção | O que significa |
+|-------|----------------|
+| `classic-editorial` | Hierarquia medida, autoridade com serifa, luxo mais contido |
+| `extravagant-maximalist` | Camadas densas, cor forte, abundância visual deliberada |
+| `cinematic-immersive` | Narrativa atmosférica, contraste dramático, seções como cenas |
+| `playful-dopamine` | Paletas vibrantes, energia otimista, detalhes expressivos |
+| `neo-brutalist` | Arestas duras, estrutura visível, rejeição da polidez genérica |
+| `retrofuturist` | Cromado, nostalgia sci-fi, otimismo arcade, futuro visto pelo passado |
+| `luxury-modern` | Alto refinamento, respiro premium, ornamento seletivo, acabamento forte |
+| `collage-handmade` | Ritmo de recorte, mixed media, imperfeição intencional |
+
+---
+
+### Grupo 2 — Movimentos de layout
+
+> Escolha de 1 a 3 assinaturas de layout.
+
+| Opção | O que significa |
+|-------|----------------|
+| `asymmetric-composition` | Peso desigual, blocos deslocados, tensão no lugar da simetria genérica |
+| `narrative-scroll` | As seções se comportam como capítulos, não como pilhas de cards |
+| `experimental-navigation` | Gavetas ocultas, ideias radiais, exploração em mapa, entradas não convencionais |
+| `dense-mosaic` | Muitas superfícies, tamanhos variados de cards, colagem de informação |
+| `split-screen` | Tensão persistente entre duas zonas visuais |
+| `hero-signature` | Composição de abertura marcante que define o sistema inteiro |
+
+---
+
+### Grupo 3 — Sistema de motion
+
+> Escolha de 0 a 3 direções de motion.
+
+| Opção | O que significa |
+|-------|----------------|
+| `restrained-microinteractions` | Feedback preciso e funcional, sem espetáculo gratuito |
+| `kinetic-typography` | Tipografia animada como camada principal de narrativa |
+| `scroll-driven-scenes` | Seções animam pelo progresso do scroll, não por reveals genéricos |
+| `view-transitions` | A navegação carrega continuidade entre telas e estados |
+| `cursor-reactive` | Proximidade do ponteiro, profundidade no hover, highlights reativos |
+| `gamified-feedback` | Mudanças de estado lúdicas, loops de recompensa, momentos de delight |
+
+---
+
+### Grupo 4 — Materiais e texturas
+
+> Escolha de 0 a 3 linguagens de superfície.
+
+| Opção | O que significa |
+|-------|----------------|
+| `glass-layers` | Blur, translucidez, bordas luminosas, profundidade via substrato |
+| `grain-noise` | Textura controlada para quebrar a suavidade digital |
+| `paper-editorial` | Superfícies quentes, ritmo de impresso, sombras e fibras sutis |
+| `chrome-metallic` | Highlights especulares, acabamento de luxo futurista, reflexos |
+| `soft-neumorphic` | Controles elevados/escavados com sensação tátil usados com moderação |
+| `collage-cutout` | Fragmentos em camadas, bordas coladas, sensação de mixed media |
+
+---
+
+### Grupo 5 — Movimentos tipográficos
+
+> Escolha de 1 a 3 direções tipográficas.
+
+| Opção | O que significa |
+|-------|----------------|
+| `bold-display` | Títulos grandes com personalidade forte |
+| `variable-font-axes` | Variação de peso/largura/tamanho óptico usada como material de design |
+| `serif-revival` | Calor, autoridade ou profundidade cultural contra a fadiga digital |
+| `mono-rails` | Labels técnicos e ritmo de metadata como dispositivo estrutural |
+| `compressed-headlines` | Drama alto ou condensado para sistemas cinematográficos ou editoriais |
+| `mixed-type-system` | Duas ou mais famílias com papéis bem separados |
+
+---
+
+### Grupo 6 — CSS avançado
+
+> Escolha de 0 a 4 técnicas de implementação.
+
+| Opção | O que significa |
+|-------|----------------|
+| `scroll-driven-animations` | Use timelines de scroll/view em CSS para lógica de cenas |
+| `view-transition-api` | Carrega continuidade entre rotas ou estados da UI |
+| `mask-clip-path` | Revelações não retangulares, janelas de imagem, cortes ornamentais |
+| `svg-filters-noise` | Distorção, grão, displacement, imperfeição tátil |
+| `backdrop-filter` | Profundidade de vidro e translucidez em camadas |
+| `3d-transforms` | Cards em perspectiva, pilhas com profundidade, momentos de hero imersivos |
+| `sticky-storytelling` | Capítulos fixados, revelações progressivas, narrativa encenada |
+
+---
+
+### Grupo 7 — Guardrails anti-mesmice
+
+> Escolha de 2 a 4 traços que devem aparecer no resultado final.
+
+| Opção | O que significa |
+|-------|----------------|
+| `avoid-generic-hero` | A seção de abertura precisa ter um movimento estrutural distintivo |
+| `uneven-rhythm` | Quebre a monotonia da grade repetitiva com variação controlada |
+| `domain-specific-ornament` | A linguagem visual deve vir do domínio do produto, não do clichê SaaS |
+| `signature-surface` | Pelo menos um tratamento de superfície deve ser inconfundível |
+| `color-courage` | Permita contraste mais forte ou paleta mais rica quando servir à identidade |
+| `motion-with-purpose` | Motion precisa comunicar hierarquia ou sensação, não preencher espaço |
+
+---
+
+### O que o comando gera
+
+Após as 7 telas, o seletor salva dois arquivos:
+
+- **Ativo:** `.aioson/context/design-variation-preset.md` — lido pelo `@design-hybrid-forge` na próxima execução
+- **Histórico:** `.aioson/context/history/design-variation-presets/<timestamp>.md` — trilha permanente
+
+E exibe no terminal o bloco YAML para copiar direto ao prompt, caso prefira não usar o arquivo:
+
+```yaml
+variation_overlay:
+  style_modes:
+    - cinematic-immersive
+    - luxury-modern
+  layout_moves:
+    - hero-signature
+    - narrative-scroll
+  motion_system:
+    - scroll-driven-scenes
+    - restrained-microinteractions
+  materials_textures:
+    - glass-layers
+  typography_moves:
+    - compressed-headlines
+    - mixed-type-system
+  advanced_css:
+    - scroll-driven-animations
+    - backdrop-filter
+  anti_sameness:
+    - avoid-generic-hero
+    - signature-surface
+    - motion-with-purpose
+```
+
+---
+
+## Exemplos práticos
+
+### Dashboard SaaS dark com vidro e comando
+
+Perfil: produto técnico, B2B, dark mode obrigatório.
+
+Seleções no `design-hybrid:options`:
+
+```
+Style modes:        cinematic-immersive, luxury-modern
+Layout moves:       hero-signature, dense-mosaic
+Motion system:      restrained-microinteractions, scroll-driven-scenes
+Materials:          glass-layers
+Typography:         mono-rails, bold-display
+Advanced CSS:       backdrop-filter, scroll-driven-animations
+Anti-sameness:      avoid-generic-hero, signature-surface, motion-with-purpose
+```
+
+Depois ativar:
+
+```text
+/design-hybrid-forge
+→ skills primárias: aurora-command-ui + cognitive-core-ui
+→ nome sugerido: aurora-cognitive-command
+```
+
+---
+
+### Landing page de produto consumer com energia lúdica
+
+Perfil: app mobile, público jovem, cor como protagonista.
+
+Seleções no `design-hybrid:options`:
+
+```
+Style modes:        playful-dopamine, extravagant-maximalist
+Layout moves:       asymmetric-composition, hero-signature
+Motion system:      gamified-feedback, cursor-reactive, kinetic-typography
+Materials:          grain-noise, collage-cutout
+Typography:         bold-display, variable-font-axes
+Advanced CSS:       view-transition-api, mask-clip-path
+Anti-sameness:      color-courage, uneven-rhythm, avoid-generic-hero, domain-specific-ornament
+```
+
+Depois ativar:
+
+```text
+/design-hybrid-forge
+→ skills primárias: warm-craft-ui + neo-brutalist-ui
+→ nome sugerido: warm-brutalist-play
+```
+
+---
+
+### Site editorial para marca de luxo
+
+Perfil: marca premium, slow content, autoridade visual.
+
+Seleções no `design-hybrid:options`:
+
+```
+Style modes:        classic-editorial, luxury-modern
+Layout moves:       narrative-scroll, split-screen
+Motion system:      restrained-microinteractions, view-transitions
+Materials:          paper-editorial, grain-noise
+Typography:         serif-revival, compressed-headlines
+Advanced CSS:       sticky-storytelling, view-transition-api
+Anti-sameness:      domain-specific-ornament, signature-surface, color-courage
+```
+
+Depois ativar:
+
+```text
+/design-hybrid-forge
+→ skills primárias: bold-editorial-ui + clean-saas-ui
+→ nome sugerido: luxury-editorial-saas
+```
+
+---
+
+## Exemplos de uso do CLI
+
+Criar preset visual interativo:
+
+```bash
+aioson design-hybrid:options .
+```
+
+Forçar PT-BR e modo avançado (3 modificadores):
+
+```bash
+aioson design-hybrid:options . --locale=pt-BR --advanced
+```
+
+Inspecionar o catálogo completo sem abrir a UI interativa:
+
+```bash
+aioson design-hybrid:options . --json
+```
+
+Depois, ativar a skill híbrida gerada:
+
+```text
+@design-hybrid-forge
+```
+
+ou, em clientes com slash commands:
+
+```text
+/design-hybrid-forge
+```

package/docs/pt/devlog-pipeline.md

@@ -0,0 +1,270 @@
+# Devlog Pipeline
+
+> Processa devlogs escritos manualmente pelos agentes e sincroniza artifacts, decisions, learnings e verdict com o SQLite.
+
+Quando o CLI `aioson` não está disponível (ex: Claude Code sem terminal, sessão sem live session ativa), os agentes escrevem devlogs em `aioson-logs/`. O devlog pipeline importa esses arquivos para o SQLite automaticamente, garantindo visibilidade no dashboard mesmo quando o CLI não foi chamado durante a sessão.
+
+---
+
+## Formato do devlog
+
+Salvar em: `aioson-logs/devlog-{agent}-{unix-timestamp}.md`
+
+```markdown
+---
+agent: dev
+feature: checkout
+session_key: direct-session:1711234567890:dev
+started_at: 2026-04-01T14:23:00Z
+finished_at: 2026-04-01T15:45:00Z
+status: completed
+verdict: null
+plan_step: FASE-1
+---
+
+# Devlog: @dev — checkout — 2026-04-01
+
+## Summary
+Implementei a migration de cart_items e o AddToCart action com testes unitários.
+
+## Artifacts
+- src/database/migrations/003_cart_items.ts
+- src/actions/cart/AddToCart.ts
+- tests/cart/AddToCart.test.ts
+
+## Decisions
+- UUID para cart_id em vez de auto-increment — compatibilidade com múltiplas sessões
+
+## Learnings
+- [process] Rodar `npm test -- --filter=cart` isola testes do módulo rapidamente
+- [domain] cart_items deve ter constraint UNIQUE(cart_id, product_id) para evitar duplicatas
+
+## Blockers
+- Nenhum
+```
+
+**Campos obrigatórios:** `agent`, `started_at`, `finished_at`.  
+**Campos opcionais:** `feature`, `session_key`, `status`, `verdict`, `plan_step`.
+
+**Devlog mínimo** (para sessões interrompidas):
+
+```markdown
+---
+agent: dev
+feature: checkout
+status: partial
+started_at: 2026-04-01T14:23:00Z
+finished_at: 2026-04-01T14:58:00Z
+---
+## Summary
+Comecei a migration de cart_items — parei no step 2 de 5.
+## Learnings
+- [process] Sempre rodar migrations em ambiente de teste antes de commitar
+```
+
+---
+
+## `aioson devlog:process`
+
+Processa todos os devlogs pendentes de `aioson-logs/` e sincroniza com o SQLite.
+
+```bash
+aioson devlog:process [path] [opções]
+```
+
+**Opções:**
+
+| Opção | Descrição |
+|---|---|
+| `--json` | Retorna JSON com lista de resultados e contagens |
+
+**O que o comando faz para cada devlog:**
+
+| Seção | Destino no SQLite |
+|---|---|
+| `## Artifacts` (caminhos de arquivo) | Tabela `artifacts` vinculada à run |
+| `## Decisions` | `execution_events` com tipo `decision` |
+| `## Learnings` (`[tipo] texto`) | `project_learnings` (upsert — frequency++) |
+| `verdict` no frontmatter | `execution_events.verdict` (PASS/FAIL/PARTIAL) |
+| `## Summary` | `agent_runs.summary` |
+
+**Exemplo:**
+
+```bash
+aioson devlog:process .
+```
+
+Saída:
+
+```
+Devlog Processing — meu-projeto
+──────────────────────────────────────────────────
+Found 3 devlog(s):
+
+devlog-dev-1711234567.md
+  run: dev-1711234567890
+  Artifacts: 3 registered ✓
+  Decisions: 1 logged ✓
+  Learnings: 2 upserted ✓
+
+devlog-qa-1711237890.md
+  run: qa-1711237890123
+  Artifacts: 1 registered ✓
+  Learnings: 1 upserted ✓
+  Verdict: PASS ✓
+
+devlog-dev-1711241234.md — ⚠ missing frontmatter or agent field. Fix and re-run.
+──────────────────────────────────────────────────
+Processed: 2/3 devlogs
+New learnings: 3 (queued for brains export)
+Artifacts registered: 4
+```
+
+**Idempotência:** devlogs já processados recebem `processed_at` no frontmatter. Rodar o comando novamente os ignora.
+
+---
+
+## `aioson devlog:watch`
+
+Daemon que observa `aioson-logs/` e processa automaticamente novos devlogs assim que são criados.
+
+```bash
+aioson devlog:watch [path] [opções]
+```
+
+**Opções:**
+
+| Opção | Descrição |
+|---|---|
+| `--poll` | Forçar modo polling (padrão automático no WSL2) |
+
+**Detecção automática de WSL2:** o comando lê `/proc/version` e, se detectar `microsoft`, usa polling de 5 segundos em vez de `fs.watch` (que tem comportamento instável no WSL2).
+
+**Exemplos:**
+
+```bash
+# Iniciar em background
+aioson devlog:watch . &
+
+# Ver output ao vivo (sem background)
+aioson devlog:watch .
+
+# Forçar polling em qualquer ambiente
+aioson devlog:watch . --poll &
+```
+
+Saída durante operação:
+
+```
+[DEVLOG WATCHER] WSL2 detected — using polling (5s interval)
+[DEVLOG WATCHER] Watching /meu-projeto/aioson-logs for new devlogs...
+[DEVLOG WATCHER] Press Ctrl+C to stop.
+[14:47:08] New: devlog-dev-1711237890.md → processing...
+[14:47:09] Processed: devlog-dev-1711237890.md → 2 learnings, 3 artifacts → SQLite ✓
+[14:51:33] New: devlog-qa-1711238200.md → processing...
+[14:51:34] Processed: devlog-qa-1711238200.md → VERDICT: PASS → SQLite ✓
+```
+
+Para parar: `Ctrl+C` ou `kill %1` se rodou em background.
+
+---
+
+## `aioson devlog:export-brains`
+
+Exporta learnings de alta frequência dos devlogs para `.aioson/brains/` como nodes Zettelkasten.
+
+Funciona exatamente como `learning:export` mas com `--min-frequency=2` por padrão (mais conservador para o pipeline de devlogs).
+
+```bash
+aioson devlog:export-brains [path] [--min-frequency=N] [--json]
+```
+
+**Exemplos:**
+
+```bash
+# Exportar learnings reforçados em 2+ sessões (padrão)
+aioson devlog:export-brains .
+
+# Mais seletivo: apenas learnings reforçados em 3+ sessões
+aioson devlog:export-brains . --min-frequency=3
+```
+
+Saída:
+
+```
+Learning Export — min-frequency: 2
+──────────────────────────────────────────────────
+  process-commit-por-step.md ✓ (frequency: 4)
+  domain-cart-uniqueness.md ✓ (frequency: 3)
+──────────────────────────────────────────────────
+2 nodes written to .aioson/brains/
+Run: aioson learning:evolve to promote high-frequency nodes to genome.
+```
+
+---
+
+## Pipeline completo
+
+### Modo manual (pós-sessão)
+
+```bash
+# 1. Processar devlogs acumulados
+aioson devlog:process .
+
+# 2. Checar estado das features
+aioson spec:status .
+
+# 3. Exportar learnings para brains
+aioson devlog:export-brains . --min-frequency=2
+
+# 4. Promover para genome quando frequency ≥ 5
+aioson learning:evolve .
+```
+
+### Modo automático (background durante sessão)
+
+```bash
+# Iniciar watcher em background antes de começar a sessão
+aioson devlog:watch . &
+
+# ... trabalhar normalmente, escrever devlogs ao final de cada subsessão ...
+
+# Depois da sessão: apenas exportar para brains
+aioson devlog:export-brains . --min-frequency=2
+```
+
+---
+
+## Devlog de @qa com verdict
+
+O devlog do `@qa` deve incluir `verdict` no frontmatter para que o pipeline registre automaticamente o veredito no SQLite:
+
+```markdown
+---
+agent: qa
+feature: checkout
+status: completed
+verdict: PASS
+started_at: 2026-04-01T16:00:00Z
+finished_at: 2026-04-01T17:30:00Z
+---
+## Summary
+QA checkout — PASS. 5-step baseline + 2 adversarial probes. Sem regressões.
+## Artifacts
+- output/qa/checkout-qa-report.md
+## Learnings
+- [quality] Testar cart com 0 itens é caso de borda crítico — sempre incluir no baseline
+```
+
+Após `devlog:process`, o veredito `PASS` aparece em `execution_events.verdict` e fica pesquisável no dashboard.
+
+---
+
+## Diferença entre `devlog:process` e `devlog:sync`
+
+| Comando | Faz |
+|---|---|
+| `devlog:sync` | Import básico: cria task + run + eventos de seção. Sem extração de learnings, artifacts ou verdict. |
+| `devlog:process` | Import enriquecido: learnings → `project_learnings`, artifacts → tabela `artifacts`, decisions → `execution_events`, verdict → `execution_events.verdict`. |
+
+Use `devlog:process` para o pipeline completo. `devlog:sync` é o comando legado mais simples.