@jaimevalasek/aioson 1.7.2 → 1.8.0

package/docs/pt/comandos-cli.md

@@ -45,7 +45,10 @@
 | `agents` | Lista agentes registrados, paths, dependências e outputs | Quando quer entender o arsenal ativo |
 | `agent:prompt` | Gera o prompt pronto para ativar um agente em outro cliente de IA | Quando o cliente não suporta slash command |
 | `workflow:plan` | Sugere o fluxo de agentes adequado ao porte do projeto | Quando quer decidir a ordem de execução |
-| `workflow:next` | Avança o fluxo real, registra estado, aceita desvio e skip ate `@dev` | Quando quer handoff automatico entre agentes |
+| `workflow:next` | Avança o fluxo real, registra estado, aceita desvio e skip ate `@dev`. Agora com gates técnicos e `--auto-heal` | Quando quer handoff automatico entre agentes |
+| `workflow:heal` | Reativa um agente com contexto corretivo após falha de gate | Quando um estágio quebrou e você quer retry com o erro como contexto |
+| `workflow:harden` | Analisa erros recorrentes do workflow e aplica/preconiza fixes preventivos | Hardening autônomo da base de código |
+| `workflow:execute` | Monta e executa o plano de agentes baseado na classificação; aceita `--dry-run` e `--start-from` | Para orquestrar features sem o dashboard |
 | `test:agents` | Valida contratos e arquivos críticos dos agentes | Quando mexeu no sistema de agentes |
 | `test:smoke` | Roda um smoke test em workspace temporário | Quando quer validar o pacote de forma ampla |
 | `test:package` | Testa o pacote instalado a partir de uma origem local | Quando vai validar release ou empacotamento |
@@ -139,13 +142,14 @@
 | `agent:done` | Registra conclusão de sessão de agente; aceita `--verdict`, `--artifacts` (CSV de paths) e `--plan-step` | Ao final de cada sessão de agente — é o comando que fecha a run e popula artifacts + verdict no SQLite |
 | `runtime:prune` | Remove registros antigos do SQLite de runtime | Quando o banco está grande e quer liberar espaço |
 
-### Skills
+### Skills e otimização de contexto
 
 | 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 |
+| `compress:agents` | Comprime arquivos de instrução dos agentes para reduzir consumo de tokens por sessão. Modo estrutural (gratuito) ou semântico via LLM (`--llm`). Salva backup automático em `.original.md`. Aceita `--agent`, `--rules`, `--dry-run`, `--restore`. | Quando quer reduzir custo de API sem alterar nenhuma lógica. Veja [compress:agents](./compress-agents.md) |
 | `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
@@ -157,6 +161,36 @@
 | `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 |
 
+### Autenticação e Workspaces (Cloud)
+
+| Comando | O que faz | Quando usar |
+|---|---|---|
+| `auth:login` | Autentica o CLI na AIOSON Store via `--token` | Quando for interagir com recursos em nuvem, instalar pacotes privados ou publicar itens na Store |
+| `auth:logout` | Remove o token de autenticação local | Quando quiser desconectar o ambiente da conta atual |
+| `auth:status` | Verifica o estado da sua autenticação | Para confirmar se você está logado na AIOSON Store |
+| `workspace:init` | Inicializa um projeto local e o vincula a um workspace remoto `--name=<slug>` | Quando começar um projeto que terá persistência, tracking e controle sincronizados no cloud |
+| `workspace:status` | Exibe os detalhes e metadados do workspace conectado | Para verificar o id, nome e status de sincronização do projeto atual |
+| `workspace:open` | Abre o painel do workspace conectado no seu navegador web | Quando precisar ver configurações do workspace na interface do cloud |
+
+### AIOSON Store (Sistemas, Genomes, Squads e Skills)
+
+A nova versão da Store permite empacotar, distribuir e instalar não só agentes, mas sistemas completos (boilerplates), genomes estruturados e skills.
+
+| Comando | O que faz | Quando usar |
+|---|---|---|
+| `system:package` | Lê o `system.json` e empacota o projeto local em `.aioson/system-packages` | Quando quiser testar o empacotamento completo do seu sistema antes de submetê-lo |
+| `system:publish` | Empacota e publica seu sistema/boilerplate na AIOSON Store | Quando quiser distribuir uma base arquitetural inteira para que outros comecem projetos rapidamente |
+| `system:list` | Lista os sistemas disponíveis localmente ou na nuvem | Para descobrir boilerplates e sistemas base que podem ser instalados |
+| `system:install` | Baixa e inicializa um sistema completo a partir da Store | Para dar kickstart num projeto novo a partir de um `system` já configurado com squads e arquitetura |
+| `squad:list` | Lista squads instaladas localmente ou remotamente na Store `--remote` | Para descobrir e inspecionar quais squads estão ativas ou disponíveis na nuvem |
+| `squad:publish` | Publica uma squad local na AIOSON Store | Quando quiser compartilhar ou monetizar `--paid` uma squad montada |
+| `squad:install` | Baixa e instala uma squad da Store no projeto local | Para importar capacidades, agentes e workflows empacotados distribuídos na Store |
+| `squad:grant` | Concede licença de acesso a uma squad para um email de usuário | Quando você gerencia permissões manuais de suas squads privadas/pagas |
+| `genome:publish` | Publica um dos seus genomes na AIOSON Store | Quando criar um padrão de conhecimento valioso (ex: regras de negócio) e quiser distribuir |
+| `genome:install` / `install:store` | Baixa e vincula um genome remoto no seu projeto local | Quando precisar instalar pacotes de conhecimento remotos para uso dos seus agentes |
+| `genome:list` / `remove` | Lista ou desinstala genomes presentes no projeto | Para gerenciar os pacotes de conhecimento instalados na pasta `.aioson/genomes` |
+| `skill:publish` | Empacota e publica uma skill local na AIOSON Store | Quando criar uma ferramenta ou integração e quiser distribuí-la para a comunidade |
+
 ### Contexto e recuperação de sessão
 
 | Comando | O que faz | Quando usar |
@@ -164,7 +198,8 @@
 | `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:health` | Analisa `.aioson/context/`, estima tokens por arquivo, sinaliza arquivos pesados e specs de features já concluídas | Antes de iniciar qualquer sessão longa — dá visibilidade do custo de contexto |
-| `context:trim` | Detecta specs stale (feature `done`) e seções muito longas, arquiva com `--force` | Quando o contexto está crescendo ou há specs de features já entregues |
+| `feature:archive` | Move artefatos de uma feature `done` para `.aioson/context/done/{slug}/` e atualiza o manifest | Arquivamento retroativo de features já entregues ou verificação com `--dry-run` |
+| `context:trim` | *(legado — use `feature:archive`)* | — |
 | `context:monitor` | Exibe barras ASCII com uso de contexto por agente de uma squad; aceita `--budget` + `--tokens` para modo de budget de projeto | Quando quer acompanhar em tempo real o contexto de uma squad ou checar se está perto do limite. 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 |
@@ -185,10 +220,15 @@ Scripts determinísticos que movem verificações de estado, validação de arte
 | `detect:test-runner` | Detecta PHPUnit, Jest, Vitest, Pytest, RSpec, Forge e node:test via arquivos de config | Quando `@dev` ou `@tester` precisa saber como rodar os testes |
 | `pulse:update` | Atualiza `project-pulse.md` com agente, feature, gate e próximo passo | Ao final de cada sessão de agente |
 | `state:save` | Salva ponto de continuação em `dev-state.md` (fase, status, spec-version, histórico) | Durante `@dev` ao fim de cada fase ou antes de encerrar |
-| `feature:close` | Fecha feature com verdict PASS/FAIL: atualiza spec, features.md e project-pulse.md | Após QA sign-off |
+| `feature:close` | Fecha feature com verdict PASS/FAIL: atualiza spec, features.md, project-pulse.md e dispara archivamento automático | Após QA sign-off — chamado pelo `@qa` automaticamente |
+| `feature:archive` | Move artefatos de uma feature `done` para `.aioson/context/done/{slug}/` e atualiza o manifest | Chamado pelo `feature:close` automaticamente; também disponível para retroativo com `--dry-run` e `--restore` |
 | `gate:check` | Valida pré-requisitos e artefatos de um phase gate (A/B/C/D); retorna PASS ou BLOCKED | Antes de avançar para o próximo agente |
 | `artifact:validate` | Verifica a cadeia completa de artefatos de uma feature (PRD → spec → plano → conformance) | A qualquer momento para checar completude |
 | `workflow:execute` | Monta e executa o plano de agentes baseado na classificação; aceita `--dry-run` e `--start-from` | Para orquestrar features sem o dashboard |
+| `runner:run` | Executa uma tarefa ou worker diretamente pelo runner | Quando quer executar fora do loop principal de sessão |
+| `runner:queue` | Enfileira tarefas no runner com prioridade e agente designado | Para execução assíncrona ou batch de tarefas |
+| `runner:plan` | Gera plano de execução do runner a partir de uma feature | Antes de iniciar execução por fase |
+| `runner:daemon` | Inicia/para/monitora o daemon do runner para execução 24/7 | Para workers automáticos e execução contínua |
 | `runner:queue:from-plan` | Extrai fases `## Phase N:` do plano e enfileira no runner com prioridades | Antes de iniciar execução por fase com o runner |
 | `learning:auto-promote` | Promove aprendizados de alta frequência para arquivos de regra em `.aioson/rules/` | Após várias sessões — quando quer solidificar padrões em regras |
 
@@ -232,6 +272,13 @@ Três comandos de inteligência de sistema para otimizar tokens, gerar contexto
 | `brief:gen` | Lê uma fase do plano de implementação + `architecture.md` + `spec.md` e gera um brief 100% autocontido para um worker | Antes de entregar uma fase a um executor de squad — garante que o worker tem tudo que precisa sem buscar contexto adicional. Veja [Geração de Brief](#40-gerar-brief-de-worker-briefgen) |
 | `verify:gate` | Verificação de olhos frescos: compara spec vs artefato entregue sem histórico de conversa; emite `PASS`, `PASS_WITH_NOTES`, `FAIL_WITH_ISSUES` ou `BLOCKED` | Após cada entrega de fase — detecta bugs que o agente gerador não consegue ver por viés de contexto. Veja [Verify Gate](#41-verificar-entrega-verifygate) |
 
+### Git e committer
+
+| Comando | O que faz | Quando usar |
+|---|---|---|
+| `commit:prepare` | Coleta diff staged, roda `git:guard`, gera `commit-prep.json` com tipo, escopo e descrição candidata | Antes de ativar `@committer` — automatiza a preparação e aplica guardrails de segurança |
+| `git:guard` | Verifica stage proibido (`node_modules/`, secrets, build artifacts) e pode instalar pre-commit hook | Antes de qualquer commit; use `--install-hook` para proteção contínua |
+
 ---
 
 ## Exemplos e usos práticos
@@ -531,6 +578,37 @@ Regras:
 Alias compativel:
 - `agent:next`
 
+Flags novas de hardening:
+- `--auto-heal`: se um gate técnico falhar ao completar, reativa o agente automaticamente com o erro como contexto corretivo (máx 3 retries)
+- `--force`: ignora gates técnicos (uso com cautela)
+
+### 12a. Reativar um agente com auto-cura (healing)
+
+```bash
+# Reativa @dev com o último erro injetado no prompt
+aioson workflow:heal . --stage=dev
+
+# Reativa @qa após falha de teste
+aioson workflow:heal . --stage=qa
+```
+
+Use quando um estágio falhou em um gate técnico ou contrato e você quer dar ao agente uma segunda chance com o erro explícito no contexto.
+
+### 12b. Hardening autônomo do projeto
+
+```bash
+# Analisa erros recorrentes e aplica fixes preventivos
+aioson workflow:harden .
+
+# Apenas preview
+aioson workflow:harden . --dry-run
+```
+
+Use periodicamente para:
+- detectar padrões de erro nos logs do workflow
+- atualizar `.gitignore` e instalar pre-commit hooks automaticamente
+- criar stubs de helpers de teste quando faltam
+
 ### 13. Preparar orquestração paralela
 
 ```bash
@@ -811,27 +889,37 @@ Total context load:                    ~17,625 tokens
 
 ⚠  1 stale spec file(s) (features: done):
    → spec-auth.md (feature: auth is done)
-   Run: aioson context:trim . to archive them
+   Run: aioson feature:archive . --feature=auth to archive it
 ```
 
 Use **antes de começar uma sessão longa** — se `Total context load` estiver acima de 15.000 tokens, considere arquivar specs stale ou criar um contexto escopado.
 
-### 29. Arquivar specs de features já entregues
+### 29. Arquivar artefatos de features já entregues
+
+O arquivamento é **automático** a partir do `feature:close --verdict=PASS` — o `@qa` dispara o comando e todos os artefatos da feature (`prd-`, `spec-`, `requirements-`, `sheldon-enrichment-`, etc.) são movidos para `.aioson/context/done/{slug}/` sem intervenção manual.
+
+Para ver o que seria movido antes de rodar:
 
 ```bash
-# Ver o que seria arquivado (sem mover nada)
-aioson context:trim . --dry-run
+aioson feature:archive . --feature=checkout --dry-run
+```
+
+Para retroativo em features que já estão como `done` em `features.md`:
 
-# Arquivar de verdade
-aioson context:trim . --force
+```bash
+aioson feature:archive . --feature=user-auth
 ```
 
-Os arquivos são movidos para `.aioson/context/archive/` — nunca deletados. Para restaurar:
+Para restaurar uma feature arquivada (e voltar a trabalhar nela):
 
 ```bash
-mv .aioson/context/archive/spec-auth.md .aioson/context/spec-auth.md
+aioson feature:archive . --feature=user-auth --restore
 ```
 
+O manifest em `.aioson/context/done/MANIFEST.md` registra todas as features arquivadas com data, contagem de arquivos e resumo da Vision — agentes históricos (`@cypher`, `@neo`, `@discover`, `@sheldon`) leem esse manifest em vez dos arquivos completos.
+
+> Veja a [documentação completa do feature:archive](./feature-archive.md) para detalhes de safety guards, saída JSON e impacto nos agentes.
+
 ### 30. Monitorar budget de tokens durante uma sessão
 
 ```bash
@@ -1569,7 +1657,7 @@ aioson feature:close . \
   --notes="Auth edge case ausente"
 ```
 
-Fecha a feature: atualiza spec (QA sign-off), features.md e project-pulse.md em uma chamada.
+Fecha a feature: atualiza spec (QA sign-off), features.md e project-pulse.md em uma chamada. Em `--verdict=PASS`, dispara `feature:archive` automaticamente — todos os artefatos da feature são movidos para `.aioson/context/done/{slug}/` e o manifest é atualizado sem intervenção manual.
 
 ### 51. Executar workflow completo
 
@@ -1622,6 +1710,65 @@ Cria arquivos em `.aioson/rules/` para aprendizados `process` e `quality` com fr
 
 ---
 
+### 54. Preparar commit com `commit:prepare`
+
+```bash
+# Preparar commit do estado atual (staged)
+aioson commit:prepare .
+```
+
+Saída esperada:
+
+```
+Commit Preparation
+──────────────────────────────────────────────────
+Staged files : 3
+Guard status : PASS
+
+Changes:
+  src/components/Button.tsx    (modified)
+  tests/button.test.tsx        (modified)
+  README.md                    (modified)
+
+commit-prep.json written to .aioson/context/commit-prep.json
+```
+
+O `@committer` lerá esse arquivo e gerará a mensagem semântica correta.
+
+Se nada estiver staged:
+
+```
+Guard status : BLOCKED — no staged files
+Nothing to commit. Stage files first with git add.
+```
+
+Se houver arquivos proibidos:
+
+```
+Guard status : BLOCKED — forbidden files detected
+  node_modules/.package-lock.json
+Remove forbidden files from stage before committing.
+```
+
+---
+
+### 55. Verificar stage com `git:guard`
+
+```bash
+# Verificação única
+aioson git:guard .
+
+# Instalar hook de pre-commit para verificação contínua
+aioson git:guard . --install-hook
+```
+
+Regras do guard:
+- Bloqueia stage vazio
+- Bloqueia arquivos em `node_modules/`, `dist/`, `.next/`, `*.db`, secrets
+- Pode instalar hook em `.git/hooks/pre-commit`
+
+---
+
 ## Atalhos úteis
 
 ```bash

package/docs/pt/compress-agents.md

@@ -0,0 +1,304 @@
+# compress:agents — Compressão de Agentes
+
+`aioson compress:agents` reduz o tamanho dos arquivos de instrução dos agentes (`.aioson/agents/`) e opcionalmente das regras (`.aioson/rules/`), diminuindo o consumo de tokens por sessão sem alterar nenhuma regra ou lógica.
+
+---
+
+## Por que comprimir
+
+Cada sessão de agente carrega os arquivos de instrução inteiros no contexto da IA. Arquivos maiores custam mais tokens — e os custos se multiplicam porque quase toda sessão carrega o mesmo conjunto de arquivos.
+
+A compressão elimina:
+- Seções explicativas que repetem o que as regras já dizem ("Por que isso importa")
+- Frases introdutórias vazias ("É importante notar que...", "Vale ressaltar que...")
+- Resumos finais que repetem o que foi escrito acima
+- Parágrafos que explicam o óbvio a partir do contexto
+
+O conteúdo técnico — tabelas, code blocks, comandos, paths, URLs, regras, constraints — permanece 100% intacto.
+
+---
+
+## Dois modos
+
+| Modo | Flag | Como funciona | Custo |
+|------|------|---------------|-------|
+| **Estrutural** | *(padrão, sem flag)* | Remove padrões conhecidos de baixo valor por regex | Gratuito |
+| **LLM** | `--llm` | Envia cada arquivo ao Claude para compressão semântica | Pago (API) |
+
+Use o modo estrutural no dia a dia. Use `--llm` quando quiser o máximo de redução possível — especialmente em agentes novos ou gerados por squads que tendem a ser mais verbosos.
+
+---
+
+## Instalação e pré-requisitos
+
+O comando está incluído no AIOSON a partir da versão **1.7.3**. Nenhuma dependência extra necessária para o modo estrutural.
+
+Para o modo `--llm`, a variável de ambiente `ANTHROPIC_API_KEY` precisa estar definida no seu shell com a chave da API Anthropic.
+
+---
+
+## Referência completa
+
+```
+aioson compress:agents [path] [opções]
+```
+
+`path` é opcional — omitir usa o diretório atual.
+
+### Opções
+
+| Flag | Tipo | Descrição |
+|------|------|-----------|
+| `--agent=<nome>` | string | Comprime apenas o(s) agente(s) especificado(s). Aceita lista separada por vírgula. |
+| `--rules` | boolean | Inclui `.aioson/rules/*.md` além dos agentes. |
+| `--dry-run` | boolean | Mostra o que seria comprimido sem alterar nenhum arquivo. |
+| `--llm` | boolean | Usa a API do Claude para compressão semântica. Requer `ANTHROPIC_API_KEY`. |
+| `--model=<alias>` | string | Modelo para o modo `--llm`. Valores: `haiku` (padrão), `sonnet`, `opus`. |
+| `--restore` | boolean | Restaura todos os agentes a partir dos backups `.original.md`. |
+| `--stats` | boolean | Exibe estatísticas de tamanho sem alterar arquivos. |
+
+---
+
+## Exemplos práticos
+
+### 1. Preview — ver o que seria comprimido sem alterar nada
+
+```bash
+aioson compress:agents . --dry-run
+```
+
+Saída esperada:
+```
+Preview — mode: structural
+
+Agents:
+  ~ dev.md: 14.5KB → 9.2KB  (−37%)
+  ~ analyst.md: 14.2KB → 9.8KB  (−31%)
+  ~ setup.md: 19.4KB → 11.3KB  (−42%)
+  · committer.md: 8.6KB — already compact, skipped
+
+─────────────────────────────────────
+Files processed : 29
+Compressed      : 3
+Total saved     : 18.2 KB
+```
+
+---
+
+### 2. Comprimir todos os agentes (modo estrutural)
+
+```bash
+aioson compress:agents .
+```
+
+Saída esperada:
+```
+Compress — mode: structural
+
+Agents:
+  ✓ dev.md: 14.5KB → 9.2KB  (−37%) ← backup saved
+  ✓ analyst.md: 14.2KB → 9.8KB  (−31%) ← backup saved
+  ✓ setup.md: 19.4KB → 11.3KB  (−42%) ← backup saved
+  · committer.md: 8.6KB — already compact, skipped
+
+─────────────────────────────────────
+Files processed : 29
+Compressed      : 3
+Total saved     : 18.2 KB
+
+Backups: <agent>.original.md
+Restore: aioson compress:agents . --restore
+```
+
+O arquivo original é salvo automaticamente como `dev.original.md` antes de qualquer alteração.
+
+---
+
+### 3. Comprimir apenas agentes específicos
+
+```bash
+# Um agente
+aioson compress:agents . --agent=dev
+
+# Múltiplos agentes
+aioson compress:agents . --agent=dev,analyst,product
+
+# Preview dos mesmos
+aioson compress:agents . --agent=dev,analyst,product --dry-run
+```
+
+---
+
+### 4. Comprimir agentes + regras
+
+```bash
+aioson compress:agents . --rules
+```
+
+Útil logo após instalar o AIOSON em um projeto — comprime tanto os agentes quanto os arquivos em `.aioson/rules/` de uma só vez.
+
+---
+
+### 5. Compressão semântica via LLM (máxima redução)
+
+```bash
+# Com Haiku — barato, rápido (padrão)
+aioson compress:agents . --llm
+
+# Com Sonnet — melhor qualidade de compressão
+aioson compress:agents . --llm --model=sonnet
+
+# Preview antes de gastar créditos
+aioson compress:agents . --llm --dry-run
+```
+
+O modo `--llm` é mais agressivo: além dos padrões estruturais, reescreve parágrafos inteiros para a menor forma que preserva o significado completo. Recomendado para agentes grandes (> 10KB) onde o modo estrutural já não encontra mais ganhos.
+
+**Custo estimado por arquivo com Haiku:**
+| Tamanho | Tokens de entrada | Custo aprox. |
+|---------|-----------------|-------------|
+| 5 KB | ~1.300 tokens | < $0.001 |
+| 15 KB | ~3.800 tokens | ~$0.001 |
+| 65 KB | ~16.000 tokens | ~$0.004 |
+
+---
+
+### 6. Comprimir um agente de squad gerado automaticamente
+
+Agentes gerados pelo comando `aioson squad:agent-create` tendem a ser mais verbosos. Para comprimi-los:
+
+```bash
+# Os agentes de squad ficam em .aioson/squads/<slug>/agents/
+# Use o caminho do projeto como base
+aioson compress:agents . --agent=atendente-farmacia --dry-run
+```
+
+> **Nota:** No momento o comando aponta para `.aioson/agents/`. Para squads em `.aioson/squads/`, use `--llm` com o arquivo diretamente ou comprima manualmente o `.md` do agente.
+
+---
+
+### 7. Restaurar a versão original
+
+```bash
+# Restaurar todos
+aioson compress:agents . --restore
+
+# Restaurar apenas um agente
+aioson compress:agents . --restore --agent=dev
+```
+
+O restore lê o arquivo `.original.md`, sobrescreve o comprimido e remove o backup:
+
+```
+  Restored: dev.md
+  Restored: analyst.md
+
+Restored 2 file(s). Backup files removed.
+```
+
+---
+
+### 8. Ver estatísticas sem alterar arquivos
+
+```bash
+aioson compress:agents . --stats
+```
+
+Equivalente ao `--dry-run` mas semântica mais clara quando o objetivo é apenas monitorar o tamanho dos agentes.
+
+---
+
+## Como funciona o modo estrutural
+
+O modo estrutural processa cada arquivo em três etapas, protegendo o conteúdo técnico:
+
+**1. Proteção de blocos imutáveis**
+
+Antes de qualquer transformação, os seguintes elementos são extraídos e preservados intactos:
+- Frontmatter YAML (`---` ... `---`)
+- Code blocks (` ``` ` ... ` ``` `)
+- Tabelas markdown (`| ... |`)
+- Inline code (`` ` `` ... `` ` ``)
+- URLs e paths
+
+**2. Remoção de seções de baixo valor**
+
+Seções cujo header corresponde a um dos padrões abaixo são removidas por completo (header + conteúdo):
+
+| Header removido |
+|-----------------|
+| `## Por que isso importa` |
+| `## Por que isso é importante` |
+| `## Why this matters` |
+| `## Why this is important` |
+| `## Rationale` |
+
+Essas seções são removidas apenas quando o header corresponde exatamente — seções com conteúdo técnico único (listas, tabelas, exemplos) não são afetadas mesmo com nome similar.
+
+**3. Remoção de filler em linhas de prosa**
+
+Frases introdutórias sem valor informativo são removidas do início das linhas:
+
+| Padrão removido |
+|-----------------|
+| `É importante notar que` |
+| `Vale ressaltar que` |
+| `Deve-se observar que` |
+| `It is important to note that` |
+| `Note that` / `Please note that` |
+| `Keep in mind that` |
+| `As mentioned earlier` |
+| `Observe que` |
+
+Trailers ao fim de frases também são eliminados: `— o que garante...`, `— isso é fundamental porque...`, `como mencionado anteriormente`.
+
+---
+
+## Como funciona o modo LLM
+
+O modo `--llm` usa a [API Messages da Anthropic](https://docs.anthropic.com/en/api/messages) via `fetch` nativo (sem dependência extra no projeto). O prompt de sistema instrui o modelo a:
+
+- Preservar todo o conteúdo técnico (code blocks, tabelas, comandos, regras, constraints)
+- Remover redundância semântica — parágrafos que repetem o que já está acima
+- Comprimir explicações de múltiplos parágrafos para 1–2 frases densas
+- Não alterar frontmatter, paths, URLs
+
+O arquivo original é salvo como `.original.md` antes de qualquer escrita.
+
+---
+
+## Backup e segurança
+
+Toda compressão (estrutural ou LLM) gera um backup automático na primeira execução:
+
+```
+.aioson/agents/
+├── dev.md              ← arquivo comprimido (ativo)
+└── dev.original.md     ← backup original (para edição humana)
+```
+
+Se você editar o arquivo original e quiser recomprimi-lo, delete o `.original.md` antes — o comando não sobrescreve backups existentes para não perder alterações manuais.
+
+Para restaurar: `aioson compress:agents . --restore`
+
+---
+
+## Dúvidas frequentes
+
+**Os agentes funcionam igual após a compressão?**
+Sim. O modelo lê prose comprimida tão bem quanto prose longa — pesquisa do projeto Caveman mostra que brevidade pode até aumentar precisão em certos benchmarks. Nenhuma regra, instrução ou constraint é removida.
+
+**Quais arquivos são comprimidos?**
+Por padrão, apenas `.aioson/agents/*.md`. Com `--rules`, inclui `.aioson/rules/*.md`. Arquivos `.original.md` são sempre ignorados.
+
+**O que acontece se eu rodar duas vezes?**
+Na segunda execução, o arquivo já estará comprimido e o comando reportará "already compact, skipped". O backup `.original.md` não é sobrescrito.
+
+**Posso comprimir um único agente sem afetar os outros?**
+Sim: `aioson compress:agents . --agent=dev`
+
+**O modo `--llm` respeita o contexto do projeto?**
+O prompt de sistema foca em preservar conteúdo técnico universalmente — não lê o `project.context.md`. Para compressão consciente do projeto, use o modo estrutural (que é determinístico) e aplique `--llm` pontualmente nos agentes maiores.
+
+**Como integrar na atualização do framework?**
+Após `aioson update`, rode `aioson compress:agents . --dry-run` para ver se novos agentes ou regras têm ganho potencial. Execute sem `--dry-run` para aplicar.

package/docs/pt/design-docs-governance.md

@@ -0,0 +1,59 @@
+# Governança de Design Docs
+
+> Sistema modular de governança de código introduzido na v1.7.3+. Substitui a abordagem monolítica de um único `design-doc.md` por um diretório de regras duras que os agentes aplicam automaticamente.
+
+## O que mudou?
+
+Antes da v1.7.3, a governança de código dependia de um único arquivo `design-doc.md` gerado pelo `@discovery-design-doc`. Se esse arquivo não existisse, os agentes não tinham regras estruturais para seguir.
+
+Agora, o AIOSON distribui **5 arquivos de best-practice** em `.aioson/design-docs/` durante o `install`/`init`:
+
+| Arquivo | O que governa |
+|---|---|
+| `folder-structure.md` | Estrutura de pastas canônica por tipo de projeto |
+| `componentization.md` | Quando e como quebrar em componentes/módulos |
+| `code-reuse.md` | Regras de DRY, abstração e quando não abstrair |
+| `naming.md` | Convenções de nomenclatura (arquivos, funções, classes, variáveis) |
+| `file-size.md` | Limites de tamanho de arquivo e quando dividir |
+
+## Como funciona
+
+1. **Instalação automática**: ao rodar `aioson install` ou `aioson init`, os 5 arquivos são copiados para `.aioson/design-docs/`.
+2. **Descoberta determinística**: `aioson preflight . --agent=<agente>` lista os `.aioson/design-docs/*.md` aplicáveis em `design_governance`.
+3. **Carregamento eficiente**: `@dev`, `@deyvin`, `@architect`, `@analyst`, `@pm`, `@product` e `@sheldon` carregam os arquivos listados quando a tarefa envolve estrutura, nomenclatura, reuso, componentização ou tamanho de arquivo.
+4. **Hard constraints**: os arquivos carregados são tratados como restrições duras — o agente deve segui-las, não sugerir ignorá-las.
+5. **Extensível**: você pode adicionar novos arquivos `.md` em `.aioson/design-docs/`; com `agents: []` ou sem `agents`, eles aparecem para todos os agentes.
+
+## Diferença entre governança, design-doc e PRD
+
+| Artefato | Propósito | Quem cria | Quando muda |
+|---|---|---|---|
+| **PRD** (`prd.md`) | Visão, escopo, usuários, métricas | `@product` | Quando o produto evolui |
+| **design-doc** (`design-doc.md`) | Decisões de escopo, módulos, riscos, readiness | `@discovery-design-doc` | Por feature ou refactoring grande |
+| **Governança** (`.aioson/design-docs/*.md`) | Regras estruturais duras que aplicam-se a todo código | Distribuído pelo framework | Quando o time decide mudar convenções |
+
+> **Regra de ouro**: O PRD diz *o quê* construir. O design-doc diz *como* organizar a entrega. A governança diz *como* o código deve ser estruturado para ser mantido.
+
+## Customizando as regras
+
+Edite qualquer arquivo em `.aioson/design-docs/` para adaptar às convenções do seu time:
+
+```bash
+# Exemplo: ajustar limite de tamanho de arquivo
+aioson sandbox:exec . -- cat .aioson/design-docs/file-size.md
+
+# Editar
+code .aioson/design-docs/naming.md
+```
+
+Depois de editar, os agentes passam a usar suas convenções em vez das defaults.
+
+## Para projetos existentes
+
+Se você instalou o AIOSON antes da v1.7.3, rode:
+
+```bash
+aioson doctor . --fix
+```
+
+O doctor detectará arquivos padrão faltantes em `.aioson/design-docs/` e copiará apenas o que falta. Arquivos existentes são project-local e são preservados em updates.