@jaimevalasek/aioson 1.3.0 → 1.5.1

package/docs/pt/profiler-system.md

@@ -1,6 +1,6 @@
 # Sistema Profiler — Guia Rápido
 
-> Pipeline oficial para pesquisa, enriquecimento e geração de Genoma 3.0 e Advisors no AIOSON.
+> Pipeline oficial para pesquisa, enriquecimento e geração de Genome 3.0 e Advisors no AIOSON.
 
 ---
 
@@ -16,7 +16,7 @@ O Sistema Profiler cria um perfil cognitivo inferido de pessoas públicas a part
 
 O pipeline gera dois outputs principais:
 
-- `Genoma 3.0`: conhecimento destilado + perfil cognitivo aplicável a agentes executores
+- `Genome 3.0`: conhecimento destilado + perfil cognitivo aplicável a agentes executores
 - `Advisor Agent`: conselheiro ativo que responde como a persona, com web search e memória
 
 ---
@@ -30,7 +30,7 @@ O fluxo oficial é sequencial:
 2. `@profiler-enricher`
    Consolida a pesquisa com materiais extras do usuário e produz `.aioson/profiler-reports/{person-slug}/enriched-profile.md`
 3. `@profiler-forge`
-   Transforma o perfil enriquecido em Genoma 3.0, Advisor Agent ou ambos
+   Transforma o perfil enriquecido em Genome 3.0, Advisor Agent ou ambos
 
 Fluxo resumido:
 
@@ -41,7 +41,7 @@ Pessoa alvo
   -> @profiler-enricher
   -> enriched-profile.md
   -> @profiler-forge
-  -> Genoma 3.0 / Advisor / ambos
+  -> Genome 3.0 / Advisor / ambos
 ```
 
 ---
@@ -61,20 +61,20 @@ Depois siga a sequência natural:
 @profiler-forge stefan-georgi
 ```
 
-### Opção 2: via `@genoma`
+### Opção 2: via `@genome`
 
 ```text
-@genoma
+@genome
 Tipo: persona
 Pessoa: Stefan Georgi
 Domínio: direct response copywriting
 ```
 
-Quando `type: persona` é detectado, o `@genoma` deve redirecionar para o pipeline profiler por padrão.
+Quando `type: persona` é detectado, o `@genome` deve redirecionar para o pipeline profiler por padrão.
 
 ### Opção 3: modo rápido
 
-Se o usuário pedir explicitamente um genoma persona rápido, leve ou `--quick`, o sistema pode gerar um resultado com baixa fidelidade usando apenas conhecimento inferido do LLM.
+Se o usuário pedir explicitamente um genome persona rápido, leve ou `--quick`, o sistema pode gerar um resultado com baixa fidelidade usando apenas conhecimento inferido do LLM.
 
 Nesses casos:
 
@@ -120,16 +120,16 @@ Todos os perfis psicométricos devem ser tratados como `INFERIDOS`.
 ### Outputs finais
 
 ```text
-.aioson/genomas/{person-slug}-{domain-slug}.md
-.aioson/genomas/{person-slug}-{domain-slug}.meta.json
+.aioson/genomes/{person-slug}-{domain-slug}.md
+.aioson/genomes/{person-slug}-{domain-slug}.meta.json
 .aioson/advisors/{person-slug}-advisor.md
 ```
 
 ---
 
-## Quando usar Genoma 3.0
+## Quando usar Genome 3.0
 
-Use Genoma 3.0 quando você quer enriquecer executores já existentes com a forma de pensar de uma pessoa.
+Use Genome 3.0 quando você quer enriquecer executores já existentes com a forma de pensar de uma pessoa.
 
 Exemplos:
 
@@ -137,7 +137,7 @@ Exemplos:
 - estrategista editorial operando com lentes mentais de um criador específico
 - time de liderança avaliando decisões com a filosofia operacional de uma referência
 
-Genoma é artefato passivo. Ele não executa sozinho.
+Genome é artefato passivo. Ele não executa sozinho.
 
 ---
 
@@ -196,10 +196,10 @@ Sinais de profiling fraco:
 
 ## Relação com o sistema atual
 
-O Profiler System é uma extensão do fluxo de genomas, não um substituto do Genoma 2.0.
+O Profiler System é uma extensão do fluxo de genomes, não um substituto do Genome 2.0.
 
-- Genoma 2.0 continua válido para `domain` e `function`
-- Genoma 3.0 entra quando existe `persona`
+- Genome 2.0 continua válido para `domain` e `function`
+- Genome 3.0 entra quando existe `persona`
 - Advisors convivem com squads como membros consultivos
 - relatórios intermediários viram a fonte de verdade para reprocessamento futuro
 
@@ -211,4 +211,4 @@ O Profiler System é uma extensão do fluxo de genomas, não um substituto do Ge
 - não omitir limitações do perfil
 - não pular o enriquecimento quando o objetivo for alta fidelidade
 - preservar os relatórios intermediários como trilha de auditoria
-- preferir `Genoma 3.0 + Advisor` quando o caso exigir execução e consultoria
+- preferir `Genome 3.0 + Advisor` quando o caso exigir execução e consultoria

package/docs/pt/runtime-observability.md

@@ -60,7 +60,11 @@ O gateway oficial de execucao deve:
 - `install` e `init` agora inicializam o runtime no projeto
 - `execution_events` foi adicionado ao schema do runtime
 - `workflow:next` sincroniza task/run/eventos reais no SQLite via gateway
-- `agent:prompt` classifica handoffs diretos de `@squad` e `@orchestrator` no runtime
+- `agent:prompt` classifica handoffs diretos de agentes oficiais e cria a task/run inicial no runtime
+- `runtime:session:start|log|finish|status` oferece uma camada direta para manter sessoes de agentes oficiais abertas e visiveis no dashboard durante o trabalho iterativo
+- `live:start|handoff|status|close` e `runtime:emit` formam o launcher/supervisor oficial para clientes externos, mantendo uma `session_key` viva, trocando `active_agent` por handoff e persistindo estado compacto no SQLite com historico verbose em `.aioson/runtime/live/{session_key}/`
+- `runtime:status --json` agora expoe projecoes prontas para dashboard e scripts: `activeLiveSessions`, `activeMicroTasks`, `recentLiveSessions`, `recentMicroTasks` e `recentHandoffs`
+- ativacao por linguagem natural direto no cliente (ex.: mencionar `@deyvin` no Codex) ainda nao passa pelo gateway e, portanto, nao garante registros em `tasks` e `agent_runs`
 - `parallel:init`, `parallel:assign` e `parallel:status` registram operacoes canonicas de orquestracao
 - templates novos nao instruem mais o agente a chamar `runtime-log` por shell snippet
 

package/docs/pt/skills.md

@@ -0,0 +1,175 @@
+# Sistema de Skills do AIOSON
+
+O AIOSON possui um sistema de skills que fornece convenções, padrões e referências específicas por framework, design system ou domínio técnico. As skills são carregadas sob demanda pelos agentes conforme o contexto do projeto.
+
+## Tipos de skills
+
+### Skills gerenciadas (`.aioson/skills/`)
+
+Distribuídas automaticamente pelo CLI durante `aioson init` ou `aioson update`. São **gitignored** — não versionadas com o projeto, pois o CLI as mantém atualizadas.
+
+Estrutura:
+
+```
+.aioson/skills/
+├── static/          ← convenções e padrões por framework
+│   ├── laravel-conventions.md
+│   ├── tall-stack-patterns.md
+│   ├── jetstream-setup.md
+│   ├── filament-patterns.md
+│   ├── flux-ui-components.md
+│   ├── django-patterns.md
+│   ├── fastapi-patterns.md
+│   ├── rails-conventions.md
+│   ├── nextjs-patterns.md
+│   ├── react-motion-patterns.md
+│   ├── node-express-patterns.md
+│   ├── node-typescript-patterns.md
+│   ├── web3-ethereum-patterns.md
+│   ├── web3-solana-patterns.md
+│   ├── web3-cardano-patterns.md
+│   └── web3-security-checklist.md
+├── dynamic/         ← referências consultadas via web quando necessário
+│   ├── laravel-docs.md
+│   ├── flux-ui-docs.md
+│   ├── npm-packages.md
+│   ├── ethereum-docs.md
+│   ├── solana-docs.md
+│   └── cardano-docs.md
+└── design/          ← design systems visuais
+    ├── cognitive-core-ui/
+    ├── interface-design/
+    └── premium-command-center-ui/
+```
+
+**Carregamento condicional:** O agente `@dev` carrega apenas as skills que correspondem ao valor de `framework` em `project.context.md`. Exemplo: se `framework=Laravel`, carrega `laravel-conventions.md` e opcionalmente `tall-stack-patterns.md` se o stack for TALL.
+
+### Skills instaladas (`.aioson/installed-skills/`)
+
+Skills de terceiros instaladas pelo usuário. São **versionadas com o projeto** (não gitignored), permitindo que toda a equipe use as mesmas skills.
+
+Cada skill instalada contém um `SKILL.md` com frontmatter YAML descrevendo quando usá-la.
+
+## Instalando skills
+
+### Via npm (pacotes públicos)
+
+```bash
+aioson skill:install @tech-leads-club/agent-skills --skill coupling-analysis
+```
+
+Isso:
+1. Baixa o pacote npm temporariamente
+2. Copia a skill para `.aioson/installed-skills/{nome}/`
+3. Distribui para ferramentas nativas (`.claude/skills/`, `.cursor/skills/`, `.windsurf/skills/`)
+4. Registra a skill na seção "Installed skills" do `AGENTS.md`
+
+### Via aioson.com (registry cloud)
+
+```bash
+aioson skill:install cloud:nome-da-skill
+```
+
+Requer autenticação com `aioson auth:login`. Busca skills publicadas no marketplace do aioson.com.
+
+### Via arquivo local
+
+```bash
+aioson skill:install ./caminho/para/skill/
+```
+
+Copia o diretório da skill diretamente para `.aioson/installed-skills/`.
+
+## Gerenciando skills
+
+### Listar skills instaladas
+
+```bash
+aioson skill:list
+```
+
+Mostra todas as skills em `.aioson/installed-skills/` com nome, descrição e fonte.
+
+### Remover uma skill
+
+```bash
+aioson skill:remove nome-da-skill
+```
+
+Remove de `.aioson/installed-skills/` e de todos os diretórios de ferramentas (`.claude/skills/`, `.cursor/skills/`, `.windsurf/skills/`).
+
+## Compatibilidade com ferramentas
+
+As skills instaladas são distribuídas automaticamente para as ferramentas de IA suportadas:
+
+| Ferramenta | Diretório | Como acessa |
+|------------|-----------|-------------|
+| Claude Code | `.claude/skills/` | Acesso direto por path |
+| Cursor | `.cursor/skills/` | Acesso direto por path |
+| Windsurf | `.windsurf/skills/` | Acesso direto por path |
+| Codex | `AGENTS.md` | Via referência `@slug` no arquivo AGENTS.md |
+| Gemini CLI | `.aioson/installed-skills/` | Acesso direto por path |
+
+### Nota sobre gitignore
+
+Mesmo que `.aioson/skills/` esteja no gitignore, todas as ferramentas (Claude Code, Gemini CLI, Codex) conseguem ler os arquivos via path direto no filesystem. O gitignore afeta apenas a descoberta automática do Codex via `@` — mas como as skills são referenciadas por path explícito nos agentes, isso não é um problema.
+
+## Mapeamento framework → skill
+
+O agente `@dev` usa o valor de `framework` do `project.context.md` para decidir quais skills carregar:
+
+| Framework | Skill estática | Referência dinâmica |
+|-----------|---------------|---------------------|
+| Laravel | `laravel-conventions.md` | `laravel-docs.md` |
+| Laravel + TALL | + `tall-stack-patterns.md` | |
+| Laravel + Jetstream | + `jetstream-setup.md` | |
+| Laravel + Filament | + `filament-patterns.md` | |
+| Laravel + Flux UI | + `flux-ui-components.md` | `flux-ui-docs.md` |
+| Django | `django-patterns.md` | |
+| FastAPI | `fastapi-patterns.md` | |
+| Rails | `rails-conventions.md` | |
+| Next.js | `nextjs-patterns.md` | `npm-packages.md` |
+| React | `react-motion-patterns.md` | `npm-packages.md` |
+| Express / Fastify | `node-express-patterns.md` | `npm-packages.md` |
+| Node.js + TypeScript | `node-typescript-patterns.md` | `npm-packages.md` |
+
+Para projetos Web3, skills adicionais são carregadas conforme `web3_networks`:
+
+| Rede | Skill estática | Referência dinâmica |
+|------|---------------|---------------------|
+| Ethereum | `web3-ethereum-patterns.md` | `ethereum-docs.md` |
+| Solana | `web3-solana-patterns.md` | `solana-docs.md` |
+| Cardano | `web3-cardano-patterns.md` | `cardano-docs.md` |
+
+## Skills de design
+
+Skills de design são especiais — apenas **uma** pode estar ativa por projeto, definida pelo campo `design_skill` em `project.context.md`. O agente `@dev` aplica exclusivamente o design system selecionado, sem misturar padrões de outros sistemas.
+
+Skills de design disponíveis:
+- `cognitive-core-ui` — UI com foco cognitivo
+- `interface-design` — Design de interfaces (dashboards, apps, ferramentas)
+- `premium-command-center-ui` — UI premium para command centers
+
+## Skills de squad
+
+Squads podem ter suas próprias skills em `.aioson/squads/{squad-slug}/skills/`. Essas são carregadas automaticamente quando a tarefa pertence ao escopo do squad.
+
+## Criando skills
+
+Uma skill é um diretório com pelo menos um arquivo `SKILL.md` contendo:
+
+```markdown
+---
+name: nome-da-skill
+description: Descrição curta do que a skill faz
+triggers:
+  - quando usar esta skill
+  - outro cenário de uso
+---
+
+# Nome da Skill
+
+Conteúdo da skill com convenções, padrões, exemplos de código, etc.
+```
+
+O frontmatter `description` e `triggers` são usados pelos agentes para decidir se devem carregar a skill para a tarefa atual.

package/docs/pt/squad-dashboard.md

@@ -0,0 +1,373 @@
+# Squad Dashboard
+
+O Squad Dashboard é um painel web embutido no próprio CLI do aioson. Ele roda localmente no computador do desenvolvedor e permite acompanhar todos os squads de um projeto em tempo real — agentes, processos ativos, uso de contexto, tokens, logs de execução e métricas.
+
+Não requer instalação adicional. Vem incluso quando você instala o aioson.
+
+---
+
+## Pré-requisitos
+
+- aioson instalado globalmente (`npm install -g @jaimevalasek/aioson`)
+- Pelo menos um squad criado no projeto (`aioson squad:create`)
+- Node.js ≥ 18 (já exigido pelo aioson)
+- Browser moderno (Chrome, Firefox, Safari, Edge)
+
+---
+
+## Iniciando
+
+Na raiz do projeto (onde fica a pasta `.aioson/`):
+
+```bash
+aioson squad:dashboard
+```
+
+Saída esperada:
+```
+Squad Dashboard rodando em http://localhost:4180 (porta 4180)
+Pressione Ctrl+C para parar.
+```
+
+Abra `http://localhost:4180` no browser. Para encerrar, pressione `Ctrl+C` no terminal.
+
+---
+
+## Opções
+
+```bash
+aioson squad:dashboard [path] [--port=4180] [--squad=<slug>] [--locale=pt-BR]
+```
+
+| Opção | Padrão | Descrição |
+|-------|--------|-----------|
+| `path` | `.` (diretório atual) | Raiz do projeto aioson |
+| `--port` | `4180` | Porta HTTP do dashboard |
+| `--squad` | — | Abre diretamente na página de um squad específico |
+| `--locale` | `pt-BR` | Idioma da interface |
+
+---
+
+## Exemplos
+
+### Iniciar na raiz do projeto atual
+```bash
+cd ~/meus-projetos/clinica-odonto
+aioson squad:dashboard
+```
+
+### Iniciar em outra porta
+```bash
+aioson squad:dashboard --port=4200
+```
+
+### Apontar para projeto em outro diretório
+```bash
+aioson squad:dashboard /home/usuario/projetos/marketing-digital
+```
+
+### Abrir diretamente em um squad específico
+```bash
+aioson squad:dashboard --squad=marketing-odonto
+# → Redireciona automaticamente para http://localhost:4180/squad/marketing-odonto
+```
+
+### Múltiplos projetos ao mesmo tempo (portas diferentes)
+```bash
+# Terminal 1
+aioson squad:dashboard ~/projetos/clinica --port=4180
+
+# Terminal 2
+aioson squad:dashboard ~/projetos/ecommerce --port=4181
+```
+
+---
+
+## Navegando pelo Dashboard
+
+### Página inicial — Lista de squads
+
+Ao acessar `http://localhost:4180`, você vê todos os squads do projeto com:
+
+- Nome e modo do squad (`content`, `software`, `mixed`)
+- Número de executores (agentes)
+- Status atual
+- Link para entrar na página do squad
+
+Se nenhum squad aparecer, verifique se existe `.aioson/squads/*/squad.manifest.json` no projeto.
+
+---
+
+### Página do squad — Painéis
+
+Cada squad tem sua própria URL: `http://localhost:4180/squad/{slug}`
+
+Os painéis disponíveis variam conforme a configuração do squad:
+
+#### Painel: Overview
+
+Visão resumida do squad:
+- Total de itens de conteúdo produzidos
+- Número de sessões registradas
+- Learnings acumulados
+- Taxa de entrega
+- Plano de execução (se definido)
+- Informações de pipeline
+
+#### Painel: Agentes (Processos)
+
+Lista os agentes Claude/AI ativos no momento:
+
+| Coluna | O que mostra |
+|--------|-------------|
+| Agente | Slug do executor |
+| PID | ID do processo no sistema operacional |
+| Tempo | Duração da sessão atual (`HH:MM:SS`) |
+| Contexto | Porcentagem do context window usado |
+| URL | Link para abrir a sessão do AI (se disponível) |
+| Ação | Botão para encerrar o processo via SIGTERM |
+
+> Os dados de processos atualizam automaticamente a cada 5 segundos via SSE (Server-Sent Events).
+
+#### Painel: Contexto
+
+Monitor do context window de cada agente em execução:
+
+- **Gauge visual** mostrando % de uso do contexto
+- **Nível de alerta**:
+  - Verde: 0–84% → Normal
+  - Amarelo: 85–94% → Warning
+  - Vermelho: 95–99% → Critical
+  - Roxo: 100%+ → Overflow
+- Detecção automática de compact (queda > 30% indica que o contexto foi compactado)
+- Breakdown por categoria (system prompt, conversation history, tool outputs, etc.)
+
+#### Painel: Tokens
+
+Uso e custo estimado por agente:
+
+- Total de tokens consumidos na sessão
+- Custo estimado em USD (baseado em modelo Sonnet-class)
+- **Flag de desperdício**: aparece quando `tool_outputs > 60%` do total
+- Breakdown por categoria (input, output, tool_use_input, tool_outputs, cache_write, cache_read)
+
+#### Painel: Logs de Execução
+
+Histórico detalhado das execuções de tasks:
+
+- Entradas filtráveis por tipo:
+  - `tool_call` — chamadas de ferramentas com input/output
+  - `reasoning` — raciocínio do agente
+  - `milestone` — marcos importantes
+  - `error` — erros com stack trace (quando disponível)
+- Timeline ordenada por timestamp
+- Filtro por sessão
+
+#### Painel: Hunk Review
+
+Revisão de código em hunks (para squads de software):
+
+- Lista de hunks pendentes de revisão
+- Ações disponíveis: **Aprovar**, **Rejeitar** (com comentário obrigatório), **Comentar**
+- Progresso: `aprovados / rejeitados / pendentes / revisados`
+- Re-submit: hunks aprovados mantêm status; só rejeitados voltam para pendente
+
+#### Painel: Content
+
+Itens de conteúdo produzidos pelo squad (para squads de conteúdo):
+
+- Lista de outputs indexados
+- Tipo e layout de cada item
+- Agente responsável
+
+#### Painel: Learnings
+
+Aprendizados acumulados pelo squad:
+
+- Learnings ativos, stale e archived
+- Tipo: preference, process, domain, quality
+- Confiança: high, medium, low
+
+#### Painel: Métricas
+
+Métricas customizadas configuradas via `aioson squad:roi`:
+
+- Valor atual vs. baseline vs. target
+- Período
+- Barra de progresso visual
+- ROI calculado (quando configurado)
+
+#### Painel: Integrações
+
+Status dos MCPs configurados no squad:
+
+- Connectors ativos (WhatsApp, Telegram, Webhook, etc.)
+- Status: connected / unconfigured / error
+- Calls totais e falhas
+
+#### Painel: Recovery Context
+
+Contexto de recovery gerado para cada agente (injeção pós-compact):
+
+- Conteúdo do `recovery-context.md`
+- Estimativa de tokens
+- Quando foi gerado
+
+---
+
+## Casos de Uso por Tipo de Squad
+
+### Squad de Conteúdo (ex: Clínica Odontológica)
+
+```bash
+# A squad está gerando conteúdo para Instagram e blog
+aioson squad:dashboard --squad=marketing-odonto
+
+# Painéis mais relevantes:
+# → Content: ver posts gerados
+# → Agentes: ver compositor e estrategista rodando
+# → Learnings: preferências de tom e formato acumuladas
+```
+
+### Squad de Software (ex: Feature de Agendamento)
+
+```bash
+aioson squad:dashboard --squad=agendamento-v2
+
+# Painéis mais relevantes:
+# → Hunk Review: revisar código antes de merge
+# → Logs: acompanhar tool_calls do agente de código
+# → Contexto: monitorar se o agente está perto do limite
+```
+
+### Squad com Workers e Daemon
+
+```bash
+# Primeiro inicie o daemon (workers automáticos)
+aioson squad:daemon start --squad=clinica
+
+# Em outro terminal, levante o dashboard
+aioson squad:dashboard --squad=clinica
+
+# Painéis mais relevantes:
+# → Métricas: taxa de no-show, ROI
+# → Integrações: status do WhatsApp Business
+# → Agentes: ver processos em tempo real
+```
+
+---
+
+## Integração com outros comandos
+
+O dashboard lê dados gerados por outros comandos do aioson. Para que os painéis mostrem dados ricos:
+
+| Para ver no dashboard | Comando que gera os dados |
+|-----------------------|--------------------------|
+| Métricas e ROI | `aioson squad:roi metric --squad=X` |
+| Status de MCPs | `aioson squad:mcp configure --squad=X` |
+| Processos ativos | Agentes rodando que gravam em `.aioson/squads/{slug}/processes/` |
+| Context window | Agentes que gravam em `.aioson/squads/{slug}/context-monitor.json` |
+| Token usage | Agentes que gravam em `.aioson/squads/{slug}/token-usage.json` |
+| Learnings | `aioson squad:learning` e sessões registradas automaticamente |
+| Recovery context | `aioson squad:recovery --squad=X --agent=Y` |
+
+---
+
+## Requisitos de Dados no Projeto
+
+O dashboard funciona mesmo sem todos os dados. O que cada painel precisa:
+
+```
+.aioson/
+  squads/
+    {slug}/
+      squad.manifest.json          ← obrigatório (o squad aparece na lista)
+      context-monitor.json         ← painel Contexto
+      token-usage.json             ← painel Tokens
+      processes/
+        {agent}.json               ← painel Agentes
+      recovery-context.md          ← painel Recovery
+      attachments/                 ← painel Attachments
+  runtime/
+    aios.sqlite                    ← painéis Content, Learnings, Métricas, Integrações
+```
+
+Se o SQLite não existir, os painéis que dependem dele aparecem vazios mas o dashboard não quebra.
+
+---
+
+## Diferença entre Squad Dashboard e aioson-dashboard
+
+| | Squad Dashboard | aioson-dashboard |
+|---|---|---|
+| **O que é** | Servidor HTTP embutido no CLI | App Next.js installável (premium) |
+| **Como acessa** | `aioson squad:dashboard` | Instala e roda separado |
+| **Foco** | Squads do projeto em tempo real | Gestão geral — projetos, genomas, pipelines, cloud |
+| **Porta** | `localhost:4180` (configurável) | Definida pelo app |
+| **Requer instalação extra** | Não — vem com o aioson | Sim |
+| **Custo** | Gratuito | Premium |
+
+Quando ambos estão rodando, o aioson-dashboard exibe um botão **"Abrir Squad Dashboard"** na página de cada squad, abrindo diretamente a URL correta.
+
+---
+
+## Solução de Problemas
+
+### O dashboard não inicia — porta em uso
+
+```
+Porta 4180 ja esta em uso. Tente --port=<outra>
+```
+
+Use outra porta:
+```bash
+aioson squad:dashboard --port=4200
+```
+
+### Nenhum squad aparece na home
+
+Verifique se o manifest existe:
+```bash
+ls .aioson/squads/*/squad.manifest.json
+```
+
+Se não existir, crie o squad primeiro:
+```bash
+aioson squad:create . --squad=meu-squad
+```
+
+### Painéis aparecem vazios
+
+Normal para projetos novos ou squads sem dados de runtime. Os painéis populam conforme os agentes rodam e gravam dados.
+
+### Processo aparece mas não atualiza
+
+O painel de agentes usa SSE com intervalo de 5 segundos. Se parar de atualizar, recarregue a página.
+
+### Comando não encontrado após atualizar o aioson no projeto
+
+O binário global pode estar desatualizado:
+```bash
+npm update -g @jaimevalasek/aioson
+```
+
+---
+
+## Referência rápida
+
+```bash
+# Iniciar
+aioson squad:dashboard
+
+# Porta customizada
+aioson squad:dashboard --port=4200
+
+# Squad específico
+aioson squad:dashboard --squad=meu-squad
+
+# Projeto em outro diretório
+aioson squad:dashboard /path/do/projeto
+
+# Ver ajuda
+aioson squad:dashboard --help
+```