@jaimevalasek/aioson 1.3.0 → 1.5.1

package/docs/pt/comandos-cli.md

@@ -33,6 +33,7 @@
 |---|---|---|
 | `setup:context` | Cria ou atualiza `.aioson/context/project.context.md` | Logo após instalar o framework |
 | `context:validate` | Valida o `project.context.md` | Depois de editar o contexto manualmente |
+| `context:pack` | Monta um pacote mínimo de contexto para uma tarefa específica | Quando você quer enviar para a IA só a memória relevante |
 | `locale:apply` | Reaplica um pack de idioma nos agentes gerenciados pelo AIOSON | Quando quer trocar o idioma em que os agentes do framework operam no projeto |
 | `locale:diff` | Compara um agente com o pack de idioma esperado | Quando quer detectar drift de tradução |
 | `i18n:add` | Gera o scaffold de um novo locale do próprio AIOSON | Quando vai adicionar outro idioma oficial ao CLI do framework |
@@ -76,18 +77,36 @@
 | `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 |
 
-### Genomas e squads
+### Web nativa
 
 | Comando | O que faz | Quando usar |
 |---|---|---|
-| `genome:doctor` | Valida um arquivo de genoma | Quando quer checar integridade de um genoma |
-| `genome:migrate` | Migra genomas para o formato novo | Quando está atualizando genomas legados |
+| `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 |
+|---|---|---|
+| `genome:doctor` | Valida um arquivo de genome | Quando quer checar integridade de um genome |
+| `genome:migrate` | Migra genomes para o formato novo | Quando está atualizando genomes legados |
 | `squad:status` | Mostra visão geral das squads instaladas | Quando quer saber o estado atual das squads |
 | `squad:doctor` | Diagnostica saúde operacional das squads | Quando suspeita de drift, staleness ou artefatos faltando |
-| `squad:repair-genomes` | Corrige referências de genomas em manifesto de squad | Quando um manifesto aponta bindings quebrados |
+| `squad:repair-genomes` | Corrige referências de genomes em manifesto de squad | Quando um manifesto aponta bindings quebrados |
 | `squad:validate` | Valida a estrutura e o manifesto de uma squad específica | Antes de exportar ou publicar |
 | `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 |
 
 ### Runtime
 
@@ -104,15 +123,35 @@
 | `runtime:fail` | Finaliza uma execução com falha | Quando a run falhou |
 | `runtime:status` | Mostra snapshot do runtime | Quando quer uma visão atual das runs |
 | `runtime:log` | Logger stateful de uma linha para agentes oficiais | Quando quer registrar eventos sem orquestrar vários comandos |
+| `runtime:session:start` | Abre ou reutiliza uma sessao direta de agente oficial | Quando quer manter uma sessao viva entre varias tarefas do `@deyvin` ou outro agente direto |
+| `runtime:session:log` | Adiciona um passo concluido na sessao direta ativa | Quando quer registrar cada tarefa concluida durante a sessao |
+| `runtime:session:finish` | Encerra a sessao direta ativa | Quando terminou a sessao ou vai fazer handoff |
+| `runtime:session:status` | Mostra o estado da sessao direta e os ultimos eventos | Quando quer saber se a sessao ainda esta aberta ou acompanhar com `--watch` |
+| `live:start` | Abre uma sessao viva rastreada para Codex, Claude, Gemini ou OpenCode | Quando quer iniciar o cliente externo a partir do AIOSON e manter status, agente ativo e logs no dashboard |
+| `runtime:emit` | Registra eventos compactos da sessao viva atual | Quando quer marcar tarefa concluida, milestone, block ou step de plano sem abrir uma sessao paralela |
+| `live:status` | Mostra o estado da sessao viva e do processo filho | Quando quer acompanhar `active_agent`, progresso do plano e se o cliente ainda esta vivo |
+| `live:handoff` | Transfere a mesma sessao viva para outro agente AIOSON | Quando o agente atual precisa passar a continuidade para `@product`, `@architect`, `@dev` ou outro agente |
+| `live:close` | Fecha a sessao viva e gera `summary.md` | Quando terminou a sessao externa e quer consolidar o historico compacto + verbose |
+| `runtime:backup` | Faz backup incremental do SQLite para S3 ou HTTP do cliente | Quando quer persistir dados de runtime na nuvem do cliente |
+| `runtime:restore` | Restaura dados de runtime a partir de um backup remoto | Quando quer recuperar dados em outra máquina ou após perda |
+| `runtime:prune` | Remove registros antigos do SQLite de runtime | Quando o banco está grande e quer liberar espaço |
+
+### Skills
+
+| Comando | O que faz | Quando usar |
+|---|---|---|
+| `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 |
 
 ### Cloud
 
 | Comando | O que faz | Quando usar |
 |---|---|---|
 | `cloud:import:squad` | Importa snapshot remoto de squad para o projeto | Quando vai instalar ou sincronizar uma squad publicada |
-| `cloud:import:genome` | Importa snapshot remoto de genoma | Quando quer trazer um genoma publicado |
+| `cloud:import:genome` | Importa snapshot remoto de genome | Quando quer trazer um genome publicado |
 | `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 genoma local | Quando quer versionar e compartilhar um genoma |
+| `cloud:publish:genome` | Publica snapshot de um genome local | Quando quer versionar e compartilhar um genome |
 
 ---
 
@@ -178,6 +217,33 @@ aioson context:validate .
 
 Use quando o projeto já está claro e você quer gerar o contexto sem passar pelo wizard interativo.
 
+### 6A. Montar um pacote mínimo de contexto
+
+```bash
+aioson context:pack .
+aioson context:pack . --agent=dev --goal="ajustar captions do YouTube" --module=src
+aioson context:pack . --agent=qa --goal="validar regressao do checkout" --module=app --max-files=10
+```
+
+Use quando você quer mandar para Codex, Claude Code, Gemini ou outro cliente só o contexto mais relevante para a tarefa atual.
+
+O comando escreve `.aioson/context/context-pack.md` e normalmente seleciona:
+
+- `project.context.md`
+- `memory-index.md`
+- `skeleton-system.md`
+- `discovery.md`
+- `spec-current.md`
+- `spec-history.md`
+- `architecture.md`
+- `module-<pasta>.md` e `scan-<pasta>.md` quando houver foco em um módulo
+
+Importante:
+
+- `context:pack` não substitui `discovery.md` nem `spec.md`
+- ele apenas monta um pacote mínimo para reduzir carga, custo e ruído no contexto
+- antes de montar o pack, o comando atualiza os derivados locais como `memory-index.md`, `spec-current.md`, `spec-history.md` e `module-<pasta>.md`
+
 ### 7. Trocar idioma do projeto
 
 ```bash
@@ -254,7 +320,7 @@ aioson agents . --lang=pt-BR
 aioson agent:prompt architect . --tool=codex
 ```
 
-Use `agents` para ver quem existe e `agent:prompt` quando o cliente de IA não entende `/setup`, `@dev` ou slash commands.
+Use `agents` para ver quem existe e `agent:prompt` quando o cliente de IA nao entende `/setup`, `@dev` ou slash commands, ou quando voce quer um handoff direto rastreado no runtime antes de continuar em outro cliente.
 
 ### 10. Validar agentes e pacote antes de release
 
@@ -282,6 +348,14 @@ O comando agora trabalha em duas etapas:
 1. O JavaScript faz uma análise local do projeto e gera `.aioson/context/scan-index.md`.
 2. Se você ativar `--with-llm`, a LLM usa esse índice compacto para produzir `discovery.md` e `skeleton-system.md`.
 
+Importante:
+
+- `scan:project` sozinho nao gera `discovery.md`
+- `scan:project` nunca gera `architecture.md`
+- se `discovery.md` e `skeleton-system.md` ja existirem e voce rodar com `--with-llm`, o scanner agora entra em modo de atualizacao por padrao: usa os arquivos atuais como memoria base, gera a nova versao consolidada e cria backup automatico em `.aioson/backups/` antes de sobrescrever
+- em projetos SMALL brownfield, o fluxo tipico depois do scan completo e `@analyst` -> `@architect` -> `@dev`
+- sem API LLM configurada, o fluxo local tambem e valido: `scan:project --folder=...` -> `@analyst` no seu Codex/Claude/Gemini -> `@architect` -> `@dev`
+
 O parâmetro `--folder` agora é obrigatório. Ele define quais pastas do projeto devem ganhar um mapa completo com pastas e arquivos. Você pode informar uma pasta ou várias separadas por vírgula.
 
 Artefatos locais gerados pelo scan:
@@ -290,6 +364,13 @@ Artefatos locais gerados pelo scan:
 - `scan-folders.md`: mapa somente de pastas do projeto
 - `scan-<pasta>.md`: mapa completo da pasta pedida em `--folder`, incluindo toda a estrutura de pastas e arquivos
 - `scan-aioson.md`: mapa útil do `.aioson/`, mostrando só artefatos gerados no uso do projeto
+- `memory-index.md`: índice de leitura com “leia isto quando precisar de X”
+- `module-<pasta>.md`: memória focada para cada pasta pedida em `--folder`
+
+Se existir `.aioson/context/spec.md`, o scanner também deriva:
+
+- `spec-current.md`: recorte curto do estado atual, trabalho em andamento e decisões abertas
+- `spec-history.md`: recorte histórico com implementações concluídas e decisões tomadas
 
 No caso de `.aioson/`, o scanner oculta o que é padrão do framework:
 
@@ -303,7 +384,7 @@ E mostra o que importa para operação do projeto, por exemplo:
 
 - páginas de contexto geradas
 - squads criadas
-- genomas criados
+- genomes criados
 - arquivos locais de MCP
 - outros artefatos específicos do uso real do cliente
 
@@ -312,6 +393,8 @@ Modos de resumo:
 - `--summary-mode=titles`: envia só títulos, tamanhos e estrutura. É o modo mais leve.
 - `--summary-mode=summaries`: envia títulos + resumos curtos. É o modo padrão.
 - `--summary-mode=raw`: além do índice, envia também o conteúdo bruto dos arquivos-chave. É o modo mais pesado.
+- `--context-mode=merge`: padrão para brownfield. Se já existir `discovery.md` ou `skeleton-system.md`, tenta atualizar sem apagar contexto útil.
+- `--context-mode=rewrite`: reescreve a memória a partir do scan atual. Use quando quiser regenerar do zero.
 - `--with-llm`: ativa a etapa opcional de enriquecimento por LLM.
 - `--llm-model=<name>`: sobrescreve o modelo configurado para esta execução.
 
@@ -321,6 +404,13 @@ Quando usar cada modo:
 - Se quiser mais contexto sem mandar arquivos brutos, use `summaries`.
 - Se quiser máxima riqueza de contexto e aceitar um prompt maior, use `raw`.
 
+Fluxos recomendados:
+
+- **Com API no aioson:** `scan:project --folder=src --with-llm --provider=...` -> `@analyst` -> `@architect` -> `@dev`
+- **Sem API no aioson:** `scan:project --folder=src` -> abrir seu AI CLI -> `@analyst` -> `@architect` -> `@dev`
+- **Com contexto mínimo para tarefa específica:** `scan:project --folder=src` -> `context:pack --agent=dev --goal="..." --module=src`
+- Se o seu cliente nao entender `@analyst`, gere um prompt pronto com `aioson agent:prompt analyst --tool=codex` ou troque `--tool` para o cliente correto
+
 Exemplo prático para reduzir carga no provider:
 
 ```bash
@@ -329,6 +419,18 @@ aioson scan:project . --folder=src --with-llm --provider=deepseek --summary-mode
 
 Nesse fluxo, providers como DeepSeek servem melhor como sintetizadores da arquitetura, relações e riscos do sistema, enquanto o trabalho pesado de mapear pastas solicitadas e filtrar o `.aioson/` fica no próprio CLI.
 
+Exemplo prático para atualizar memória existente sem perder contexto:
+
+```bash
+aioson scan:project . --folder=src,app --with-llm --provider=openai
+```
+
+Exemplo prático para reescrever do zero:
+
+```bash
+aioson scan:project . --folder=src,app --with-llm --provider=openai --context-mode=rewrite
+```
+
 ### 12. Avancar o workflow real entre agentes
 
 ```bash
@@ -403,11 +505,11 @@ Use este fluxo:
 
 Use isso quando quiser um painel local para acompanhar squads, runtime e entregas do projeto.
 
-### 16. Validar e migrar genomas
+### 16. Validar e migrar genomes
 
 ```bash
-aioson genome:doctor .aioson/genomas/fintech.md
-aioson genome:migrate .aioson/genomas --write
+aioson genome:doctor .aioson/genomes/fintech.md
+aioson genome:migrate .aioson/genomes --write
 ```
 
 Use `genome:doctor` para validar um arquivo individual e `genome:migrate` para atualizar um conjunto legado para o formato novo.
@@ -431,13 +533,58 @@ Use:
 - `squad:export` para empacotar a squad
 - `squad:pipeline` para inspecionar pipelines definidos dentro da squad
 
-### 18. Reparar bindings de genoma 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
 ```
 
-Use quando o manifesto da squad perdeu referências corretas para genomas ou ficou incompatível com a estrutura atual.
+Use quando o manifesto da squad perdeu referências corretas para genomes ou ficou incompatível com a estrutura atual.
 
 ### 19. Inicializar o runtime e indexar entregas
 
@@ -461,7 +608,39 @@ aioson runtime:task:finish . --task=task-001 --goal="Landing entregue"
 
 Use esse fluxo quando você quer rastreamento explícito de task, run, progresso e artefatos finais.
 
-### 21. Registrar eventos rápidos com `runtime:log`
+### 21. Manter uma sessao direta rastreada no terminal
+
+```bash
+aioson runtime:session:start . --agent=deyvin --title="Sessao de continuidade"
+aioson runtime:session:log . --agent=deyvin --message="Corrigi validacao do modal de estoque"
+aioson runtime:session:log . --agent=deyvin --message="Ajustei feedback visual de erro no formulario"
+aioson runtime:session:status . --agent=deyvin --watch=2
+aioson runtime:session:finish . --agent=deyvin --summary="Sessao encerrada com correcoes no estoque"
+```
+
+Use esse fluxo quando voce quer deixar uma sessao direta viva entre varios pedidos ao mesmo agente e ver no dashboard se ela ainda esta aberta, quais passos ja foram registrados e quando foi encerrada. Rode `runtime:session:status --watch=2` em outro terminal se quiser acompanhar ao vivo.
+
+### 22. Abrir uma sessao viva rastreada em cliente externo
+
+```bash
+aioson live:start . --tool=codex --agent=deyvin --plan=plan.md --no-launch
+aioson runtime:emit . --agent=deyvin --type=task_started --title="Corrigir modal de estoque"
+aioson runtime:emit . --agent=deyvin --type=plan_checkpoint --plan-step=RF-01 --summary="Launcher entregue"
+aioson runtime:emit . --agent=deyvin --type=task_completed --summary="Corrigi o modal de estoque" --refs="src/app.js,src/styles.css"
+aioson live:handoff . --agent=deyvin --to=product --reason="Escopo exige decisao de produto"
+aioson live:status . --agent=product --watch=2
+aioson live:close . --agent=product --summary="Sessao encerrada com handoff e resumo final"
+```
+
+Use esse fluxo quando voce quer iniciar Codex, Claude, Gemini ou OpenCode por fora do cliente, manter a mesma `session_key` viva entre varias tarefas e registrar no runtime:
+- agente ativo atual
+- marcos compactos no SQLite
+- `state.json`, `events.ndjson` e `summary.md` em `.aioson/runtime/live/{session_key}/`
+- handoffs entre agentes no mesmo envelope de sessao
+- progresso resumido de plano quando a sessao foi iniciada com `--plan`
+- projecoes prontas em `runtime:status --json` para `activeLiveSessions`, `recentMicroTasks` e `recentHandoffs`
+
+### 23. Registrar eventos rápidos com `runtime:log`
 
 ```bash
 aioson runtime:log . --agent=ux-ui --message="Comecei a revisar a landing"
@@ -470,7 +649,7 @@ aioson runtime:log . --agent=ux-ui --message="Entreguei a UI final" --finish --s
 
 Use quando quer um logger stateful de uma linha, sem precisar chamar manualmente `task:start`, `start`, `update` e `finish`.
 
-### 22. Fechar falhas de task ou run
+### 24. Fechar falhas de task ou run
 
 ```bash
 aioson runtime:task:fail . --task=task-001 --goal="Bloqueio em requisitos"
@@ -479,7 +658,7 @@ aioson runtime:fail . --run=run-001 --message="Dependencia externa indisponivel"
 
 Use quando a task ou a run precisa ser encerrada como falha, mantendo histórico no runtime.
 
-### 23. Publicar squads e genomas
+### 25. Publicar squads e genomes
 
 ```bash
 aioson cloud:publish:squad . --slug=marketing --resource-version=1.0.0 --base-url=https://aiosforge.com
@@ -488,7 +667,7 @@ aioson cloud:publish:genome . --slug=fintech --resource-version=1.0.0 --base-url
 
 Use quando você quer transformar artefatos locais em snapshots publicáveis e versionados.
 
-### 24. Importar squads e genomas publicados
+### 26. Importar squads e genomes publicados
 
 ```bash
 aioson cloud:import:squad . --url=https://aiosforge.com/snapshots/squads/marketing/1.0.0.json
@@ -497,6 +676,36 @@ aioson cloud:import:genome . --url=https://aiosforge.com/snapshots/genomes/finte
 
 Use quando vai instalar, atualizar ou sincronizar recursos publicados em outro projeto.
 
+### 27. Configurar e monitorar delivery de conteúdo
+
+```bash
+# Validar output strategy antes de rodar
+aioson squad:validate . --squad=youtube-creator
+
+# Verificar saúde (modo, webhooks, env vars)
+aioson squad:doctor . --squad=youtube-creator
+
+# Exportar configuração para outra squad ou documentar
+aioson output-strategy:export . --squad=youtube-creator
+
+# Copiar webhooks de uma squad para outra
+aioson output-strategy:import . --squad=nova-squad --from=youtube-creator
+
+# Ou importar de um arquivo
+aioson output-strategy:import . --squad=nova-squad --file=config-webhooks.json
+
+# Disparar delivery manual de conteúdo (quando autoPublish está desligado)
+aioson deliver . --squad=youtube-creator --content-key=episode-001
+```
+
+Use quando você quer:
+- **Validar** que webhooks estão configurados corretamente
+- **Copiar** a mesma estratégia de delivery entre múltiplas squads
+- **Testar** webhooks antes de rodar squads de verdade
+- **Reenviar** conteúdo que falhou na entrega automática
+
+Veja [Output Strategy e Delivery](../output-strategy-delivery.md) para guia completo sobre webhooks, payloads, env vars e troubleshooting.
+
 ---
 
 ## Atalhos úteis

package/docs/pt/deyvin.md

@@ -0,0 +1,115 @@
+# Deyvin
+
+> Guia focado no agente `@deyvin`, o companheiro tecnico de continuidade do AIOSON.
+
+## O que e
+
+`@deyvin` e o agente de continuidade e pair programming do AIOSON. Ele existe para ajudar quando voce quer retomar trabalho sem abrir um fluxo completo de produto, descoberta ou arquitetura.
+
+O foco dele nao e decidir a visao do produto nem desenhar a arquitetura inteira. O foco e continuar, corrigir, diagnosticar e implementar em passos pequenos, usando a memoria viva do projeto como ponto de partida.
+
+## Para que serve
+
+Use `@deyvin` quando precisar de apoio em situacoes como:
+
+- continuar uma sessao anterior sem perder contexto
+- entender o que foi feito recentemente
+- revisar tasks, runs e logs do runtime do projeto
+- olhar `spec.md`, `spec-current.md`, `spec-history.md` e o `context-pack.md` antes de tocar no Git
+- corrigir bugs pequenos e pontuais
+- implementar ajustes incrementais com validacao a cada passo
+- destravar um lote pequeno de trabalho antes de escalar para outro agente
+
+## Como ele auxilia
+
+O `@deyvin` ajuda de forma pratica:
+
+1. Lendo primeiro a memoria do projeto.
+2. Checando `rules` e docs relevantes.
+3. Consultando o runtime SQLite quando existir historico recente.
+4. Resumindo o estado atual para voce.
+5. Propondo o menor proximo passo util.
+6. Executando a correcao ou implementacao em lotes pequenos.
+7. Fazendo handoff quando perceber que o trabalho ficou grande demais.
+
+## Ordem de leitura
+
+Quando o `@deyvin` entra em acao, a ordem mental e esta:
+
+1. `project.context.md`
+2. `.aioson/rules/`
+3. `.aioson/docs/`
+4. `context-pack.md`, quando existir
+5. `memory-index.md`
+6. `spec-current.md` e `spec-history.md`
+7. `spec.md`
+8. `features.md` e artefatos da feature em andamento
+9. `skeleton-system.md`, `discovery.md` e `architecture.md`
+10. runtime SQLite
+11. Git apenas como fallback
+
+Essa ordem evita que o agente releia o projeto inteiro quando ja existe memoria suficiente.
+
+## O que ele nao faz
+
+`@deyvin` nao substitui:
+
+- `@product` para abrir feature nova ou consolidar PRD
+- `@discovery-design-doc` quando a demanda ainda esta vaga
+- `@analyst` quando faltam regras, entidades ou discovery brownfield
+- `@architect` quando a arquitetura precisa ser formalizada
+- `@ux-ui` quando a direcao visual precisa de definicao
+- `@dev` quando a implementacao deve seguir o fluxo tecnico completo
+- `@qa` quando a tarefa pede uma revisao formal de risco e teste
+
+## Alias compativel
+
+O nome oficial e `@deyvin`.
+O alias `@pair` continua aceito por compatibilidade.
+
+## Exemplos de uso
+
+```text
+@deyvin ve o que foi feito ontem e vamos continuar
+@deyvin revisa o runtime e me diga onde paramos
+@deyvin corrige esse bug pequeno comigo
+@deyvin leia as rules ativas e os docs relacionados antes de agir
+```
+
+## Sessao viva rastreada
+
+Quando voce entrar por `aioson live:start`, o `@deyvin` deve continuar trabalhando na mesma `session_key` e registrar apenas marcos compactos:
+
+```bash
+aioson live:start . --tool=codex --agent=deyvin --plan=plan.md --no-launch
+aioson runtime:emit . --agent=deyvin --type=task_started --title="Corrigir modal de estoque"
+aioson runtime:emit . --agent=deyvin --type=task_completed --summary="Corrigi o modal de estoque" --refs="src/app.js,src/styles.css"
+aioson live:handoff . --agent=deyvin --to=product --reason="Escopo exige decisao de produto"
+```
+
+Nesse modo, o `@deyvin` nao deve abrir uma sessao paralela de `runtime:session:*`. O agente ativo passa a ser trocado por `live:handoff`, o status fica disponivel em `live:status` e o fechamento final fica em `live:close`.
+
+
+## Quando escolher ele
+
+Escolha `@deyvin` quando:
+
+- voce quer velocidade sem perder contexto
+- o problema e pequeno ou ainda esta sendo entendido
+- voce quer trabalhar como se tivesse um colega sênior do lado
+- o objetivo principal e continuar, nao planejar do zero
+
+## Quando nao escolher ele
+
+Nao escolha `@deyvin` quando:
+
+- a feature ainda nao esta clara
+- existe uma descoberta maior para fazer
+- a arquitetura ainda esta indefinida
+- a conversa precisa virar PRD, discovery ou plano formal
+- o pedido abre um projeto novo ou greenfield para construir um sistema inteiro
+- o prompt mistura mais de um produto, muda a identidade do sistema no meio do texto ou junta varios modulos centrais de uma vez
+
+Nesses casos, o comportamento correto e handoff imediato. `@deyvin` nao deve "ir codando para ajudar" quando o escopo ainda precisa ser enquadrado.
+
+Nesses casos, o caminho certo e acionar o agente especializado antes.

package/docs/pt/genome-3.0-spec.md

@@ -1,17 +1,17 @@
-# Genoma 3.0 — Especificação de Formato
+# Genome 3.0 — Especificação de Formato
 
 > Versão: 3.0  
 > Status: Ativo  
-> Compatibilidade: retrocompatível com Genoma 2.0  
+> Compatibilidade: retrocompatível com Genome 2.0  
 > Data: 2026-03-13
 
 ---
 
 ## Visão geral
 
-O Genoma 3.0 estende o Genoma 2.0 com suporte a profiling de persona baseado em evidências. O objetivo é representar não só o que um domínio exige, mas como uma pessoa específica pensa sobre esse domínio.
+O Genome 3.0 estende o Genome 2.0 com suporte a profiling de persona baseado em evidências. O objetivo é representar não só o que um domínio exige, mas como uma pessoa específica pensa sobre esse domínio.
 
-O formato mantém as 10 seções canônicas do Genoma 2.0 e adiciona seções específicas para:
+O formato mantém as 10 seções canônicas do Genome 2.0 e adiciona seções específicas para:
 
 - perfil cognitivo
 - estilo de comunicação
@@ -20,7 +20,7 @@ O formato mantém as 10 seções canônicas do Genoma 2.0 e adiciona seções es
 
 ---
 
-## Tipos de genoma
+## Tipos de genome
 
 | Tipo | Versão mínima | Descrição |
 |------|---------------|-----------|
@@ -106,7 +106,7 @@ profiler_report: ".aioson/profiler-reports/stefan-georgi/enriched-profile.md"
 
 ## Seções canônicas
 
-### Obrigatórias em todo genoma
+### Obrigatórias em todo genome
 
 | Seção | Descrição |
 |-------|-----------|
@@ -200,7 +200,7 @@ Cobrir:
 - padrões típicos de erro
 - áreas de excesso de confiança
 - áreas de subconfiança
-- guidance compensatório para agentes que aplicarem o genoma
+- guidance compensatório para agentes que aplicarem o genome
 
 ### `## Conflict Resolution`
 
@@ -220,17 +220,17 @@ Cobrir:
 
 ### Leitura por sistema 2.0
 
-Um leitor de Genoma 2.0 deve conseguir:
+Um leitor de Genome 2.0 deve conseguir:
 
 - ignorar campos extras no frontmatter
 - ignorar seções extras
 - continuar lendo normalmente as 10 seções canônicas
 
-Isso torna o Genoma 3.0 retrocompatível por adição.
+Isso torna o Genome 3.0 retrocompatível por adição.
 
 ### Migração de 2.0 para 3.0
 
-Quando um genoma 2.0 recebe camada de persona:
+Quando um genome 2.0 recebe camada de persona:
 
 1. preservar o slug base quando fizer sentido
 2. elevar `version` para `3`
@@ -241,7 +241,7 @@ Quando um genoma 2.0 recebe camada de persona:
 
 ### Quick mode
 
-Quando um genoma persona for gerado sem profiler completo:
+Quando um genome persona for gerado sem profiler completo:
 
 - `evidence_mode: inferred`
 - `confidence: low`

package/docs/pt/inicio-rapido.md

@@ -40,6 +40,13 @@ O scanner cria estes arquivos localmente:
 - `.aioson/context/scan-folders.md`
 - `.aioson/context/scan-<pasta>.md`
 - `.aioson/context/scan-aioson.md`
+- `.aioson/context/memory-index.md`
+- `.aioson/context/module-<pasta>.md`
+
+Se existir `.aioson/context/spec.md`, ele tambem deriva:
+
+- `.aioson/context/spec-current.md`
+- `.aioson/context/spec-history.md`
 
 Se você também quiser gerar `discovery.md` e `skeleton-system.md`, ative a etapa opcional com LLM:
 
@@ -47,6 +54,28 @@ Se você também quiser gerar `discovery.md` e `skeleton-system.md`, ative a eta
 npx @jaimevalasek/aioson scan:project . --folder=src --with-llm --provider=openai
 ```
 
+Se `discovery.md` e `skeleton-system.md` ja existirem, o comportamento padrao agora e `merge`, com backup automatico em `.aioson/backups/`. Para regenerar do zero:
+
+```bash
+npx @jaimevalasek/aioson scan:project . --folder=src --with-llm --provider=openai --context-mode=rewrite
+```
+
+Se você nao usa API LLM no `aioson`, o caminho manual tambem funciona:
+
+1. Rode `scan:project . --folder=src`
+2. Opcional: rode `context:pack . --agent=analyst --goal="consolidar discovery brownfield" --module=src`
+3. Abra seu Codex, Claude Code, Gemini CLI ou cliente equivalente
+4. Execute `@analyst`
+5. O `@analyst` usa os arquivos de scan para gerar `discovery.md`
+
+Quando voce quiser montar um pacote minimo de contexto para uma tarefa especifica, use:
+
+```bash
+npx @jaimevalasek/aioson context:pack . --agent=dev --goal="ajustar captions do YouTube" --module=src
+```
+
+Esse comando gera `.aioson/context/context-pack.md` com os arquivos e trechos mais relevantes para a tarefa.
+
 ---
 
 ## 2. Configure o contexto do projeto
@@ -91,6 +120,8 @@ O agente `@setup` detecta o framework, faz as perguntas e gera o `project.contex
 
 > Cada CLI tem uma forma diferente de invocar agentes. Consulte o [Guia de CLIs de IA](./clientes-ai.md) para exemplos detalhados de Claude Code, Codex e Gemini.
 
+Se voce estiver entrando num projeto ja existente e quiser um companheiro tecnico para retomar uma sessao, diagnosticar algo pequeno ou implementar aos poucos, pode chamar `@deyvin` depois que o contexto minimo estiver pronto.
+
 ---
 
 ## Qual sequência usar?
@@ -98,8 +129,24 @@ O agente `@setup` detecta o framework, faz as perguntas e gera o `project.contex
 | 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
 
@@ -117,6 +164,20 @@ Exemplos:
 Esse passo de `@discovery-design-doc` é **recomendado quando agrega clareza**, não obrigatório.
 Se o pedido já estiver claro e pequeno, siga o fluxo normal.
 
+### Atalho de continuidade
+
+Quando o projeto ja tem memoria suficiente e voce quer retomar trabalho sem abrir uma feature nova:
+
+```text
+@deyvin -> pequeno lote -> validar -> seguir ou fazer handoff
+```
+
+Exemplos:
+- continuar o que foi feito ontem
+- revisar logs/tasks recentes do runtime
+- corrigir um bug pequeno junto
+- ajustar um fluxo ja conhecido sem abrir PRD novo
+
 **Não sabe o tamanho?** Responda 3 perguntas:
 1. Quantos tipos de usuário? (1=0pt, 2=1pt, 3+=2pt)
 2. Quantas integrações externas? (0=0pt, 1-2=1pt, 3+=2pt)