@jaimevalasek/aioson 1.5.1 → 1.6.0

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

@@ -0,0 +1,107 @@
+# `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`.
+
+## Exemplos
+
+Criar preset visual:
+
+```bash
+aioson design-hybrid:options .
+```
+
+Forçar PT-BR e modo avançado:
+
+```bash
+aioson design-hybrid:options . --locale=pt-BR --advanced
+```
+
+Depois, ativar a skill híbrida gerada:
+
+```text
+@nome-da-skill
+```
+
+ou, em clientes com slash commands:
+
+```text
+/nome-da-skill
+```

package/docs/pt/inicio-rapido.md

@@ -12,11 +12,20 @@
 
 ## 1. Instalação
 
+Ao rodar o `init` ou `install`, um **wizard interativo** aparece para você escolher:
+
+1. **Quais ferramentas AI** usar (Claude Code, Codex, Gemini, OpenCode)
+2. **Qual modo** (Development ou Development + Squads)
+3. **Design system** (opcional) — Clean SaaS UI, Aurora Command UI, Cognitive Core UI, etc.
+4. **Idioma dos agentes** — English, Português, Español, Français
+
+Só os arquivos relevantes são copiados. Nenhuma dependência extra é instalada.
+
 ### Novo projeto (recomendado)
 
 ```bash
-mkdir meu-projeto && cd meu-projeto
-npx @jaimevalasek/aioson init
+npx @jaimevalasek/aioson init meu-projeto
+cd meu-projeto
 ```
 
 ### Projeto existente
@@ -26,7 +35,49 @@ cd meu-projeto
 npx @jaimevalasek/aioson install
 ```
 
-Isso cria a pasta `.aioson/` com todos os arquivos de configuração, agentes e contexto.
+### Instalar tudo de uma vez (`--all`)
+
+Use `--all` para pular o wizard e instalar imediatamente com todas as ferramentas e squads ativados:
+
+```bash
+# Cria projeto e instala tudo (sem wizard)
+npx @jaimevalasek/aioson init meu-projeto --all
+
+# Instala em projeto existente (todas as ferramentas + squads)
+npx @jaimevalasek/aioson install --all
+```
+
+**O que o `--all` instala:**
+- Ferramentas: Claude Code, Codex, Gemini, OpenCode
+- Modo: Development + Squads
+- Design: nenhum
+- Idioma: English
+
+### Re-configurar depois (adicionar ferramentas/modos)
+
+Se precisar adicionar uma ferramenta ou ativar Squads depois:
+
+```bash
+npx @jaimevalasek/aioson install --reconfigure
+```
+
+Isso roda o wizard novamente — só os arquivos relevantes ao novo perfil são atualizados.
+
+### CI / automação (sem wizard)
+
+```bash
+npx @jaimevalasek/aioson install --no-interactive
+```
+
+Instala todos os arquivos sem perguntar (comportamento padrão antes do wizard).
+
+### Atualizar para nova versão
+
+```bash
+npx @jaimevalasek/aioson update
+```
+
+O update respeita o perfil salvo — só atualiza os arquivos que foram instalados originalmente.
 
 Se o projeto já for brownfield e você quiser gerar um panorama inicial da base, rode depois:
 

package/docs/pt/inteligencia-adaptativa.md

@@ -0,0 +1,324 @@
+# Inteligência Adaptativa
+
+O AIOSON aprende com o trabalho dos agentes e evolui com o projeto. Este documento explica os três sistemas que formam a camada de inteligência adaptativa: o **Evolution Pipeline**, o **Tool Registry** e o **Ambient Intelligence Layer**.
+
+---
+
+## Visão Geral
+
+Sem inteligência adaptativa, o AIOSON funciona como uma ferramenta estática: os agentes trabalham, cometem os mesmos erros, repetem os mesmos comandos — e cada sessão começa do zero.
+
+Com inteligência adaptativa:
+
+- Correções que você dá aos agentes viram **regras permanentes no contexto do projeto**
+- Ferramentas criadas por um agente ficam disponíveis em **todas as sessões futuras**
+- O framework **avisa proativamente** quando há itens que precisam de atenção
+
+---
+
+## 1. Evolution Pipeline
+
+### O que é
+
+Um pipeline que transforma learnings acumulados em arquivos de configuração do projeto. Em vez de depender de você lembrar de promover learnings manualmente, o AIOSON analisa os padrões e propõe — ou aplica — as mudanças automaticamente.
+
+### Como funciona
+
+Durante as sessões, os agentes registram learnings no banco de dados com tipo, título, frequência e evidências. Quando você roda `aioson learning:evolve`, o pipeline:
+
+1. Filtra learnings com frequência ≥ 2 (ocorreram ao menos duas vezes)
+2. Agrupa por tipo (preferência, processo, domínio, qualidade)
+3. Gera deltas — mudanças propostas para arquivos de contexto e regras
+4. Roda dois gates de validação antes de aprovar cada delta
+5. Aplica os aprovados ou salva uma proposta para revisão
+
+**Gate 1 — Constitucional:** nenhum delta pode tocar arquivos em `.aioson/agents/`. Esses arquivos são imutáveis — são a identidade dos agentes, não configuração de projeto.
+
+**Gate 2 — Tamanho:** arquivos alvo não podem ultrapassar 300 linhas após o append. Evita que o contexto cresça sem controle.
+
+### Mapeamento de tipos para arquivos
+
+| Tipo de learning | Arquivo alvo |
+|---|---|
+| `preference` | `.aioson/context/project.context.md` → seção Preferências |
+| `domain` | `.aioson/context/project.context.md` → seção Conhecimento de Domínio |
+| `quality` | `.aioson/context/project.context.md` → seção Padrões de Qualidade |
+| `process` | `.aioson/rules/<squad>-process.md` (ou `project-process.md`) |
+
+### Comandos
+
+```bash
+# Ver o que seria evoluído (sem aplicar)
+aioson learning:evolve .
+aioson learning:evolve . --dry-run
+
+# Aplicar automaticamente sem perguntar
+aioson learning:evolve . --auto-apply
+
+# Filtrar por squad específico
+aioson learning:evolve . --squad=backend --dry-run
+
+# Aplicar um arquivo de proposta salvo
+aioson learning:apply . --file=.aioson/evolution/pending-2026-03-30T12-00-00.json
+```
+
+### Exemplos práticos
+
+**Cenário:** durante 3 sessões com o agente `/dev`, você corrigiu o mesmo erro — o agente tentava criar arquivos `.ts` num projeto que usa apenas `.js`.
+
+O agente registrou um learning `correction` a cada sessão. Com frequência 3:
+
+```bash
+aioson learning:evolve . --dry-run
+```
+
+Saída:
+```
+Analisando 3 learnings elegíveis...
+
+Deltas propostos: 1 aprovado, 0 rejeitados
+
+  [1] APPEND → .aioson/context/project.context.md
+      Seção: ## Preferências dos Agentes
+      Learnings: 3 (preference)
+      - Este projeto usa CommonJS (.js). Nunca criar arquivos .ts. (alta confiança)
+        > Corrigido 3 vezes em sessões de /dev
+```
+
+```bash
+aioson learning:evolve . --auto-apply
+# ✓ Aplicado: .aioson/context/project.context.md (+3 learnings)
+# 1 delta(s) aplicado(s) com sucesso.
+```
+
+Na próxima sessão, o agente lê o contexto atualizado e não comete mais o erro.
+
+**Cenário:** equipe tem padrões de processo que emergem das sessões.
+
+```bash
+aioson learning:evolve . --squad=backend
+# Gera .aioson/rules/backend-process.md com os padrões consolidados
+```
+
+---
+
+## 2. Dynamic Tool Registry
+
+### O que é
+
+Um registro persistente de ferramentas criadas pelos próprios agentes durante o trabalho. Uma ferramenta registrada hoje fica disponível em todas as sessões futuras do projeto — sem que você precise configurar nada.
+
+### Como funciona
+
+As tools são armazenadas no banco SQLite do projeto (`dynamic_tools`). Cada tool tem:
+- Nome único por projeto
+- Descrição
+- Tipo: `shell` (comando bash inline) ou `script` (arquivo Node.js)
+- Squad opcional (se omitido, disponível para todos os agentes)
+
+A execução acontece via subprocess isolado com ambiente restrito — variáveis como `ANTHROPIC_API_KEY` nunca são passadas para as tools.
+
+### Comandos
+
+```bash
+# Registrar uma tool do tipo shell
+aioson tool:register . \
+  --name=run_tests \
+  --description="Roda os testes do projeto" \
+  --type=shell \
+  --cmd="npm test"
+
+# Registrar com filtro de squad
+aioson tool:register . \
+  --name=seed_db \
+  --description="Popula o banco de desenvolvimento" \
+  --type=shell \
+  --cmd="npm run db:seed" \
+  --squad=backend
+
+# Registrar um script Node.js
+aioson tool:register . \
+  --name=check_coverage \
+  --description="Verifica cobertura de testes" \
+  --type=script \
+  --path=.aioson/tools/check-coverage.js
+
+# Listar todas as tools
+aioson tool:list .
+
+# Listar tools de um squad
+aioson tool:list . --squad=backend
+
+# Chamar uma tool
+aioson tool:call . --name=run_tests --input='{}'
+
+# Chamar com input
+aioson tool:call . --name=run_tests --input='{"filter":"auth"}'
+
+# Ver detalhes de uma tool
+aioson tool:show . --name=run_tests
+
+# Remover uma tool
+aioson tool:unregister . --name=run_tests
+```
+
+### Exemplos práticos
+
+**Cenário:** agente `/qa` precisa checar se o servidor local está no ar antes de rodar testes. Em vez de escrever o curl toda vez:
+
+```bash
+aioson tool:register . \
+  --name=check_health \
+  --description="Verifica se o servidor local está respondendo" \
+  --type=shell \
+  --cmd='curl -sf http://localhost:3000/health && echo "OK" || echo "DOWN"'
+```
+
+Agora qualquer agente pode usar:
+```bash
+aioson tool:call . --name=check_health --input='{}'
+# OK
+```
+
+**Cenário:** agente `/dev` cria um script mais complexo para validar migrações:
+
+```bash
+# Agente cria o arquivo
+# .aioson/tools/validate-migrations.js
+
+# Depois registra
+aioson tool:register . \
+  --name=validate_migrations \
+  --description="Verifica se há migrações pendentes no banco" \
+  --type=script \
+  --path=.aioson/tools/validate-migrations.js \
+  --squad=backend \
+  --by=dev
+```
+
+**Segurança:** o subprocess recebe apenas `PATH`, `HOME`, `LANG`, `TERM`, `USER` e `TOOL_INPUT` (o JSON de input). Nenhuma variável de ambiente com credenciais é passada.
+
+**Listar tudo:**
+```bash
+aioson tool:list .
+# Tools registradas (3):
+#
+#   run_tests
+#     Roda os testes do projeto
+#     tipo: shell | registrada: 2026-03-30
+#
+#   check_health
+#     Verifica se o servidor local está respondendo
+#     tipo: shell | registrada: 2026-03-30
+#
+#   validate_migrations [squad:backend]
+#     Verifica se há migrações pendentes no banco
+#     tipo: script | registrada: 2026-03-30
+```
+
+---
+
+## 3. Ambient Intelligence Layer
+
+### O que é
+
+Um sistema que monitora o estado do projeto e avisa proativamente quando há itens que precisam de atenção — sem que você precise lembrar de rodar comandos.
+
+### Como funciona
+
+O AIOSON injeta verificações automáticas em pontos-chave do fluxo:
+
+- **Ao iniciar uma sessão** (`live:start`): exibe um digest se há itens pendentes
+- **Ao fechar uma sessão** (`live:close`): mostra o que foi acumulado durante o trabalho
+- **Sob demanda** (`aioson health`): relatório completo do estado do projeto
+
+### Comando health
+
+```bash
+aioson health .
+```
+
+Saída de exemplo:
+```
+AIOSON Health — itens que precisam de atenção:
+
+  ● 8 learning(s) prontos para evoluir
+    → aioson learning:evolve .
+  ○ Squad "frontend" inativo há 14 dia(s)
+  ✗ 1 tool(s) com handler inválido: validate_migrations
+    → aioson tool:unregister . --name=validate_migrations
+
+```
+
+### Digest automático no live:start
+
+Ao iniciar qualquer sessão com um agente:
+
+```bash
+aioson live:start . --agent=dev --tool=claude
+# Sessão iniciada: @dev | claude | session-dev-...
+#
+# AIOSON Health — itens pendentes:
+#   ● 5 learning(s) prontos para evoluir
+#   → aioson health . para detalhes
+```
+
+### Digest automático no live:close
+
+```bash
+aioson live:close . --agent=dev --summary="Implementou feature de auth"
+# Sessão encerrada: @dev | session-dev-... | .aioson/runtime/aios.sqlite
+#
+# AIOSON Health — itens após sessão:
+#   ● 3 learning(s) prontos para evoluir
+#   → aioson health . para detalhes e ações
+```
+
+Para suprimir o digest (modo CI ou scripts):
+```bash
+aioson live:start . --agent=dev --tool=claude --no-health
+aioson live:close . --agent=dev --no-health
+```
+
+### O que o health verifica
+
+| Item | Nível | Ação sugerida |
+|---|---|---|
+| Learnings com freq ≥ 2 prontos para evoluir | info | `aioson learning:evolve .` |
+| Squads sem atividade há 14+ dias | warn | Revisar contexto do squad |
+| Tools com handler de script inexistente | error | `aioson tool:unregister . --name=<nome>` |
+| Propostas de evolução pendentes em `.aioson/evolution/` | info | `aioson learning:apply . --file=...` |
+
+---
+
+## Fluxo completo integrado
+
+```
+Sessão de trabalho com /dev
+  │
+  ├─ live:start
+  │    └─ Health digest: "5 learnings prontos para evoluir"
+  │
+  ├─ Agente trabalha...
+  │    ├─ Você corrige erros → agente registra learnings
+  │    └─ Agente cria tools via tool:register
+  │
+  └─ live:close
+       ├─ Health digest: "8 learnings prontos para evoluir"
+       └─ Sugestão: aioson learning:evolve .
+            │
+            └─ learning:evolve --auto-apply
+                 ├─ Gate constitucional: ✓
+                 ├─ Gate de tamanho: ✓
+                 └─ Aplica → .aioson/context/project.context.md atualizado
+
+Próxima sessão: agente já sabe o que não fazer.
+```
+
+---
+
+## Referências
+
+- [Comandos CLI](./comandos-cli.md) — referência completa de todos os comandos
+- [Memória e Contexto](./memoria-contexto.md) — como o contexto do projeto é gerenciado
+- [Squads](./automacao-squads.md) — squads e seus learnings

package/docs/pt/monitor-de-contexto.md

@@ -0,0 +1,104 @@
+# Monitor de Contexto
+
+> Visualiza em tempo real o uso de janela de contexto por agente, com alertas automáticos de warning e critical.
+
+O `context:monitor` lê o arquivo `context-monitor.json` de uma squad e exibe barras de progresso ASCII com o percentual de contexto utilizado por cada agente. Útil para acompanhar sessões longas e antecipar quando um agente está próximo de compactar.
+
+---
+
+## Comando
+
+### `context:monitor`
+
+```bash
+aioson context:monitor [path] [opções]
+```
+
+**Opções:**
+
+| Opção | Descrição |
+|---|---|
+| `--squad=<slug>` | Squad a monitorar (obrigatório) |
+| `--agent=<id>` | Filtrar por agente específico (opcional) |
+| `--json` | Retorna dados estruturados em JSON |
+
+**Exemplos:**
+
+```bash
+# Monitorar todos os agentes de uma squad
+aioson context:monitor . --squad=meu-squad
+
+# Monitorar apenas um agente
+aioson context:monitor . --squad=meu-squad --agent=dev
+
+# Output JSON para dashboards ou scripts
+aioson context:monitor . --squad=meu-squad --json
+```
+
+---
+
+## Saída
+
+```
+  Context Monitor — meu-squad
+
+   ✓ dev              [████████░░░░░░░░░░░░] 42%  42000/100000
+   ⚠ qa               [█████████████████░░░] 85%  85000/100000
+   ! analyst          [████████████████████] 97%  97000/100000
+
+  Thresholds: warning=85%  critical=95%
+  Updated: 2026-03-30T14:23:00.000Z
+```
+
+---
+
+## Níveis de alerta
+
+| Ícone | Nível | Limiar | Situação |
+|---|---|---|---|
+| ✓ | normal | < 85% | Contexto confortável |
+| ⚠ | warning | 85–94% | Prepare recovery, evite carregar novos arquivos grandes |
+| ! | critical | 95–99% | Recovery deve ser gerado agora |
+| X | overflow | ≥ 100% | Compactação iminente ou já ocorreu |
+
+---
+
+## Quando usar
+
+- Antes de iniciar uma tarefa longa em um agente que já está com contexto parcialmente cheio
+- Para saber qual agente da squad está mais próximo de compactar
+- Para integrar alertas em scripts de monitoramento via `--json`
+
+---
+
+## JSON output
+
+Com `--json`, retorna objeto com os agentes e seus níveis:
+
+```json
+{
+  "ok": true,
+  "squadSlug": "meu-squad",
+  "agents": {
+    "dev": {
+      "totalUsed": 42000,
+      "windowSize": 100000,
+      "warningLevel": "normal"
+    },
+    "qa": {
+      "totalUsed": 85000,
+      "windowSize": 100000,
+      "warningLevel": "warning"
+    }
+  },
+  "updatedAt": "2026-03-30T14:23:00.000Z"
+}
+```
+
+---
+
+## Relação com recovery automático
+
+Em squads, o monitor detecta automaticamente quando o uso de contexto de um agente cai mais de 30% entre duas medições (sinal de compactação) e injeta um arquivo de recovery. Esse comportamento é coordenado por `checkAndInjectRecovery()` dentro do Squad Dashboard.
+
+Para sessões diretas (sem squad), use [`recovery:generate`](./recuperacao-de-sessao.md).