@jaimevalasek/aioson 1.4.0 → 1.6.0

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

@@ -0,0 +1,129 @@
+# Busca de Contexto
+
+> Indexa e busca documentos do projeto via FTS5 (full-text search) com ranking automático por relevância e recência.
+
+O `context:search` constrói um índice SQLite FTS5 dos arquivos do projeto e permite buscas em linguagem natural que retornam os documentos mais relevantes — ordenados por BM25 e com reranking por data de modificação. Integra com o `context:pack` para montar pacotes de contexto mais precisos.
+
+---
+
+## Comandos
+
+### `context:search:index`
+
+Indexa os arquivos do diretório para permitir buscas futuras.
+
+```bash
+aioson context:search:index [path] [opções]
+```
+
+**Opções:**
+
+| Opção | Descrição |
+|---|---|
+| `--force` | Reindexar arquivos já indexados |
+| `--json` | Retorna resultado em JSON |
+
+**Exemplos:**
+
+```bash
+# Indexar o projeto atual
+aioson context:search:index .
+
+# Forçar reindexação completa
+aioson context:search:index . --force
+```
+
+---
+
+### `context:search`
+
+Busca documentos relevantes no índice.
+
+```bash
+aioson context:search <query> [opções]
+```
+
+**Opções:**
+
+| Opção | Descrição |
+|---|---|
+| `--limit=N` | Máximo de resultados (padrão: 10) |
+| `--cwd=<path>` | Diretório do projeto |
+| `--json` | Retorna resultados em JSON |
+
+**Exemplos:**
+
+```bash
+# Busca simples
+aioson context:search "autenticação JWT"
+
+# Limitar resultados
+aioson context:search "configuração de banco de dados" --limit=5
+
+# JSON para uso em scripts
+aioson context:search "endpoint de pagamento" --json
+```
+
+**Saída:**
+
+```
+  Search results for: "autenticação JWT"
+
+  1. Arquitetura de Segurança
+     .aioson/context/architecture.md
+     ...sistema usa [JWT] com expiração de 24h, [autenticação] via Bearer token...
+
+  2. Especificação de API
+     .aioson/context/spec.md
+     ...endpoints protegidos exigem header [Authorization: Bearer <token>]...
+```
+
+---
+
+## Como funciona
+
+**Indexação:**
+- Varre `.md`, `.txt` e `.json` recursivamente
+- Ignora `node_modules` e pastas ocultas
+- Salva em `~/.aioson/search/context-search.sqlite` com WAL mode
+- Arquivos já indexados são pulados (use `--force` para atualizar)
+
+**Ranking:**
+- BM25 built-in do FTS5 (penaliza spam, recompensa termos raros)
+- Bônus de recência: arquivos modificados há menos tempo têm score ligeiramente maior
+- Decay de 30 dias: após um mês, o bônus de recência se dissipa
+
+**Concorrência:**
+- WAL mode habilitado — múltiplas instâncias podem ler simultaneamente
+
+---
+
+## Invalidação automática
+
+Entradas com mais de 24 horas são consideradas obsoletas e removidas automaticamente na próxima indexação. Para forçar atualização antes disso, use `--force`.
+
+---
+
+## Quando usar
+
+- Antes de montar um `context:pack` para uma tarefa específica
+- Quando o projeto tem muitos arquivos e você quer encontrar qual documento tem o contexto certo
+- Em scripts que precisam descobrir automaticamente documentação relevante para uma tarefa
+
+---
+
+## JSON output
+
+```json
+{
+  "ok": true,
+  "results": [
+    {
+      "relPath": ".aioson/context/architecture.md",
+      "title": "Arquitetura de Segurança",
+      "snippet": "...sistema usa [JWT] com expiração...",
+      "score": 3.42
+    }
+  ]
+}
+```

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

@@ -0,0 +1,156 @@
+# Cache de Contexto
+
+> Salva snapshots de contexto em arquivos temporários locais e restaura quando necessário.
+
+O `context:cache` guarda o conteúdo de sessão em `~/.aioson/temp/` com limpeza automática após 24 horas. Útil para preservar o estado de uma sessão antes de trocar de agente, de branch ou de computador — e restaurar depois sem precisar regenerar tudo do zero.
+
+---
+
+## Comandos
+
+### `context:cache`
+
+Lista as sessões em cache, ordenadas da mais recente para a mais antiga.
+
+```bash
+aioson context:cache [opções]
+```
+
+**Opções:**
+
+| Opção | Descrição |
+|---|---|
+| `--json` | Retorna lista em JSON |
+
+**Exemplo:**
+
+```bash
+aioson context:cache
+```
+
+**Saída:**
+
+```
+  Cached Context Sessions
+
+  a3f8c2d1  2026-03-30T14:00  2KB — implementar autenticação JWT
+  b9e1f4a2  2026-03-30T10:30  8KB — refatorar módulo de pagamento
+  c7d2e5b3  2026-03-29T22:15  5KB — review de PRs pendentes
+```
+
+---
+
+### `context:cache:save`
+
+Salva um snapshot de contexto na sessão de cache.
+
+```bash
+aioson context:cache:save [path] [opções]
+```
+
+**Opções:**
+
+| Opção | Descrição |
+|---|---|
+| `--content="..."` | Conteúdo markdown a salvar (obrigatório) |
+| `--goal="..."` | Objetivo da sessão (para identificar) |
+| `--agent="..."` | Agente ativo |
+| `--json` | Retorna ID e caminho em JSON |
+
+**Exemplos:**
+
+```bash
+# Salvar conteúdo de contexto atual
+aioson context:cache:save . --content="$(cat .aioson/context/recovery-context.md)" --goal="implementar JWT"
+
+# Com agente
+aioson context:cache:save . --content="..." --goal="refatorar pagamento" --agent="dev"
+```
+
+---
+
+### `context:cache:restore`
+
+Restaura o conteúdo de uma sessão em cache.
+
+```bash
+aioson context:cache:restore [opções]
+```
+
+**Opções:**
+
+| Opção | Descrição |
+|---|---|
+| `--session=<id>` | ID da sessão a restaurar (obrigatório) |
+| `--query=<texto>` | Filtrar apenas linhas que contêm o texto |
+| `--json` | Retorna conteúdo em JSON |
+
+**Exemplos:**
+
+```bash
+# Restaurar sessão completa
+aioson context:cache:restore --session=a3f8c2d1
+
+# Restaurar apenas as linhas com "JWT"
+aioson context:cache:restore --session=a3f8c2d1 --query="JWT"
+```
+
+---
+
+### `context:cache:cleanup`
+
+Remove sessões expiradas.
+
+```bash
+aioson context:cache:cleanup [opções]
+```
+
+**Opções:**
+
+| Opção | Descrição |
+|---|---|
+| `--max-age=<horas>` | Remover sessões com mais de N horas (padrão: 24) |
+| `--json` | Retorna quantidade removida em JSON |
+
+**Exemplos:**
+
+```bash
+# Remover sessões com mais de 24h (padrão)
+aioson context:cache:cleanup
+
+# Manter apenas sessões das últimas 6 horas
+aioson context:cache:cleanup --max-age=6
+```
+
+---
+
+## Onde fica o cache
+
+As sessões são salvas em `~/.aioson/temp/` — fora do repositório, nunca commitadas. Cada sessão tem um diretório próprio com:
+
+```
+~/.aioson/temp/
+  a3f8c2d1/
+    context.md       # conteúdo salvo
+  sessions.json      # índice com metadados de todas as sessões
+```
+
+---
+
+## Restauração parcial com `--query`
+
+O `--query` filtra o conteúdo restaurado linha a linha, retornando apenas as linhas que contêm o texto buscado. Útil quando você quer extrair apenas a parte relevante de um contexto grande.
+
+```bash
+# Pegar só as linhas sobre banco de dados de uma sessão
+aioson context:cache:restore --session=a3f8c2d1 --query="database"
+```
+
+---
+
+## Quando usar
+
+- Antes de trocar de branch ou reiniciar o cliente de IA
+- Para preservar o estado de uma sessão longa antes de um `context:pack` novo
+- Para compartilhar contexto entre dois agentes diferentes sem reescrever tudo
+- Como fallback quando o `recovery:generate` não tem git disponível

package/docs/pt/cenarios.md

@@ -124,6 +124,22 @@ Objetivo: gerar o PRD base antes de mapear pacientes, médicos, agendamentos e r
 
 ### Passo 4: @product — PRD base
 
+**Atalho com documento de kickoff (opcional):**
+
+Se você já tiver uma ideia esboçada, crie um arquivo de entrada antes de ativar o `@product`:
+
+```bash
+# Crie plans/agendamentos.md com suas notas brutas:
+# - quero que pacientes agendem consultas online
+# - médico pode bloquear horários
+# - notificação por email na confirmação
+```
+
+Ao ativar `/product`, o agente detecta `plans/agendamentos.md` e pergunta:
+> "Encontrei `plans/agendamentos.md`. Quer que eu use como fonte para o PRD?"
+
+Se sim, ele sintetiza o conteúdo e gera o PRD formal. Você pode deletar o arquivo original depois.
+
 ```
 /product
 ```
@@ -260,7 +276,7 @@ tests/Feature/AppointmentTest.php
 - N+1: Eager loading em todos os índices (with('doctor.user', 'patient.user'))
 - Timezone: UTC no banco, conversão na camada de apresentação
 
-### Passo 6: @dev — Implementação
+### Passo 6: @dev — Implementação com TDD Gate
 
 ```
 /dev
@@ -269,8 +285,32 @@ Implemente a feature de agendamentos primeiro.
 Comece pela migration, model, action e controller.
 ```
 
-**O @dev implementa seguindo as convenções:**
+O `@dev` detecta o test runner (`pest.xml` encontrado → Pest PHP) e aplica o TDD Gate antes de implementar qualquer lógica de negócio:
 
+**1. Escreve o teste com falha (RED):**
+```php
+// tests/Feature/CreateAppointmentTest.php
+it('throws exception on doctor schedule conflict', function () {
+    $doctor = Doctor::factory()->create();
+    $slot = now()->addDay()->setHour(10)->setMinute(0);
+
+    Appointment::factory()->create([
+        'doctor_id' => $doctor->id,
+        'date'      => $slot,
+        'status'    => 'confirmed',
+    ]);
+
+    expect(fn () => (new CreateAppointmentAction)->execute([
+        'doctor_id'  => $doctor->id,
+        'patient_id' => Patient::factory()->create()->id,
+        'date'       => $slot,
+    ]))->toThrow(AppointmentConflictException::class);
+});
+```
+
+Roda o teste → **falha** (RED confirmado). Só então implementa:
+
+**2. Implementa o suficiente para passar (GREEN):**
 ```php
 // app/Actions/CreateAppointmentAction.php
 class CreateAppointmentAction
@@ -304,6 +344,8 @@ class CreateAppointmentAction
 }
 ```
 
+Roda o teste → **passa** (GREEN). Commit. Próximo passo.
+
 ### Passo 7: @qa — Testes
 
 ```
@@ -318,6 +360,8 @@ Revise a CreateAppointmentAction e escreva os testes para:
 
 **O @qa entrega** `tests/Feature/AppointmentTest.php` com todos os casos.
 
+> **Quando usar @tester em vez de @qa:** Se após o `@dev` a cobertura estiver em zero ou muito baixa, ative `/tester` em vez de `/qa`. O `@tester` começa por um inventário completo (`test-inventory.md`), mapeia os riscos, escolhe a estratégia e escreve testes em ordem de prioridade — Auth/Authorization > Business rules > Data integrity > UI. O `@qa` é um revisor pontual; o `@tester` é um engenheiro de testes que parte do zero.
+
 ---
 
 ## Cenário 3 — SaaS multi-tenant (MEDIUM)

package/docs/pt/comandos-cli.md

@@ -77,6 +77,13 @@
 | `qa:scan` | Faz crawl automático do app e procura riscos | Quando quer inspeção ampla de rotas |
 | `qa:report` | Reexibe ou exporta o último relatório | Quando quer consultar ou regenerar o relatório |
 
+### Web nativa
+
+| Comando | O que faz | Quando usar |
+|---|---|---|
+| `web:map` | Descobre URLs internas de um site por crawl simples | Quando quer mapear docs, páginas públicas ou áreas navegáveis sem serviço externo |
+| `web:scrape` | Extrai conteúdo principal de uma página em markdown, text, html ou links | Quando quer transformar HTML em contexto utilizável para agentes |
+
 ### Genomes e squads
 
 | Comando | O que faz | Quando usar |
@@ -90,6 +97,13 @@
 | `squad:export` | Exporta uma squad local para snapshot/entrega | Quando quer empacotar a squad |
 | `squad:pipeline` | Lista, inspeciona ou acompanha pipelines declarados na squad | Quando a squad define pipelines reutilizáveis |
 | `squad:agent-create` | Cria agente customizado em `.aioson/my-agents/` ou dentro de uma squad | Quando quer criar agente personalizado. Veja [Agentes Customizados](./agentes-customizados.md) |
+| `squad:dashboard` | Painel web local para monitorar squads em tempo real | Quando quer ver agentes rodando, contexto, tokens e métricas. Veja [Squad Dashboard](./squad-dashboard.md) |
+| `squad:worker` | Executa, lista e testa workers não-LLM de uma squad | Quando quer rodar workers determinísticos manualmente |
+| `squad:daemon` | Inicia/para/monitora daemon de workers automáticos | Quando quer execução 24/7 com cron e webhooks |
+| `squad:mcp` | Configura e testa conectores MCP (WhatsApp, Telegram, etc.) | Quando quer integrar canais reais à squad |
+| `squad:roi` | Define modelo de precificação e registra métricas de resultado | Quando quer calcular e reportar ROI da squad |
+| `squad:processes` | Lista e encerra processos ativos de uma squad | Quando quer inspecionar ou parar agentes sem usar o dashboard |
+| `squad:recovery` | Gera contexto de recovery para reinjecting após compact | Quando um agente perdeu contexto após compactação |
 | `output-strategy:export` | Exporta a estratégia de output (webhooks, delivery) de uma squad | Quando quer copiar configuração para outra squad ou documentar |
 | `output-strategy:import` | Importa estratégia de output de um arquivo ou outra squad | Quando quer replicar webhooks/delivery entre squads |
 | `deliver` | Dispara delivery manual de conteúdo para webhooks configurados | Quando quer reenviar conteúdo ou testar webhooks |
@@ -129,6 +143,7 @@
 | `skill:install` | Instala skill de terceiros via npm, cloud ou path local | Quando quer adicionar capacidade ao projeto. Veja [Skills](./skills.md) |
 | `skill:list` | Lista skills instaladas em `.aioson/installed-skills/` | Quando quer saber quais skills estão ativas |
 | `skill:remove` | Remove skill instalada e limpa diretórios de ferramentas | Quando uma skill não é mais necessária |
+| `design-hybrid:options` | Abre um seletor visual com setas + espaço para montar um preset temporário de variações de design | Quando quer alimentar a `design-hybrid-forge` com direções mais extravagantes, clássicas, animadas ou com CSS avançado. Usa o locale do projeto automaticamente e aceita `--locale` como override; com `--advanced` libera um 3º modificador. Veja [design-hybrid-forge](./design-hybrid-forge.md) |
 
 ### Cloud
 
@@ -139,6 +154,33 @@
 | `cloud:publish:squad` | Publica snapshot de uma squad local | Quando quer distribuir uma squad para outro projeto ou catálogo |
 | `cloud:publish:genome` | Publica snapshot de um genome local | Quando quer versionar e compartilhar um genome |
 
+### Contexto e recuperação de sessão
+
+| Comando | O que faz | Quando usar |
+|---|---|---|
+| `recovery:generate` | Gera `.aioson/context/recovery-context.md` com objetivo, agente, arquivos modificados e commits recentes | Antes de encerrar uma sessão longa ou ao detectar compactação iminente. Veja [Recuperação de Sessão](./recuperacao-de-sessao.md) |
+| `recovery:show` | Exibe o conteúdo do arquivo de recovery da sessão atual | Quando quer re-injetar o contexto no início de uma nova sessão |
+| `context:monitor` | Exibe barras ASCII com percentual de uso de contexto por agente de uma squad | Quando quer acompanhar em tempo real quão cheio está o contexto de cada agente. Veja [Monitor de Contexto](./monitor-de-contexto.md) |
+| `context:search:index` | Indexa arquivos `.md`, `.txt` e `.json` do projeto em banco FTS5 | Antes de usar `context:search` — normalmente uma vez, depois incrementalmente. Veja [Busca de Contexto](./busca-de-contexto.md) |
+| `context:search` | Busca documentos relevantes no índice por query em linguagem natural | Quando quer encontrar quais arquivos do projeto contêm contexto relevante para uma tarefa |
+| `context:cache` | Lista sessões de contexto em cache (mais recentes primeiro) | Quando quer saber quais snapshots de sessão estão disponíveis para restaurar. Veja [Cache de Contexto](./cache-de-contexto.md) |
+| `context:cache:save` | Salva um snapshot de conteúdo em `~/.aioson/temp/` | Quando quer preservar o estado de uma sessão antes de trocar de branch ou agente |
+| `context:cache:restore` | Restaura o conteúdo de uma sessão salva, com filtro opcional por query | Quando quer recuperar contexto de uma sessão anterior |
+| `context:cache:cleanup` | Remove sessões expiradas do cache (padrão: mais de 24h) | Quando quer liberar espaço ou forçar limpeza antes do prazo |
+
+### Execução segura
+
+| Comando | O que faz | Quando usar |
+|---|---|---|
+| `sandbox:exec` | Executa um comando shell com timeout, redação automática de secrets e summarização de output longo | Quando quer rodar scripts dentro de uma sessão de agente sem expor variáveis sensíveis do ambiente. Veja [Sandbox de Execução](./sandbox.md) |
+
+### Sharding de agente
+
+| Comando | O que faz | Quando usar |
+|---|---|---|
+| `agent:shard:index` | Divide arquivos de instrução de agente em shards por heading e indexa via FTS5 | Após adicionar ou atualizar arquivos de agente. Veja [Agent Sharding](./agent-sharding.md) |
+| `agent:load` | Carrega os shards mais relevantes de um agente para um objetivo dado, dentro de orçamento de tokens | Quando quer enviar ao LLM apenas as seções do agente necessárias para a tarefa atual |
+
 ---
 
 ## Exemplos e usos práticos
@@ -519,7 +561,52 @@ Use:
 - `squad:export` para empacotar a squad
 - `squad:pipeline` para inspecionar pipelines definidos dentro da squad
 
-### 18. Reparar bindings de genome em squads
+### 18. Monitorar squads com o Squad Dashboard
+
+```bash
+# Levantar o dashboard na raiz do projeto
+aioson squad:dashboard
+
+# Porta customizada
+aioson squad:dashboard --port=4200
+
+# Abrir direto em um squad específico
+aioson squad:dashboard --squad=marketing-odonto
+```
+
+Acesse `http://localhost:4180` no browser. O dashboard mostra todos os squads do projeto com agentes rodando, uso de contexto, tokens, logs de execução e métricas em tempo real.
+
+Para documentação completa: [Squad Dashboard](./squad-dashboard.md)
+
+### 19. Workers, Daemon e Integrações
+
+```bash
+# Listar workers de uma squad
+aioson squad:worker . --sub=list --squad=clinica
+
+# Executar um worker manualmente
+aioson squad:worker . --sub=run --squad=clinica --worker=confirma-consulta --input='{"phone":"5511999999999"}'
+
+# Iniciar daemon (workers automáticos 24/7)
+aioson squad:daemon . --sub=start --squad=clinica
+
+# Ver status do daemon
+aioson squad:daemon . --sub=status
+
+# Configurar integração WhatsApp
+aioson squad:mcp . --sub=configure --squad=clinica --mcp=whatsapp --connector=whatsapp-business
+
+# Testar conexão
+aioson squad:mcp . --sub=test --squad=clinica --mcp=whatsapp
+
+# Registrar métrica de ROI
+aioson squad:roi . --sub=metric --squad=clinica --key=no_show_rate --value=8 --unit=% --baseline=20 --target=5
+
+# Ver relatório de ROI
+aioson squad:roi . --sub=report --squad=clinica
+```
+
+### 20. Reparar bindings de genome em squads
 
 ```bash
 aioson squad:repair-genomes .aioson/squads/marketing/squad.manifest.json --write

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:
 
@@ -129,8 +180,24 @@ Se voce estiver entrando num projeto ja existente e quiser um companheiro tecnic
 | Tamanho do projeto | Sequência de agentes |
 |---|---|
 | **MICRO** — 0–1 ponto | `@setup → @dev` |
-| **SMALL** — 2–3 pontos | `@setup → @product → @analyst → @architect → @ux-ui → @dev → @qa` |
-| **MEDIUM** — 4–6 pontos | `@setup → @product → @analyst → @architect → @ux-ui → @pm → @orchestrator → @dev → @qa` |
+| **SMALL** — 2–3 pontos | `@setup → @product → [@sheldon] → @analyst → @architect → @dev → @qa → [@tester]` |
+| **MEDIUM** — 4–6 pontos | `@setup → @product → [@sheldon] → @analyst → @architect → @ux-ui → @pm → @orchestrator → @dev → @qa → [@tester]` |
+
+`[@sheldon]` — opcional, recomendado para validar e enriquecer o PRD antes de codar.
+`[@tester]` — opcional, para cobertura sistemática quando o `@dev` implementou sem testes adequados.
+
+### Estratégia de documentos de kickoff
+
+Antes de ativar `@product`, você pode criar arquivos de entrada na raiz do projeto:
+
+```
+plans/minha-ideia.md     ← suas notas brutas, esboços, referências
+prds/visao-produto.md    ← rascunhos de requisitos, inspirações
+```
+
+O `@product` e o `@sheldon` detectam esses arquivos automaticamente e perguntam se devem usá-los como fonte para gerar os artefatos formais em `.aioson/context/`. Os arquivos originais nunca são modificados — você decide quando deletá-los.
+
+Esses arquivos de kickoff **não são versionados por padrão** (estão no `.gitignore`). Eles são documentos de trabalho do desenvolvedor, não artefatos do projeto.
 
 ### Atalho recomendado quando o escopo ainda está nebuloso