@jaimevalasek/aioson 1.5.1 → 1.7.0

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