@jaimevalasek/aioson 1.7.2 → 1.9.0

package/docs/pt/{busca-de-contexto.md → _arquivo/busca-de-contexto.md}

@@ -1,129 +1,136 @@
-# 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
-    }
-  ]
-}
-```
+# [Arquivado] Busca de Contexto
+
+> **Esta doc foi consolidada em [`5-referencia/memoria-e-contexto.md`](../5-referencia/memoria-e-contexto.md)**.
+> Conteúdo abaixo preservado para referência histórica.
+
+---
+
+# 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 → _arquivo/cache-de-contexto.md}

@@ -1,156 +1,163 @@
-# 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
+# [Arquivado] Cache de Contexto
+
+> **Esta doc foi consolidada em [`5-referencia/memoria-e-contexto.md`](../5-referencia/memoria-e-contexto.md)**.
+> Conteúdo abaixo preservado para referência histórica.
+
+---
+
+# 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