@jaimevalasek/aioson 1.5.1 → 1.6.0

package/docs/en/cli-reference.md

@@ -6,39 +6,50 @@ Complete reference for all `aioson` commands.
 
 ## init
 
-Create a new project directory and install AIOSON inside it.
+Create a new project directory and install AIOSON inside it. In interactive terminals, an **install wizard** runs first so you choose which AI tools and modes to install.
 
 ```bash
 aioson init <project-name>
 aioson init my-app --lang=pt-BR
 aioson init my-app --tool=codex
-aioson init my-app --lang=es --tool=gemini --json
+aioson init my-app --no-interactive
 ```
 
 **Options:**
 - `--lang=en|pt-BR|es|fr` — sets `conversation_language` in the generated context and applies the matching agent locale pack. Default: `en`.
 - `--tool=codex|claude|gemini|opencode` — configures the primary AI client. Affects which gateway file is used. Default: `codex`.
+- `--no-interactive` — skip the wizard and install all files (CI / automation).
 - `--json` — prints structured JSON result instead of human-readable output.
 
 **What it does:**
 1. Creates `<project-name>/` directory.
-2. Copies all template files into it.
-3. Applies the selected locale pack.
-4. Prints the recommended first command (`@setup`).
+2. Runs the install wizard (tools + mode selection).
+3. Copies only the files matching your profile.
+4. Shows the AIOSON reveal animation and install summary.
+5. Applies the selected locale pack.
 
 ---
 
 ## install
 
-Install AIOSON in an existing directory (or the current directory).
+Install AIOSON in an existing directory (or the current directory). Runs the same wizard as `init` when in a TTY.
 
 ```bash
 aioson install
 aioson install ./my-project
 aioson install --lang=pt-BR --tool=claude
+aioson install --reconfigure
+aioson install --no-interactive
 ```
 
-**Options:** same as `init`.
+**Options:**
+- `--lang=en|pt-BR|es|fr` — sets locale pack.
+- `--tool=codex|claude|gemini|opencode` — configures AI client.
+- `--reconfigure` — re-run the wizard even if a profile already exists (e.g. to add Gemini later).
+- `--no-interactive` — skip the wizard and install all files.
+- `--force` — overwrite existing files.
+- `--dry-run` — preview without writing.
+- `--json` — prints structured JSON result.
 
 **Use this when:**
 - The project already exists (legacy codebase, existing repo).
@@ -48,7 +59,7 @@ aioson install --lang=pt-BR --tool=claude
 
 ## update
 
-Update managed files to the latest template version. Preserves context files and anything not in the managed file list.
+Update managed files to the latest template version. Respects the saved install profile — only updates files that were originally installed.
 
 ```bash
 aioson update
@@ -60,7 +71,7 @@ aioson update --lang=pt-BR
 - `--lang=en|pt-BR|es|fr` — re-applies the locale pack after updating. If omitted, re-applies whatever locale is currently active.
 - `--json` — prints structured JSON result.
 
-**What it updates:** all files in the `MANAGED_FILES` list (agents, config, gateway files, skills). Does not touch `project.context.md`, `discovery.md`, `architecture.md`, or other context files you created.
+**What it updates:** all files in the `MANAGED_FILES` list that match your install profile (agents, config, gateway files, skills). Does not touch `project.context.md`, `discovery.md`, `architecture.md`, or other context files you created.
 
 ---
 

package/docs/pt/README.md

@@ -15,9 +15,16 @@ Bem-vindo à documentação em português do AIOSON — um framework leve de age
 | [Squad e Genome](./squad-genome.md) | Como criar squads modulares, diferenciar skill de genome, aplicar genomes e publicar entregáveis HTML |
 | [Agentes Customizados](./agentes-customizados.md) | Criar agentes personalizados com `squad:agent-create` — tipos, Voice DNA, infra operacional, maturity scoring |
 | [Skills](./skills.md) | Sistema de skills: tipos, instalação, mapeamento por framework e compatibilidade cross-tool |
+| [design-hybrid-forge](./design-hybrid-forge.md) | Fluxo canônico para criar skills híbridas de design com preset visual, locale automático e histórico |
 | [Automação de Squads](./automacao-squads.md) | Transformar processos de squad em scripts executáveis (Python/Node.js) que rodam sem LLM |
 | [Output Strategy e Delivery](./output-strategy-delivery.md) | Configurar webhooks, automatizar entrega de conteúdo, monitorar delivery e troubleshoot |
 | [Suporte Web3](./web3.md) | Guia para projetos dApp (Ethereum, Solana, Cardano) |
+| [Recuperação de Sessão](./recuperacao-de-sessao.md) | Gerar e restaurar contexto entre sessões do Claude Code após compactação |
+| [Monitor de Contexto](./monitor-de-contexto.md) | Visualizar uso de janela de contexto por agente com alertas de warning e critical |
+| [Busca de Contexto](./busca-de-contexto.md) | Indexar e buscar documentos do projeto via FTS5 com ranking por relevância e recência |
+| [Cache de Contexto](./cache-de-contexto.md) | Salvar snapshots de contexto e restaurar entre sessões |
+| [Sandbox de Execução](./sandbox.md) | Executar comandos com timeout, redação de secrets e summarização de output |
+| [Agent Sharding](./agent-sharding.md) | Carregar apenas as seções relevantes de instruções de agente para uma tarefa específica |
 
 ## Documentação em inglês
 

package/docs/pt/agent-sharding.md

@@ -0,0 +1,132 @@
+# Agent Sharding
+
+> Carrega apenas as seções relevantes de um arquivo de instruções de agente para uma tarefa específica, reduzindo consumo de tokens.
+
+Arquivos de instrução de agente podem conter muitas seções — role, guidelines, error handling, output format, checklist de revisão — mas para uma tarefa específica, apenas algumas são necessárias. O `agent:load` divide o arquivo em shards semânticos por heading, indexa via FTS5 e carrega apenas os shards mais relevantes para o objetivo informado.
+
+---
+
+## Comandos
+
+### `agent:shard:index`
+
+Indexa os arquivos de instruções de agentes para permitir carregamento inteligente.
+
+```bash
+aioson agent:shard:index [path] [opções]
+```
+
+**Opções:**
+
+| Opção | Descrição |
+|---|---|
+| `--agents-dir=<path>` | Diretório dos agentes (padrão: `.aioson/agents`) |
+| `--force` | Reindexar mesmo se já indexado |
+| `--json` | Retorna resultado em JSON |
+
+**Exemplos:**
+
+```bash
+# Indexar todos os agentes do projeto
+aioson agent:shard:index .
+
+# Forçar reindexação após atualizar arquivos de agente
+aioson agent:shard:index . --force
+
+# Diretório customizado de agentes
+aioson agent:shard:index . --agents-dir=.aioson/my-agents
+```
+
+---
+
+### `agent:load`
+
+Carrega os shards mais relevantes de um agente para um objetivo dado.
+
+```bash
+aioson agent:load <agent-id> [opções]
+```
+
+**Opções:**
+
+| Opção | Descrição |
+|---|---|
+| `--goal="..."` | Objetivo da tarefa (direciona a seleção de shards) |
+| `--agents-dir=<path>` | Diretório dos agentes (padrão: `.aioson/agents`) |
+| `--max-shards=<n>` | Máximo de shards a carregar (padrão: 3) |
+| `--max-tokens=<n>` | Orçamento de tokens (padrão: 2000) |
+| `--print` | Exibe o conteúdo completo dos shards selecionados |
+| `--json` | Retorna shards e tokens em JSON |
+
+**Exemplos:**
+
+```bash
+# Ver quais seções do agente dev são relevantes para a tarefa
+aioson agent:load dev --goal="implementar endpoint de pagamento com TDD"
+
+# Exibir o conteúdo para usar diretamente no prompt
+aioson agent:load dev --goal="refatorar autenticação" --print
+
+# Carregar mais shards se necessário
+aioson agent:load dev --goal="..." --max-shards=5 --max-tokens=3000
+
+# JSON para integração em scripts
+aioson agent:load dev --goal="..." --json
+```
+
+**Saída:**
+
+```
+  Agent: dev  (3/8 shards, 420 tokens)
+
+  ## Role  (85 tokens)
+  ## Implementation Guidelines  (180 tokens)
+  ## Error Handling  (155 tokens)
+```
+
+---
+
+## Como funciona
+
+**Divisão em shards:**
+O arquivo de instruções é dividido por headings H2 (`##`) e H3 (`###`). Cada shard é uma seção com seu conteúdo. O bloco antes do primeiro heading vira o shard `(preamble)`.
+
+**Indexação:**
+Os shards são salvos como arquivos individuais em `~/.aioson/shards/` e indexados via FTS5 (o mesmo motor do `context:search`).
+
+**Seleção:**
+1. O shard `(preamble)` e os shards de `Role` são sempre incluídos
+2. O FTS5 busca os shards mais relevantes para o `--goal`
+3. Shards são adicionados até preencher o orçamento de tokens
+4. Se ainda há espaço, shards restantes são adicionados em ordem
+
+**Orçamento:**
+O total de tokens dos shards selecionados fica dentro de `--max-tokens` (padrão 2000, estimado como chars/4).
+
+---
+
+## Exemplo de redução de contexto
+
+Para um agente com 9 seções e 228 tokens totais:
+
+```
+Carregando para "implementar com TDD e error handling":
+  Shards selecionados: 3 de 9
+  Tokens usados: 73 de 228
+
+  → Redução de 68% no consumo de tokens
+```
+
+---
+
+## Onde ficam os índices
+
+Os shards são indexados em `~/.aioson/shards/` — fora do repositório, não commitado. Use `--force` para atualizar após editar os arquivos de agente.
+
+---
+
+## Quando usar
+
+- Quando um arquivo de instrução de agente tem muitas seções e você quer enviar ao LLM apenas o que é necessário para a tarefa atual
+- Para reduzir tokens consumidos por instruções fixas do agente
+- Para agentes que têm seções muito diferentes (implementação, revisão, documentação, deploy) e você quer carregar apenas o contexto certo para cada tarefa

package/docs/pt/agentes.md

@@ -125,6 +125,7 @@ O `@product` detecta esses arquivos automaticamente e pergunta se deve usá-los
 - métricas de sucesso
 - perguntas em aberto
 - identidade visual inicial, quando houver sinal suficiente
+- `## Specify depth` (projetos SMALL e MEDIUM) — classificação aplicada, profundidade de spec escolhida e lista de ambiguidades que devem ser resolvidas antes que `@analyst` avance
 
 > Se o pedido mencionar explicitamente um command center premium, control tower, tri-rail shell ou estilo AIOS Dashboard, o `@product` deve registrar a skill `premium-command-center-ui` na seção de identidade visual do PRD.
 
@@ -223,6 +224,10 @@ Alias compativel:
 - Riscos identificados
 - Referências visuais (wireframes, links)
 
+Em **modo feature**, entrega adicionalmente:
+- `requirements-{slug}.md` — regras de negócio com IDs rastreáveis (`REQ-{slug}-N`) e acceptance criteria verificáveis por QA (`AC-{slug}-N`)
+- `spec-{slug}.md` — esqueleto de memória da feature, com `phase_gates` no frontmatter para que `@dev` e `@deyvin` saibam quais fases já foram aprovadas
+
 ---
 
 ## @discovery-design-doc
@@ -290,8 +295,9 @@ tests/
 **Entrega:** Arquivo `.aioson/context/architecture.md` com:
 - Estrutura de pastas (proporcional ao tamanho)
 - Stack definitiva
-- Decisões técnicas documentadas
+- Decisões técnicas documentadas com **rationale** — não só o que foi decidido, mas por que aquela escolha reduz risco de debug e manutenção futura
 - Padrões de código
+- **Gate B** — sinal explícito de aprovação ao final do arquivo (`@dev` só pode iniciar implementação após este gate)
 
 ---
 
@@ -627,7 +633,7 @@ Se o usuário pedir para pular o teste, o `@dev` resiste, explica, e só cede ap
 ```
 
 **Entrega:**
-- PRD enriquecido in-place (Modo A)
+- PRD enriquecido in-place com sinal de **spec-hardened** ao final — o campo `readiness` em `sheldon-enrichment-{slug}.md` indica se o PRD está pronto para downstream (`ready_for_downstream`) ou ainda tem itens bloqueantes (`needs_work`) (Modo A)
 - Relatório de status de todos os PRDs (Modo B)
 - Checklist de validação + decisão go/no-go para implementação (Modo C)
 

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/comandos-cli.md

@@ -143,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
 
@@ -153,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