@jaimevalasek/aioson 1.7.2 → 1.9.0

package/docs/pt/4-agentes/deyvin.md

@@ -0,0 +1,99 @@
+# @deyvin — Pair programming e continuidade de sessão
+
+> **Para quem é:** quem quer retomar uma feature em curso ou trabalhar em parceria com a IA numa tarefa conhecida.
+> **Tempo de leitura:** 4 min.
+> **O que você vai sair sabendo:**
+> - Quando usar @deyvin em vez de @dev.
+> - Como ele recupera contexto de uma sessão anterior.
+
+## Para que serve
+
+Você estava implementando uma feature ontem. Fechou o editor. Hoje quer continuar. Mas você não quer re-explicar tudo para a IA — stack, o que foi feito, o que falta, por que tomou aquela decisão.
+
+É exatamente isso que o `@deyvin` resolve. Ele lê `dev-state.md` e os artefatos da feature ativa antes de tocar em qualquer código, e entra no meio da conversa como se nunca tivesse saído. É o agente de **continuidade** — não de greenfield.
+
+Também funciona como pair-programming clássico: você e ele trabalham juntos em pequenos passos validados, cada um confirmado antes do próximo.
+
+Alias `@pair` é equivalente — mesmo agente, nome alternativo.
+
+## Quando invocar
+
+- Retomar feature que estava em andamento (`dev-state.md` existe com status `in_progress`).
+- Corrigir ou polir uma fatia pequena já conhecida.
+- Debugar um problema específico junto.
+- Inspecionar código e entender o que está acontecendo antes de agir.
+- Fazer ajustes rápidos sem abrir um fluxo de planejamento completo.
+
+## Quando NÃO invocar
+
+- Feature nova, greenfield, ou que mistura produto + UX + implementação → `@product` primeiro.
+- Sessão de planejamento ampla → `@analyst` ou `@architect`.
+- Você não sabe o que fazer → `@neo`.
+- A feature precisa de testes sistemáticos completos → `@qa` ou `@tester`.
+
+## Diálogo típico
+
+```
+Você > @deyvin
+
+@deyvin > Lendo dev-state.md...
+          Feature ativa: checkout-stripe
+          Status: em andamento — 3/6 steps concluídos
+          Último checkpoint: rota POST /checkout implementada, retorna session_id
+          Próximo step: webhook handler para confirmação de pagamento
+
+          Continuo de onde paramos?
+Você > Sim, pode ir.
+
+@deyvin > Lendo .aioson/context/features/checkout-stripe/spec.md...
+          AC relevante para este step: "Stripe envia evento checkout.session.completed,
+          sistema confirma pedido e envia email de confirmação."
+
+          Vou criar src/webhooks/stripe.js. Antes: qual a lib de email configurada?
+Você > nodemailer com template em emails/order-confirmed.html
+
+@deyvin > Perfeito. Implementando...
+          [código criado]
+          Rodei smoke test manual. Funcionou. Atualizei dev-state.md (4/6).
+          Próximo: testar com payload real do Stripe. Quer continuar agora?
+```
+
+## Saídas em disco
+
+| Arquivo | O que atualiza |
+|---|---|
+| `.aioson/context/dev-state.md` | Status atualizado a cada checkpoint concluído |
+
+O código implementado vai onde a spec determina (seus `src/`, `app/`, etc.).
+
+## Como ele lê seu projeto
+
+1. `.aioson/context/dev-state.md` — estado da sessão anterior (step atual, feature, próximos passos).
+2. `.aioson/context/features/{slug}/spec.md` — ACs da feature ativa.
+3. `.aioson/context/project.context.md` — stack e classificação.
+4. `.aioson/docs/deyvin/continuity-recovery.md` — protocolo interno de recuperação de contexto.
+
+## Comandos CLI relacionados
+
+```bash
+# Ver estado atual da implementação
+cat .aioson/context/dev-state.md
+
+# Iniciar sessão rastreada (aparece no dashboard)
+npx @jaimevalasek/aioson live:start . --tool=claude --agent=deyvin --no-launch
+```
+
+## Handoff típico
+
+- **Vem de:** `@dev` (quando uma sessão fica incompleta) ou `@neo` (quando detecta `in_progress`).
+- **Vai para:** `@qa` (quando a implementação está completa) ou `@sheldon` (se um trecho precisa de revisão profunda).
+
+## Escopo — regra importante
+
+`@deyvin` é deliberadamente estreito. Se você pedir algo grande (novo módulo, redesign amplo, mistura de escopos), ele rejeita e aponta o agente certo. Não é limitação — é proteção contra implementar a coisa errada.
+
+## Próximo passo
+
+- Implementação nova → [Mapa do ecossistema](../1-entender/mapa-do-ecossistema.md)
+- Entender dev-state → [@dev](./dev.md) *(ficha em construção)*
+- Termos como "feature ativa" e "dossier" → [Glossário](../1-entender/glossario.md)

package/docs/pt/4-agentes/discover.md

@@ -0,0 +1,122 @@
+# @discover — Cache semântico do projeto
+
+> **Para quem é:** quem trabalha em codebase médio/grande e quer que os agentes "saibam" o sistema sem precisar varrer tudo toda vez.
+> **Tempo de leitura:** 4 min.
+> **O que você vai sair sabendo:**
+> - O que é o cache semântico e por que economiza contexto.
+> - Quando rodar @discover e quando re-rodar.
+
+## Para que serve
+
+Num projeto com 500+ arquivos, quando você invoca `@analyst` ou `@dev`, eles precisam entender o sistema antes de agir. Sem cache, eles varrem o codebase inteiro — consome janela de contexto, é lento, e pode perder coisas.
+
+O `@discover` resolve isso de vez: ele lê o projeto uma vez, extrai as informações semânticas relevantes (entidades, rotas, fluxos, dependências, estado atual), e salva tudo em `.aioson/context/bootstrap/`. Na próxima vez que qualquer agente precisar entender o sistema, ele lê o cache em vez de varrer tudo.
+
+É como ter um **mapa do território** que todos os agentes consultam. Você atualiza o mapa quando o território muda.
+
+## Quando invocar
+
+- Primeira vez rodando AIOSON num projeto existente com código.
+- Após mudanças estruturais significativas no codebase (novos módulos, refatoração grande).
+- Quando um agente se perde ou dá respostas imprecisas por falta de contexto.
+- `@neo` ou `@deyvin` sinalizam que o cache está desatualizado.
+
+## Quando NÃO invocar
+
+- Projeto novo/vazio — não há o que descobrir ainda.
+- Cache foi rodado há menos de uma semana e não houve mudanças estruturais.
+- Você quer só rodar `@setup` — o discover vem depois, é um passo separado.
+
+## Diálogo típico
+
+```
+Você > @discover
+
+@discover > Lendo project.context.md... Stack: Node.js + Express + Postgres.
+            Verificando bootstrap existente... nenhum encontrado.
+
+            Iniciando descoberta semântica:
+            - Lendo src/routes/      → 12 rotas detectadas
+            - Lendo src/models/      → 6 entidades: User, Order, OrderItem,
+                                        Product, Payment, Address
+            - Lendo src/services/    → 8 services identificados
+            - Lendo tests/           → 47 testes, cobertura em: auth, orders
+            - Lendo package.json     → dependências: stripe, nodemailer, knex
+
+            Extraindo relacionamentos:
+            Order → User (many-to-one)
+            Order → OrderItem (one-to-many)
+            OrderItem → Product (many-to-one)
+
+            Salvando cache:
+            .aioson/context/bootstrap/entities.md
+            .aioson/context/bootstrap/routes.md
+            .aioson/context/bootstrap/services.md
+            .aioson/context/bootstrap/dependencies.md
+            .aioson/context/bootstrap/test-coverage.md
+
+            Cache pronto. Próximo agente pode usar .aioson/context/bootstrap/
+            em vez de re-escanear o projeto.
+```
+
+## Saídas em disco
+
+`@discover` produz **dois outputs complementares**, com propósitos diferentes:
+
+- **`bootstrap/`** — cache **semântico**, organizado por *tipo de artefato* (entidades, rotas, services, dependências, testes). Pensado para o próximo agente ler em sequência sem re-escanear o projeto.
+- **`brains/discover/`** — nodes em formato **Zettelkasten**, com cross-references entre conceitos. Pensado para qualquer agente consultar pontualmente ("o que sei sobre `OrderItem`?") via `aioson brains:query`.
+
+| Arquivo | O que contém |
+|---|---|
+| `.aioson/context/bootstrap/entities.md` | Entidades, atributos e relacionamentos detectados |
+| `.aioson/context/bootstrap/routes.md` | Endpoints/rotas com método, path e responsabilidade |
+| `.aioson/context/bootstrap/services.md` | Services e suas funções principais |
+| `.aioson/context/bootstrap/dependencies.md` | Dependências externas e propósito |
+| `.aioson/context/bootstrap/test-coverage.md` | O que está coberto por testes |
+| `.aioson/brains/discover/` | Nodes Zettelkasten para consulta cruzada por outros agentes |
+
+## Como ele lê seu projeto
+
+Escaneia em ordem de prioridade:
+
+1. `project.context.md` — stack, framework, linguagem.
+2. `discovery.md` / `skeleton-system.md` — se `scan:project` foi rodado antes.
+3. Arquivos de rotas (por stack detectada).
+4. Models, schemas, entidades.
+5. PRDs e specs em `.aioson/context/`.
+6. `package.json`, `composer.json`, `.env.example`.
+7. Testes (para inferir comportamento esperado).
+8. Bootstrap anterior (modo refresh — detecta o que mudou).
+
+## Comandos CLI relacionados
+
+```bash
+# Escanear estrutura de pastas (complementar ao @discover)
+npx @jaimevalasek/aioson scan:project . --folder=src
+
+# Ver o cache gerado
+ls .aioson/context/bootstrap/
+cat .aioson/context/bootstrap/entities.md
+```
+
+## Handoff típico
+
+- **Vem de:** `@setup` (primeira vez) ou qualquer ponto quando o cache está stale.
+- **Vai para:** `@analyst`, `@dev`, `@deyvin` — qualquer agente que precise entender o sistema.
+
+## Diferença entre @discover e scan:project
+
+| | `scan:project` (CLI) | `@discover` (agente) |
+|---|---|---|
+| O que faz | Análise estrutural estática | Extração semântica rica |
+| Saída | `discovery.md`, `skeleton-system.md` | `bootstrap/*.md`, `brains/` |
+| Quando rodar | Como preparação rápida | Para cache profundo e relacional |
+| Frequência | Pode rodar sempre | Quando houver mudança estrutural |
+
+Os dois se complementam: `scan:project` primeiro, `@discover` depois, é o combo mais eficiente.
+
+## Próximo passo
+
+- Projeto existente sem cache → [Em projeto existente](../2-comecar/projeto-existente.md)
+- Ver o ecossistema completo → [Mapa do ecossistema](../1-entender/mapa-do-ecossistema.md)
+- Termos como "brains" e "bootstrap" → [Glossário](../1-entender/glossario.md)

package/docs/pt/4-agentes/discovery-design-doc.md

@@ -0,0 +1,91 @@
+# @discovery-design-doc — Discovery e design doc em uma sessão combinada
+
+> **Para quem é:** quem tem uma ideia ou request e quer clareza completa — problema, ambiguidades, próximos passos — antes de qualquer implementação.
+> **Tempo de leitura:** 3 min.
+> **O que você vai sair sabendo:**
+> - Quando usar este agente vs usar `@analyst` e `@architect` separados
+> - O que o design doc entrega e como ele guia os próximos agentes
+
+---
+
+## Para que serve
+
+Às vezes um request chega vago: um ticket, uma ideia de feature, uma anotação de reunião. Antes de abrir `@product` e percorrer o ciclo completo, você quer **normalizar o problema, identificar o que já está definido, e saber o que ainda está aberto** — tudo em uma sessão.
+
+O `@discovery-design-doc` faz exatamente isso: transforma um request bruto num design doc enxuto e num documento de readiness que diz ao próximo agente "aqui está o que você precisa, e aqui está o que ainda falta".
+
+É um atalho para quando o ciclo completo seria pesado demais — ou para quando você quer um checkpoint antes de decidir qual agente acionar.
+
+---
+
+## Quando invocar
+
+- Você tem um ticket, briefing ou ideia e quer transformar em documento estruturado rapidamente
+- Você quer saber o que está bem definido vs o que ainda é ambíguo antes de acionar `@product` ou `@dev`
+- Você está em modo exploratório e quer um checkpoint de clareza sem comprometer o workflow completo
+
+---
+
+## Quando NÃO invocar
+
+- A feature já tem spec e PRD definidos — acione diretamente `@dev` ou `@qa`
+- Você precisa de discovery profundo com mapeamento de domínio — use `@analyst` dentro do workflow SMALL/MEDIUM
+- Você quer um briefing pré-PRD com frameworks de framing — use `@briefing`
+
+---
+
+## Diálogo típico
+
+```
+Você > @discovery-design-doc
+       Quero adicionar modo offline ao app mobile para que usuários possam
+       ver conteúdos sem internet.
+
+@discovery-design-doc > Normalizando request...
+                        Problema: usuários perdem acesso ao conteúdo sem conexão
+                        Escopo: modo leitura offline (não criação)
+
+                        Ambiguidades identificadas:
+                        - Quanto conteúdo cabe offline? (sem limite definido)
+                        - Sincronização automática ou manual?
+                        - Conflitos de versão se offline e online divergirem?
+
+                        Já definido:
+                        - Stack: React Native + SQLite local disponível
+                        - Auth: token pode sobreviver offline (não expira em 24h)
+
+@discovery-design-doc > Design doc criado em: .aioson/context/design-doc.md
+                        Readiness: MÉDIO — 3 ambiguidades precisam de decisão.
+                        Recomendação: @product para fechar escopo antes de @dev.
+```
+
+---
+
+## Saídas em disco
+
+```
+.aioson/context/design-doc.md      ← design doc enxuto (vivo, atualizado por agentes futuros)
+.aioson/context/readiness.md       ← status de clareza + ambiguidades abertas
+```
+
+---
+
+## Como ele lê seu projeto
+
+- `.aioson/context/project.context.md`
+- Artefatos existentes: `discovery.md`, `architecture.md`, `prd.md`, `spec.md` (quando relevantes)
+- Input direto: briefing, ticket, screenshots, arquivos que você fornecer
+
+---
+
+## Handoff típico
+
+- **Vem de:** pedido direto com um request vago ou ticket
+- **Vai para:** o agente recomendado no `readiness.md` — tipicamente `@product` (para fechar escopo) ou `@dev` (quando readiness é ALTO)
+
+---
+
+## Próximo passo
+
+- Para framing pré-PRD com discovery frameworks: ficha `briefing.md` (em construção)
+- Para ciclo completo: [Primeiro projeto do zero](../2-comecar/primeiro-projeto.md)

package/docs/pt/4-agentes/genome.md

@@ -0,0 +1,115 @@
+# @genome — Criar DNA cognitivo de domínios, funções e personas
+
+> **Para quem é:** quem quer que seus agentes "pensem" de um jeito específico — como um expert de domínio, uma função de negócio, ou uma persona real.
+> **Tempo de leitura:** 4 min.
+> **O que você vai sair sabendo:**
+> - O que é um genome e para que ele serve
+> - Quando usar o pipeline completo (Profiler) vs geração rápida
+
+---
+
+## Para que serve
+
+Um agente padrão fala de forma genérica. Um agente com um genome fala com a voz e o raciocínio de um especialista específico.
+
+O `@genome` cria o **DNA cognitivo** de um domínio, função ou persona em formato estruturado: traços de personalidade (DISC, Enneagram, Big Five, MBTI, HEXACO-H), estilo de comunicação, heurísticas de decisão, e instruções de advisor. Esse genome pode ser vinculado a executores de squad para que eles raciocinem e comuniquem como aquele perfil.
+
+Tipos de genome:
+- `domain` — ex: "segurança cibernética", "direito trabalhista"
+- `function` — ex: "VP de Vendas", "Head de Produto"
+- `persona` — ex: baseado em uma pessoa real pública (usa o pipeline Profiler)
+- `hybrid` — combinação de dois ou mais dos anteriores
+
+---
+
+## Quando invocar
+
+- Você quer que um executor de squad tenha um estilo de raciocínio específico
+- Você quer criar um advisor personalizado para simular como um expert pensaria
+- Você tem um genome de persona e quer aplicá-lo a um squad existente
+
+---
+
+## Quando NÃO invocar
+
+- Você só quer criar um squad — o genome é opcional, não obrigatório
+- Você quer um genome de persona sem investigação — use `--quick` para geração rápida com disclaimer de baixa fidelidade
+- Você quer pesquisar uma pessoa real em profundidade — o `@genome` vai te redirecionar para `@profiler-researcher` automaticamente
+
+---
+
+## Diálogo típico
+
+```
+Você > @genome
+
+@genome > Que tipo de genome você quer criar?
+          [1] Domain (ex: segurança, direito)
+          [2] Function (ex: CFO, Head de Marketing)
+          [3] Persona (baseado em pessoa real — usa pipeline Profiler)
+          [4] Hybrid
+Você > 1
+
+@genome > Domínio?
+Você > segurança ofensiva (red team)
+
+@genome > Gerando genome...
+          Verificando aioson.com por genome existente... não encontrado.
+          Gerando genome "red-team-security":
+          - DISC: D-alto / C-alto (direto, sistemático)
+          - Enneagram: 5w6 (observador, analítico)
+          - Heurísticas: assume que qualquer superfície é vulnerável, prova antes de concluir
+          - Estilo: técnico, sem eufemismos, cita ferramentas e CVEs
+
+@genome > Genome salvo em .aioson/genomes/red-team-security.genome.json
+          Quer vincular a um squad ou executor agora?
+```
+
+---
+
+## Saídas em disco
+
+```
+.aioson/genomes/{slug}.genome.json   ← genome gerado
+.aioson/genomes/{slug}-advisor.md    ← advisor em formato de prompt (quando solicitado)
+```
+
+---
+
+## Como ele lê seu projeto
+
+- `.aioson/context/project.context.md` — idioma e contexto
+- `.aioson/profiler-reports/{slug}/enriched-profile.md` — se for persona e o pipeline já rodou
+
+---
+
+## Comandos CLI relacionados
+
+```bash
+# Verificar saúde de um genome (campos obrigatórios, versão)
+aioson genome:doctor <slug>
+
+# Publicar genome no aioson.com
+aioson system:publish --type=genome --slug=<slug>
+```
+
+---
+
+## Handoff típico
+
+- **Vem de:** `@squad` (para vincular a executores) ou pedido direto do usuário
+- **Vai para:** `@profiler-researcher` quando persona é detectada e pipeline completo é necessário
+
+---
+
+## Detalhes recentes
+
+- **Genome 4.0 (2026):** novos campos `anchor_prompt`, `relations`, `hexaco_h`, e `trait_interactions` — o genome passou a modelar como traços interagem entre si, não apenas listá-los isoladamente
+
+---
+
+## Próximo passo
+
+- Para personas baseadas em pessoas reais: [profiler-researcher.md](./profiler-researcher.md)
+- Para vincular genome a um squad: [squad.md](./squad.md)
+- Glossário: [genome](../1-entender/glossario.md#genome)

package/docs/pt/4-agentes/neo.md

@@ -0,0 +1,93 @@
+# @neo — Roteador: "o que faço agora?"
+
+> **Para quem é:** quem está perdido num projeto em curso ou retomando após pausa.
+> **Tempo de leitura:** 3 min.
+> **O que você vai sair sabendo:**
+> - Quando usar @neo e o que ele mostra.
+> - Como ele decide qual agente é o próximo.
+
+## Para que serve
+
+Você abre um projeto que ficou parado alguns dias. Qual o próximo passo? O que foi feito? Qual feature está em curso? Qual agente deve entrar agora?
+
+Essas perguntas têm resposta nos artefatos do projeto — mas encontrá-la manualmente consome tempo. O `@neo` faz isso por você: lê `project-pulse.md`, `dev-state.md`, as specs das features ativas, e devolve um diagnóstico em segundos, com o caminho claro.
+
+Ele não implementa, não produz artefatos. Só orienta e roteia.
+
+## Quando invocar
+
+- "Onde paramos?" — após qualquer pausa no projeto.
+- "Qual o próximo agente?" — quando você não lembra o fluxo.
+- "O projeto está bloqueado?" — para diagnosticar impedimentos.
+- Quer ver o estado geral antes de decidir o que fazer.
+- Quer um catálogo de todos os agentes disponíveis (modo ecosystem-inquiry).
+
+## Quando NÃO invocar
+
+- Você sabe exatamente qual agente precisa e está prontos os artefatos — vá direto.
+- Quer implementar continuidade — `@deyvin` é o caminho.
+- Quer ver o mapa estático de agentes — `1-entender/mapa-do-ecossistema.md` já faz isso.
+
+## Diálogo típico
+
+```
+Você > @neo
+
+@neo > Lendo project-pulse.md...
+       Projeto: loja-artesanal (SMALL, pt-BR)
+       Feature ativa: checkout-stripe (fase: @dev em andamento)
+       Último agente: @dev (ontem, 14h32)
+       dev-state.md: 3/6 steps concluídos, próximo: implementar webhook Stripe
+
+       Estado:
+       ✓ product — spec criada
+       ✓ analyst — domain map OK
+       ✓ architect — decisões registradas
+       → dev — EM ANDAMENTO (retomar com @deyvin)
+       · qa — pendente
+       · validator — pendente
+
+       Recomendação: @deyvin para retomar a implementação.
+       Alternativas: @sheldon (revisar spec antes), @pentester (audit antecipado).
+
+       O que prefere?
+```
+
+## Saídas em disco
+
+Nenhuma. `@neo` é somente leitura — ele não escreve artefatos.
+
+## Como ele lê seu projeto
+
+Nesta ordem:
+
+1. `.aioson/context/project-pulse.md` — estado global e última atividade.
+2. `.aioson/context/dev-state.md` — se @dev ou @deyvin tinham sessão ativa.
+3. `.aioson/context/project.context.md` — classificação e stack.
+4. `.aioson/context/features.md` e specs das features ativas.
+5. Arquivos de presença (`prd.md`, `discovery.md`, `architecture.md`) para inferir qual fase do workflow está completa.
+
+## Comandos CLI relacionados
+
+```bash
+# Ver próximo agente no workflow
+npx @jaimevalasek/aioson workflow:next .
+
+# Ver estado de memória recente (5 últimos eventos)
+npx @jaimevalasek/aioson memory:summary . --last=5
+```
+
+## Handoff típico
+
+- **Vem de:** qualquer ponto — @neo é válido em qualquer momento.
+- **Vai para:** o agente que ele recomendar.
+
+## Detalhes recentes
+
+Em Mai/2026 (commit `5fbbef3`), o @neo recebeu um catálogo completo do ecossistema de agentes e um novo **modo ecosystem-inquiry**: você pode perguntar "quais agentes de segurança existem?" ou "o que faz o @briefing?" e ele explica, sem precisar abrir arquivos.
+
+## Próximo passo
+
+- Ver o ecossistema completo → [Mapa do ecossistema](../1-entender/mapa-do-ecossistema.md)
+- Retomar implementação → [@deyvin](./deyvin.md)
+- Entender project-pulse → [@setup](./setup.md)

package/docs/pt/4-agentes/orache.md

@@ -0,0 +1,107 @@
+# @orache — Investigar um domínio antes de criar squad ou strategy
+
+> **Para quem é:** quem quer entender um domínio de verdade — não superficialmente — antes de criar agentes ou tomar decisões estratégicas.
+> **Tempo de leitura:** 4 min.
+> **O que você vai sair sabendo:**
+> - O que o orache investiga e em que profundidade
+> - Como o relatório alimenta o `@squad` e o `@product`
+
+---
+
+## Para que serve
+
+Criar um squad de "marketing de conteúdo" sem entender como profissionais de marketing de conteúdo **realmente** pensam produz executores genéricos. O `@orache` investiga um domínio em profundidade — frameworks reais que experts usam, vocabulário insider, anti-padrões comuns, benchmarks de qualidade, vozes de referência — e salva um relatório que o `@squad` e outros agentes usam como fundação.
+
+Você não é um motor de busca: você é um analista de domínio que usa busca como ferramenta.
+
+---
+
+## Quando invocar
+
+- Antes de criar um squad para um domínio novo ou pouco familiar
+- Quando `@squad` detecta que precisa de investigação antes de definir executores
+- Quando você quer entender um mercado ou território antes de tomar decisões de produto
+- Quando precisa de investigação parcial (só frameworks, ou só anti-padrões)
+
+---
+
+## Quando NÃO invocar
+
+- Você já conhece bem o domínio — crie o squad diretamente
+- Você precisa de pesquisa sobre uma pessoa específica — use o pipeline `@profiler-researcher`
+- Você quer pesquisa de mercado para produto — o `@product` e o `@analyst` cobrem o necessário no contexto de features
+
+---
+
+## Os 3 modos de investigação
+
+| Modo | Rodadas de busca | Quando usar |
+|---|---|---|
+| **Full (padrão)** | 3–7 | Domínio novo, squad que vai rodar muitas vezes |
+| **Targeted** | 2–3 | Domínio parcialmente conhecido, enriquecimento específico |
+| **Quick Scan** | 1–2 | Squad efêmero, prazo curto |
+
+---
+
+## As 7 dimensões investigadas
+
+1. **Frameworks** — modelos mentais que profissionais realmente usam
+2. **Anti-padrões** — erros comuns que insiders evitam
+3. **Benchmarks de qualidade** — o que "bom" significa neste domínio
+4. **Vozes de referência** — quem o domínio cita como autoridade
+5. **Vocabulário** — termos insider vs termos genéricos
+6. **Padrões estruturais** — como outputs são organizados neste campo
+7. **Lacunas de conhecimento** — o que ainda não está documentado
+
+---
+
+## Diálogo típico
+
+```
+Você > @orache nutrição esportiva para atletas amadores
+
+@orache > Iniciando investigação: nutrição esportiva (amadores).
+          Modo: Full (7 dimensões). Estimativa: 4–5 rodadas.
+
+@orache > Frameworks identificados:
+          - Periodização nutricional (CHO cycling)
+          - Janela anabólica (revisada: 2h, não 30min)
+          - ISSN guidelines para amadores
+          Anti-padrões:
+          - Suplementar sem baseline de dieta
+          - Replicar protocolo de atleta elite sem ajuste calórico
+          Vocabulário-chave: macros, CHO, RPE, DEA, periodização...
+
+@orache > Relatório completo salvo em:
+          .aioson/context/orache-report-nutricao-esportiva.md
+          Pronto para @squad usar como fundação.
+```
+
+---
+
+## Saídas em disco
+
+```
+.aioson/context/orache-report-{slug}.md    ← relatório completo das 7 dimensões
+```
+
+---
+
+## Como ele lê seu projeto
+
+- `.aioson/context/project.context.md` — idioma e contexto do projeto
+- Cache de pesquisas em `researchs/{slug}/summary.md` — se criado recentemente (< 7 dias), reutiliza em vez de rebuscar
+
+---
+
+## Handoff típico
+
+- **Vem de:** `@squad` (redirect automático) ou pedido direto do usuário
+- **Vai para:** `@squad` — o relatório alimenta a definição dos executores
+
+---
+
+## Próximo passo
+
+- Depois da investigação: [squad.md](./squad.md)
+- Para investigação de persona: [profiler-researcher.md](./profiler-researcher.md)