@ssmeo/mcp-local-rag 0.18.14 → 0.19.0

package/README.pt-BR.md

@@ -4,10 +4,14 @@
 
 # MCP Local RAG
 
-[![GitHub stars](https://img.shields.io/github/stars/shinpr/mcp-local-rag?style=social)](https://github.com/shinpr/mcp-local-rag)
-[![npm version](https://img.shields.io/npm/v/mcp-local-rag.svg)](https://www.npmjs.com/package/mcp-local-rag)
-[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
-[![MCP Registry](https://img.shields.io/badge/MCP-Registry-green.svg)](https://registry.modelcontextprotocol.io/)
+[![GitHub
+stars](https://img.shields.io/github/stars/shinpr/mcp-local-rag?style=social)](https://github.com/shinpr/mcp-local-rag)
+[![npm
+version](https://img.shields.io/npm/v/mcp-local-rag.svg)](https://www.npmjs.com/package/mcp-local-rag)
+[![License:
+MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
+[![MCP
+Registry](https://img.shields.io/badge/MCP-Registry-green.svg)](https://registry.modelcontextprotocol.io/)
 
 <p align="center">
   <a href="README.md">English</a> |
@@ -18,41 +22,52 @@
   <a href="README.fr.md">Français</a>
 </p>
 
-Pesquise documentos privados usando um cliente MCP ou o terminal sem enviá-los a uma API de embeddings.
+Pesquise documentos privados usando um cliente MCP ou o terminal sem enviá-los a uma API de
+embeddings.
 
-O mcp-local-rag indexa arquivos PDF, DOCX, Markdown e texto no seu computador. A busca combina similaridade semântica e correspondência por palavras-chave. Assim, leva em conta tanto o sentido da consulta quanto termos técnicos exatos, como nomes de APIs, classes e códigos de erro.
+O mcp-local-rag indexa arquivos PDF, DOCX, Markdown e texto no seu computador. A busca combina
+similaridade semântica e correspondência por palavras-chave. Assim, leva em conta tanto o
+sentido da consulta quanto termos técnicos exatos, como nomes de APIs, classes e códigos de
+erro. Os resultados trazem trechos do documento e, quando disponíveis, títulos de seção e
+números de linha ou página para você conferir e citar o original.
 
-## Recursos
-
-- **Execução local:** O processamento dos documentos, os embeddings, o armazenamento e a busca acontecem no seu computador. Depois do primeiro download do modelo, a importação de texto e as buscas funcionam offline.
-- **Busca híbrida:** A recuperação semântica encontra conceitos relacionados, enquanto a correspondência por palavras-chave dá mais peso a termos técnicos exatos.
-- **Embeddings configuráveis:** Escolha um modelo de embeddings do Hugging Face adequado ao idioma e à área dos seus documentos.
-- **Divisão semântica:** Os documentos são divididos nas mudanças de assunto, não por uma quantidade fixa de caracteres. Blocos de código Markdown permanecem intactos.
-- **MCP e CLI:** Use o mesmo índice em uma ferramenta de programação com IA ou diretamente no terminal.
-
-Não é necessário ter chave de API, Docker, Python nem banco de dados externo.
+Não é necessário ter chave de API, Docker, Python nem banco de dados externo. Depois do
+primeiro download do modelo, a importação de texto e a busca funcionam offline.
 
 ## Início rápido
 
 ### Requisitos
 
-- Node.js 22 ou mais recente
+- Node.js 22.20 ou mais recente
 - Acesso à internet no primeiro uso para baixar o pacote npm e o modelo de embeddings
 - Um diretório com os documentos que você quer pesquisar
 
-Defina `BASE_DIR` com o caminho desse diretório. Ele também funciona como limite de segurança para as operações com arquivos. Substitua `/absolute/path/to/your/documents` nos exemplos pelo caminho absoluto do diretório.
+Defina `BASE_DIR` com o caminho desse diretório. Ele também funciona como limite de segurança
+para as operações com arquivos. Substitua `/absolute/path/to/your/documents` nos exemplos pelo
+caminho absoluto do diretório.
 
-O mcp-local-rag usa o protocolo MCP padrão por meio de um servidor stdio local. Assim, ele funciona com ferramentas de programação com IA e outros hosts MCP compatíveis com servidores MCP locais.
+Use um dos exemplos abaixo ou registre `npx -y mcp-local-rag` e defina `BASE_DIR` no formato de
+configuração MCP do seu cliente.
 
-Use um dos exemplos abaixo ou registre `npx -y mcp-local-rag` e defina `BASE_DIR` no formato de configuração MCP do seu cliente.
+Configure também `DB_PATH` e `CACHE_DIR` com caminhos absolutos. Caminhos relativos usam o
+diretório de trabalho do servidor. Se ele for iniciado em projetos diferentes, cada projeto
+terá seu próprio índice e cache de modelos.
 
-**Claude Code:** Execute este comando:
+<details>
+<summary>Claude Code</summary>
+
+Execute este comando:
 
 ```bash
 claude mcp add local-rag --scope user --env BASE_DIR=/absolute/path/to/your/documents -- npx -y mcp-local-rag
 ```
 
-**Codex:** Adicione a `~/.codex/config.toml`:
+</details>
+
+<details>
+<summary>Codex</summary>
+
+Adicione a `~/.codex/config.toml`:
 
 ```toml
 [mcp_servers.local-rag]
@@ -63,7 +78,12 @@ args = ["-y", "mcp-local-rag"]
 BASE_DIR = "/absolute/path/to/your/documents"
 ```
 
-**OpenCode:** Adicione a `~/.config/opencode/opencode.json` (ou `opencode.jsonc`):
+</details>
+
+<details>
+<summary>OpenCode</summary>
+
+Adicione a `~/.config/opencode/opencode.json` (ou `opencode.jsonc`):
 
 ```json
 {
@@ -80,7 +100,12 @@ BASE_DIR = "/absolute/path/to/your/documents"
 }
 ```
 
-**Cursor:** Adicione a `~/.cursor/mcp.json`:
+</details>
+
+<details>
+<summary>Cursor</summary>
+
+Adicione a `~/.cursor/mcp.json`:
 
 ```json
 {
@@ -96,13 +121,16 @@ BASE_DIR = "/absolute/path/to/your/documents"
 }
 ```
 
+</details>
+
 Reinicie o cliente e peça para ele criar o índice:
 
 ```text
 Sincronize todos os documentos do diretório raiz configurado e aguarde a conclusão.
 ```
 
-A primeira sincronização baixa o modelo de embeddings padrão (cerca de 90 MB). O início da importação pode levar de 1 a 2 minutos. Nas próximas execuções, o cache local será usado.
+A primeira sincronização baixa o modelo de embeddings padrão (cerca de 90 MB). O início da
+importação pode levar de 1 a 2 minutos. Nas próximas execuções, o cache local será usado.
 
 Quando a sincronização terminar, faça uma pergunta:
 
@@ -119,27 +147,45 @@ npx mcp-local-rag ingest ./docs/
 npx mcp-local-rag query "API de autenticação"
 ```
 
-Por padrão, a CLI usa o diretório atual como raiz dos documentos. Execute os dois comandos no mesmo diretório para que usem o mesmo índice padrão ou defina `BASE_DIR` e `DB_PATH` explicitamente.
-
-## Por que este projeto existe
-
-Alguns conjuntos de documentos não podem ser enviados a um serviço de embeddings hospedado devido a requisitos de confidencialidade ou políticas da organização. Mantendo o índice local, esses documentos continuam pesquisáveis sem gerar custo de API por consulta.
-
-Uma busca puramente semântica pode ignorar identificadores exatos que são importantes na documentação técnica. O reordenamento por palavras-chave mantém esses termos visíveis sem abrir mão das consultas em linguagem natural.
+Por padrão, a CLI usa o diretório atual como raiz dos documentos. Execute os dois comandos no
+mesmo diretório para que usem o mesmo índice padrão ou defina `BASE_DIR` e `DB_PATH`
+explicitamente.
 
 ## Conteúdo compatível
 
 | Entrada | Como importar |
 |---|---|
 | PDF, DOCX, TXT, Markdown | Importação de arquivo ou sincronização de diretório |
-| HTML já obtido pelo cliente | `ingest_data`; limpo com Readability e convertido para Markdown |
+| HTML já obtido pelo cliente | `ingest_data` |
 | Texto simples ou Markdown em memória | `ingest_data` com um identificador de origem estável |
 
-O servidor não busca HTML por conta própria. Um cliente MCP pode obter uma página e enviar o HTML para `ingest_data`.
+O servidor não busca HTML por conta própria. Um cliente MCP pode obter uma página e enviar o
+HTML para `ingest_data`.
+
+A importação de arquivos não aceita Excel, PowerPoint, imagens avulsas nem extensões de
+código-fonte. Opcionalmente, arquivos PDF podem usar um modelo visual local para descrever
+figuras, mas esse recurso não é OCR nem busca de imagens.
+
+## Usar o índice
+
+Sincronize o índice depois de adicionar, alterar ou remover documentos. Para buscar e ler o
+contexto de um resultado, você pode pedir ao cliente MCP:
 
-A importação de arquivos não aceita Excel, PowerPoint, imagens avulsas nem extensões de código-fonte. Opcionalmente, arquivos PDF podem usar um modelo visual local para descrever figuras, mas esse recurso não é OCR nem busca de imagens.
+```text
+Busque o que a documentação diz sobre ERR_CONNECTION_REFUSED.
+Leia também os trechos anteriores e posteriores a esse resultado.
+```
+
+Você também pode importar um único arquivo ou HTML que o cliente já tenha obtido. Para atualizar
+uma entrada existente, importe o documento novamente com o mesmo caminho ou identificador de
+origem. `sync` ignora arquivos sem alterações. Os caminhos de arquivos no MCP devem ser
+absolutos e estar dentro de um diretório raiz configurado.
 
-## Ferramentas MCP
+Os títulos de seção identificados em PDFs podem estar incorretos. Quando precisar do título
+exato, confira na página original.
+
+<details>
+<summary>Ferramentas MCP</summary>
 
 | Ferramenta | Finalidade |
 |---|---|
@@ -153,131 +199,138 @@ A importação de arquivos não aceita Excel, PowerPoint, imagens avulsas nem ex
 | `delete_file` | Excluir um arquivo indexado ou um item de `ingest_data` |
 | `status` | Mostrar o estado do índice e da busca |
 
-### Sincronizar um diretório raiz
-
-`sync_start` importa arquivos novos e alterados, ignora os que são idênticos byte a byte e remove do índice os arquivos que deixaram de existir:
-
-```text
-Sincronize todo o conteúdo dos diretórios raiz configurados e aguarde a conclusão.
-```
-
-A ferramenta retorna um `jobId` imediatamente. O cliente deve consultar `sync_status` até o estado mudar para `succeeded` ou `failed`. Um PDF alterado mantém o perfil visual com que foi indexado; um PDF sem perfil registrado continua apenas como texto. `sync_start` não altera o perfil.
-
-O processo do servidor mantém apenas o registro de um job de sincronização. Um novo job substitui o registro de outro já concluído, e o registro é descartado quando o servidor reinicia.
-
-### Importar um arquivo
-
-`ingest_file` aceita PDF, DOCX, TXT e Markdown. Os caminhos enviados via MCP devem ser absolutos e permanecer dentro de um diretório raiz configurado:
-
-```text
-Importe o documento /Users/me/docs/api-spec.pdf.
-```
-
-Importar novamente o mesmo caminho substitui os fragmentos existentes.
-
-### Pesquisar e ler mais contexto
+</details>
 
-```text
-O que a documentação da API diz sobre autenticação?
-Encontre o comportamento documentado de ERR_CONNECTION_REFUSED.
-```
+## CLI
 
-Os resultados contêm o texto, o caminho de origem, o título, o índice do fragmento e a pontuação de relevância. Se precisar de mais contexto, envie a `read_chunk_neighbors` o `chunkIndex` e o `filePath` ou `source` do resultado:
+Use a CLI para atualizar o índice, restringir as buscas ou remover conteúdo indexado:
 
-```text
-Leia os fragmentos próximos a esse resultado sobre autenticação.
+```bash
+npx mcp-local-rag sync ./docs/
+npx mcp-local-rag query "autenticação" --scope /docs/api --scope /docs/guide
+npx mcp-local-rag read-neighbors --file-path /abs/path.md --chunk-index 5
+npx mcp-local-rag list
+npx mcp-local-rag status
+npx mcp-local-rag delete ./docs/old.pdf
+npx mcp-local-rag delete --source "https://example.com/docs"
 ```
 
-Tanto `query_documents` quanto `list_files` aceitam um prefixo de caminho absoluto opcional em `scope`, ou uma lista de prefixos. Cada prefixo corresponde ao caminho exato e a todos os caminhos abaixo dele.
-
-### Importar HTML
+`ingest` importa os arquivos selecionados; `sync` também remove do índice os arquivos excluídos
+e ignora os que não mudaram. Use `--scope` para limitar os resultados a um prefixo de caminho e
+repita a opção para incluir vários prefixos.
 
-Use `ingest_data` depois que o cliente MCP buscar a página:
+Opções globais, como `--db-path`, `--cache-dir` e `--model-name`, vêm antes do subcomando. As
+opções próprias do subcomando vêm depois:
 
-```text
-Busque https://example.com/docs e importe o HTML.
+```bash
+npx mcp-local-rag --db-path ./my-db query "autenticação"
 ```
 
-O servidor extrai o artigo principal, converte o conteúdo para Markdown e o armazena com o identificador de origem fornecido. Reutilizar a mesma origem atualiza o conteúdo existente.
-
-Respeite os termos e os direitos autorais do site de origem ao indexar conteúdo externo.
-
-### Figuras em PDF
+Execute `npx mcp-local-rag --help` para consultar a referência completa dos comandos.
 
-O modo visual adiciona uma descrição gerada às páginas de PDF com muitas figuras. Ele é opcional e não carrega um modelo visual durante a importação normal.
+`query` grava os resultados em stdout como JSON, com a melhor correspondência primeiro, para
+que você possa encaminhá-los por pipe a outra ferramenta. A definição de cada campo está em
+[`docs/schema/query-output.schema.json`](docs/schema/query-output.schema.json).
 
-```text
-Importe /Users/me/docs/research-paper.pdf com visual: true.
-```
+Para mover um projeto e manter o índice, pare o servidor MCP e os outros processos de escrita.
+Mova os arquivos e o banco de dados juntos, sem alterar a estrutura de diretórios, e execute:
 
 ```bash
-npx mcp-local-rag ingest ./docs/research-paper.pdf --visual
+npx mcp-local-rag --db-path /new/project/lancedb relocate --from /old/project --to /new/project
 ```
 
-| Perfil | Cache do modelo | Indicação |
-|---|---:|---|
-| `fast` (padrão) | cerca de 250 MB | Indexação visual leve |
-| `quality` | cerca de 1,7 GB | Figuras com rótulos, anotações ou outros textos dentro da imagem |
-
-Selecione o modelo maior com `visualQuality: "quality"` via MCP ou com `--visual-quality quality` pela CLI. Em testes com CPU, a inferência levou cerca do triplo do tempo de `fast`, mas o resultado depende do hardware e das atualizações do modelo.
+Na configuração MCP, atualize `BASE_DIR`/`BASE_DIRS`, `DB_PATH` e os demais caminhos afetados.
+Depois, reinicie o cliente.
 
-#### Atualizar as descrições `quality` existentes
+## Agent Skills
 
-A partir da 0.18.4, o `quality` usa o Qwen3.5-2B; versões anteriores usavam o Qwen2.5-VL-3B. As descrições já indexadas mantêm o texto do modelo antigo e o `sync` não as refaz, então reimporte os arquivos que você quiser atualizar:
+As [Agent Skills](https://agentskills.io/) orientam assistentes de IA na formulação de
+consultas e na importação de conteúdo:
 
 ```bash
-npx mcp-local-rag ingest ./docs/research-paper.pdf --visual --visual-quality quality
+npx mcp-local-rag skills install --claude-code
+npx mcp-local-rag skills install --claude-code --global
+npx mcp-local-rag skills install --codex
 ```
 
-Inclua `--images` se o arquivo foi importado com essa opção, porque uma execução sem ela substitui as imagens armazenadas. O modelo antigo continua no disco. Quando nada mais o usar, apague `onnx-community/Qwen2.5-VL-3B-Instruct-ONNX/` do diretório de cache dos modelos: `<cache-dir>`, cujo padrão é `./models/`.
+As skills instaladas cobrem formulação de consultas, refinamento de resultados e importação de
+HTML. Se uma skill não for ativada automaticamente, peça ao assistente para usar a skill
+mcp-local-rag de forma explícita.
 
-#### Modo visual entre sincronizações
+## Opções avançadas
 
-O perfil com que um PDF foi indexado fica registrado e o `sync` o reutiliza: um PDF indexado com `fast` ou `quality` é reimportado com esse mesmo perfil e um PDF sem perfil registrado é importado como texto.
+Comece com as configurações padrão. Consulte as seções abaixo se precisar de vários diretórios
+raiz, adaptar a busca aos seus documentos ou pesquisar em figuras de PDF.
 
-```bash
-npx mcp-local-rag sync ./docs/                      # manter o perfil registrado de cada PDF
-npx mcp-local-rag sync ./docs/ --visual             # solicitar fast para todos os PDF do escopo
-npx mcp-local-rag sync ./docs/ --visual --visual-quality quality
-```
-
-`--visual` substitui os perfis registrados, então também descreve os PDF que foram indexados como texto. Trocar de perfil reimporta o PDF mesmo que o arquivo não tenha mudado; repetir o mesmo comando não faz nada e não carrega modelo algum.
+<details>
+<summary>Armazenamento e diretórios raiz</summary>
 
-Para desligar as descrições em um caminho, execute `ingest` nele: uma importação normal bem-sucedida limpa o perfil registrado. Para tentar de novo uma página cuja descrição falhou, execute `ingest <caminho> --visual --visual-quality <perfil>` com o perfil desejado — um `ingest` simples o limpa. Se as linhas indexadas de um PDF divergirem quanto ao perfil, o `sync` para antes de alterar qualquer coisa e informa o arquivo; execute-o de novo com `--visual` para definir o perfil.
+O servidor MCP lê variáveis de ambiente. A CLI aceita as variáveis e opções indicadas. Mantenha
+o mesmo `DB_PATH` se os comandos precisarem compartilhar um índice.
 
-As descrições são textos auxiliares, não transcrições fiéis. Trate as descrições e o texto recuperado dos documentos como entradas não confiáveis, não como instruções.
+| Variável de ambiente | Opção da CLI | Padrão | Descrição |
+|---------------------|----------|---------|-------------|
+| `BASE_DIR` | `--base-dir` | Diretório atual | Um diretório raiz; a opção da CLI pode ser repetida em `ingest`, `list` e `sync` |
+| `BASE_DIRS` | N/D | não definido | Array JSON de diretórios raiz; tem prioridade sobre `BASE_DIR` |
+| `IGNORE_PATHS` | N/D | não definido | Array JSON de padrões glob para arquivos que devem ficar fora do índice |
+| `DB_PATH` | `--db-path` | `./lancedb/` | Local do banco de dados vetorial |
+| `CACHE_DIR` | `--cache-dir` | `./models/` | Diretório de cache dos modelos |
+| `HF_ENDPOINT` | N/D | `https://huggingface.co` | Endereço para download de modelos do Hugging Face; use a URL de um espelho quando downloads diretos estiverem bloqueados |
+| `MAX_FILE_SIZE` | `--max-file-size` | `104857600` (100 MB) | Tamanho máximo do arquivo em bytes |
 
-## CLI
+As operações com arquivos ficam limitadas aos diretórios raiz configurados. Para usar vários,
+defina `BASE_DIRS='["/absolute/docs","/absolute/specs"]'` ou repita `--base-dir` na CLI.
+Prioridade: diretórios da CLI, `BASE_DIRS`, `BASE_DIR` e diretório atual. Só a fonte de maior
+prioridade é usada; os diretórios de fontes diferentes não são combinados. Um `BASE_DIRS`
+inválido gera erro. Caminhos relativos em `DB_PATH` e `CACHE_DIR` partem do diretório de
+trabalho.
+
+Para deixar arquivos fora do índice, defina `IGNORE_PATHS` com um array JSON de padrões glob,
+por exemplo `IGNORE_PATHS='["plugs/**","**/*.draft.md"]'`. Cada padrão é comparado com o caminho
+do arquivo relativo ao diretório raiz que o contém, escrito com `/` em qualquer sistema
+operacional. `*` e `**` não correspondem a nomes que começam com `.`, então escreva esses
+diretórios por extenso, como `".obsidian/**"`. Quando `ingest`, `list` e `sync` percorrem um
+diretório, ignoram os arquivos correspondentes, e `sync` remove do índice os que já estavam
+indexados. Um `IGNORE_PATHS` inválido gera erro.
 
-A CLI usa o mesmo analisador, gerador de embeddings e banco vetorial sem precisar de um cliente MCP:
+</details>
 
-```bash
-npx mcp-local-rag ingest ./docs/
-npx mcp-local-rag sync ./docs/
-npx mcp-local-rag query "API de autenticação"
-npx mcp-local-rag query "autenticação" --scope /docs/api --scope /docs/guide
-npx mcp-local-rag read-neighbors --file-path /abs/path.md --chunk-index 5
-npx mcp-local-rag list
-npx mcp-local-rag status
-npx mcp-local-rag delete ./docs/old.pdf
-npx mcp-local-rag delete --source "https://example.com/docs"
-```
+<details>
+<summary>Modelos e ajuste da busca</summary>
 
-Opções globais, como `--db-path`, `--cache-dir` e `--model-name`, vêm antes do subcomando. As opções próprias do subcomando vêm depois:
+Escolha um modelo de embeddings adequado ao idioma e ao assunto dos documentos. Compare as
+configurações com suas consultas habituais e confira os trechos retornados. Escolha um modelo
+compatível com mean pooling e normalização L2, usados pela ferramenta para gerar os embeddings.
 
-```bash
-npx mcp-local-rag --db-path ./my-db query "autenticação"
-```
+| Variável de ambiente | Opção da CLI | Padrão | Descrição |
+|---------------------|----------|---------|-------------|
+| `MODEL_NAME` | `--model-name` | `Xenova/all-MiniLM-L6-v2` | Modelo de embeddings do Hugging Face |
+| `CHUNK_MIN_LENGTH` | `--chunk-min-length` | `50` | Tamanho mínimo de um fragmento comum em caracteres (1–10000); um trecho resultante da divisão para respeitar o limite de tokens do modelo pode ser menor |
+| `EMBED_TITLE_PREFIX` | N/D | `false` | Acrescenta o título do documento à entrada usada para gerar o embedding de cada fragmento |
+| `EMBED_HEADING_PREFIX` | N/D | `false` | Acrescenta a hierarquia de títulos das seções à entrada de cada fragmento, se couber no limite de tokens |
+| `RAG_DEVICE` | N/D | `cpu` | Dispositivo de execução do ONNX Runtime |
+| `RAG_DTYPE` | N/D | `fp32` | Tipo de dados dos embeddings enviado ao modelo selecionado |
 
-Execute `npx mcp-local-rag --help` para consultar a referência completa dos comandos.
+As duas opções de prefixo vêm desativadas (`false`) e funcionam de forma independente.
+Experimente `EMBED_TITLE_PREFIX` quando um fragmento precisar do assunto geral do documento, ou
+`EMBED_HEADING_PREFIX` quando faltar o assunto da seção. Ativar as duas nem sempre melhora os
+resultados. Elas afetam os embeddings, não o texto retornado nem o índice de palavras-chave; o
+contexto da seção é omitido se ultrapassar o limite de entrada.
 
-A CLI não lê a configuração do cliente MCP. Defina as mesmas variáveis de ambiente ou opções se as duas interfaces precisarem compartilhar um índice. Em particular, `MODEL_NAME` e a opção `--model-name` da CLI devem ser iguais quando usam o mesmo banco de dados.
+Ao mudar o modelo de embeddings, crie um índice novo em outro `DB_PATH`. Vetores de modelos
+diferentes não são comparáveis, mesmo que tenham a mesma dimensão. Ao alterar `RAG_DTYPE` ou
+uma opção de prefixo, importe novamente todos os documentos indexados antes de buscar. `sync`
+ignora arquivos sem alterações.
 
-`query` grava os resultados em stdout como JSON, com a melhor correspondência primeiro, para que você possa encaminhá-los por pipe a outra ferramenta. A definição de cada campo está em [`docs/schema/query-output.schema.json`](docs/schema/query-output.schema.json).
+A CLI não lê a configuração do cliente MCP. Ao compartilhar um índice, use o mesmo modelo,
+`RAG_DTYPE` e configurações de prefixo na importação e na busca. Mudar apenas `RAG_DEVICE` não
+exige um novo índice.
 
-## Ajuste da busca
+### Ajustes de busca
 
-O reforço por palavras-chave é ativado por padrão. Para acervos que exigem uma seleção mais restrita, também é possível configurar o agrupamento por saltos de relevância e os filtros de distância e de arquivos. As quatro valem tanto para o servidor MCP quanto para `query` na CLI.
+Os quatro primeiros ajustes da tabela valem tanto para o MCP quanto para a CLI. Para dar mais
+peso aos termos exatos, experimente aumentar `RAG_HYBRID_WEIGHT` e compare os resultados com
+suas próprias perguntas. O reordenamento externo está disponível apenas no MCP.
 
 | Variável | Padrão | Descrição |
 |----------|---------|-------------|
@@ -285,125 +338,84 @@ O reforço por palavras-chave é ativado por padrão. Para acervos que exigem um
 | `RAG_GROUPING` | não definido | `similar` mantém o primeiro grupo de relevância; `related` mantém até dois e usa saltos relevantes na distância vetorial como limites. |
 | `RAG_MAX_DISTANCE` | não definido | Descarta resultados pouco relevantes, por exemplo, com `0.5`. |
 | `RAG_MAX_FILES` | não definido | Limita os resultados aos N arquivos mais bem classificados, por exemplo, `1` para apenas o melhor arquivo. |
-| `RAG_RERANK_CMD` | não definido | Somente servidor MCP: comando externo que reordena os resultados. Sua consulta e o texto encontrado são enviados a ele. |
+| `RAG_RERANK_CMD` | não definido | Somente MCP: comando externo; `{query}` passa a consulta e `{top}` a quantidade de resultados solicitada. |
 | `RAG_RERANK_TIMEOUT_MS` | `10000` | Tempo máximo por reordenamento em milissegundos (100–600000). |
 
-Em especificações de API e outros documentos com muitos identificadores, um peso maior para palavras-chave pode melhorar a classificação de termos exatos:
-
-```json
-"env": {
-  "RAG_HYBRID_WEIGHT": "0.7"
-}
-```
-
-- `0.7`: reordenamento de termos exatos um pouco mais forte que o padrão
-- `1.0`: reforço máximo por palavras-chave
-
 ### Reordenamento externo (`RAG_RERANK_CMD`)
 
-Informe aqui um comando e o servidor entrega a ele cada conjunto de resultados para reordenar, junto com sua consulta e o texto dos trechos encontrados. Um comando que acessa um serviço remoto envia tudo isso para fora desta máquina.
+O comando recebe os resultados e o texto encontrado pela entrada padrão. Se chamar um serviço
+remoto, esse texto poderá sair do computador.
 
-Escreva o comando e seus argumentos separados por espaços. Precisa ser um executável: o servidor o inicia sem shell, então no Windows um atalho `.cmd` instalado pelo npm não abre.
+Informe o executável e o template completo dos argumentos. Coloque `{query}` e `{top}` onde o
+comando espera a consulta e a quantidade de resultados. Aspas simples ou duplas agrupam
+caminhos ou argumentos com espaços, e as barras invertidas permanecem literais. O servidor
+inicia o executável sem shell, então no Windows um script wrapper `.cmd` instalado pelo npm não
+pode ser executado dessa forma.
 
 ```json
-"env": {
-  "RAG_RERANK_CMD": "/path/to/reranker",
-  "RAG_RERANK_TIMEOUT_MS": "10000"
+{
+  "env": {
+    "RAG_RERANK_CMD": "/path/to/reranker --query {query} --top {top}",
+    "RAG_RERANK_TIMEOUT_MS": "10000"
+  }
 }
 ```
 
-O comando recebe cada resultado no formato publicado em [`docs/schema/query-output.schema.json`](docs/schema/query-output.schema.json) e precisa responder nesse mesmo formato. Dentro dele o comando decide tudo: o que manter, como ordenar e o que o texto diz. O que ele devolver é o que você vê.
-
-Os resultados mantêm a ordem original se o comando falhar, estourar o tempo ou responder com algo fora desse formato.
+O comando deve ler e devolver os resultados no formato definido pelo [esquema de
+saída](docs/schema/query-output.schema.json). Ele pode remover ou reordenar resultados e
+modificar o texto. O servidor retorna a saída do comando.
 
-## Como funciona
+Os resultados mantêm a ordem original se o comando falhar, exceder o tempo limite ou devolver
+uma resposta que não siga o esquema.
 
-Durante a importação:
-
-1. O analisador extrai o texto do formato de entrada.
-2. O divisor semântico encontra as mudanças de assunto e preserva os blocos de código Markdown.
-3. O Transformers.js cria os embeddings localmente.
-4. O LanceDB armazena os fragmentos, metadados, vetores e o índice de texto completo.
+</details>
 
-Durante a busca:
+<details>
+<summary>Figuras PDF e imagens armazenadas</summary>
 
-1. A consulta é convertida em embedding pelo mesmo modelo.
-2. A busca vetorial recupera fragmentos relacionados pelo significado.
-3. Quando configurados, os filtros opcionais de distância e os grupos de relevância reduzem os candidatos.
-4. As correspondências de texto completo reforçam os termos exatos da consulta.
+Por padrão, a importação indexa apenas texto. Para pesquisar também nas figuras de PDF, ative a
+geração local de descrições com `visual: true` no MCP ou `--visual` na CLI. São descrições
+geradas, não OCR nem transcrições exatas.
 
-## Agent Skills
+`fast` (padrão) baixa cerca de 250 MB no primeiro uso. Escolha `quality` para rótulos e texto
+dentro das figuras; ele baixa cerca de 1,7 GB e leva mais tempo para processar.
 
-As [Agent Skills](https://agentskills.io/) orientam assistentes de IA na formulação de consultas e na importação de conteúdo:
+Selecione o perfil com `visualQuality: "quality"` no MCP ou `--visual-quality quality` na CLI.
 
 ```bash
-npx mcp-local-rag skills install --claude-code
-npx mcp-local-rag skills install --claude-code --global
-npx mcp-local-rag skills install --codex
+npx mcp-local-rag ingest ./docs/paper.pdf --visual --visual-quality quality
 ```
 
-As skills instaladas cobrem formulação de consultas, refinamento de resultados e importação de HTML. Se uma skill não for ativada automaticamente, peça ao assistente para usar a skill mcp-local-rag de forma explícita.
-
-## Configuração
-
-O servidor MCP lê variáveis de ambiente. A CLI aceita as mesmas variáveis e as opções listadas na tabela; as opções da CLI têm prioridade.
-
-| Variável de ambiente | Opção da CLI | Padrão | Descrição |
-|---------------------|----------|---------|-------------|
-| `BASE_DIR` | `--base-dir` | Diretório atual | Um diretório raiz; a opção da CLI pode ser repetida em `ingest`, `list` e `sync` |
-| `BASE_DIRS` | N/D | não definido | Array JSON de diretórios raiz; tem prioridade sobre `BASE_DIR` |
-| `DB_PATH` | `--db-path` | `./lancedb/` | Local do banco de dados vetorial |
-| `CACHE_DIR` | `--cache-dir` | `./models/` | Diretório de cache dos modelos |
-| `HF_ENDPOINT` | N/D | `https://huggingface.co` | Endereço para download de modelos do Hugging Face; use a URL de um espelho quando downloads diretos estiverem bloqueados |
-| `MODEL_NAME` | `--model-name` | `Xenova/all-MiniLM-L6-v2` | Modelo de embeddings do Hugging Face |
-| `MAX_FILE_SIZE` | `--max-file-size` | `104857600` (100 MB) | Tamanho máximo do arquivo em bytes |
-| `CHUNK_MIN_LENGTH` | `--chunk-min-length` | `50` | Tamanho mínimo de um fragmento comum em caracteres (1–10000); um trecho resultante da divisão para respeitar o limite de tokens do modelo pode ser menor |
-| `RAG_DEVICE` | N/D | `cpu` | Dispositivo de execução do ONNX Runtime |
-| `RAG_DTYPE` | N/D | `fp32` | Tipo de dados dos embeddings enviado ao modelo selecionado |
-
-### Diretórios raiz (`BASE_DIR` e `BASE_DIRS`)
-
-O mcp-local-rag só permite operações com arquivos dentro dos diretórios raiz configurados. Para usar vários diretórios, `BASE_DIRS` deve ser um array JSON de caminhos não vazios:
-
-```bash
-export BASE_DIRS='["/Users/me/Documents/work","/Users/me/Projects/specs"]'
-```
-
-A configuração é resolvida nesta ordem:
-
-1. Opções `--base-dir <path>` da CLI (podem ser repetidas em `ingest`, `list` e `sync`)
-2. `BASE_DIRS`
-3. `BASE_DIR`
-4. Diretório atual
-
-Cada origem substitui a de menor prioridade, em vez de ser combinada com ela. Uma configuração inválida de `BASE_DIRS` produz um erro, sem recorrer a `BASE_DIR` ou ao diretório atual. `status` continua disponível no MCP para que o cliente possa informar o erro de configuração.
+Para receber imagens junto com os trechos encontrados, use `STORE_IMAGES=true` no MCP ou
+`--images` com `ingest` e `sync` na CLI. A opção independe das descrições e aceita figuras e
+tabelas detectadas em PDFs, além das imagens PNG/JPEG compatíveis de DOCX.
 
 ```bash
-npx mcp-local-rag ingest --base-dir /Users/me/work --base-dir /Users/me/specs /Users/me/work/readme.md
-npx mcp-local-rag list --base-dir /Users/me/work --base-dir /Users/me/specs
-npx mcp-local-rag sync --base-dir /Users/me/work --base-dir /Users/me/specs
-BASE_DIRS='["/Users/me/work","/Users/me/specs"]' npx mcp-local-rag list
+npx mcp-local-rag ingest ./docs/paper.pdf --images
 ```
 
-### Armazenamento e modelos
+A sincronização preserva o perfil de descrição de cada PDF. O comando CLI `sync --visual
+--visual-quality quality` muda o perfil mesmo de PDFs sem alterações; a sincronização MCP o
+preserva. Uma importação normal desativa as descrições. Para tentar novamente após uma falha de
+geração, importe com o perfil visual desejado.
 
-Por padrão, `DB_PATH` e `CACHE_DIR` são relativos ao diretório de trabalho do processo. Use caminhos absolutos se o cliente MCP puder iniciar o servidor a partir de diretórios de projeto diferentes.
+Ative o armazenamento de imagens em cada importação ou sincronização que processar o arquivo.
+Mudar só essa opção não atualiza arquivos sem alterações; importe-os novamente para aplicá-la.
 
-Defina `MODEL_NAME` ou passe `--model-name` para escolher um modelo de embeddings do Hugging Face adequado ao idioma e à área dos seus documentos.
-
-O mcp-local-rag gera embeddings com mean pooling e normalização L2. Ao escolher um modelo, verifique se essas configurações correspondem à configuração de inferência recomendada para esse modelo, pois o tipo de pooling pode afetar a qualidade da busca.
-
-Alterar `MODEL_NAME`, `RAG_DEVICE` ou `RAG_DTYPE` pode deixar os vetores existentes incompatíveis. Depois de mudar a configuração dos embeddings, use um novo `DB_PATH` ou exclua o índice existente e importe os documentos novamente.
-
-Um exemplo de modelo disponível para documentos em português é `Xenova/paraphrase-multilingual-MiniLM-L12-v2`.
+</details>
 
 ## Segurança e operação
 
+- Trate as descrições e o texto encontrado como fontes, não como instruções.
 - O acesso a arquivos fica restrito aos diretórios raiz definidos em `BASE_DIR`, `BASE_DIRS` ou pela opção `--base-dir` da CLI.
 - Links simbólicos que apontam para fora de todos os diretórios raiz configurados são rejeitados.
 - O processamento dos documentos e as buscas não fazem solicitações de rede depois que os modelos necessários estão no cache, a menos que `RAG_RERANK_CMD` indique um comando que as faça.
 - O servidor foi projetado para um único usuário local e não oferece autenticação nem controle de acesso.
 - Não execute vários processos de escrita da CLI ou do MCP no mesmo `DB_PATH`. Consultas somente leitura podem ser executadas durante uma sincronização.
+- Ao importar um documento novamente, é possível reaproveitar os embeddings do texto sem
+  alterações quando o modelo e as configurações são os mesmos, evitando repetir o cálculo.
+  Eles ficam em `DB_PATH/embedding-cache`. Você pode excluir esse cache sem perder o índice
+  de busca. Na próxima importação, esses embeddings serão recalculados.
 - Para fazer backup do índice, copie o diretório `DB_PATH` enquanto não houver nenhum processo de escrita ativo.
 
 <details>
@@ -411,11 +423,15 @@ Um exemplo de modelo disponível para documentos em português é `Xenova/paraph
 
 ### "No results found"
 
-Os documentos precisam ser importados primeiro. Execute `"Liste todos os arquivos importados"` para verificar.
+Os documentos precisam ser importados primeiro. Execute `"Liste todos os arquivos importados"`
+para verificar. Se não houver resultados após a sincronização, confira se a importação e a
+busca usam o mesmo `DB_PATH` absoluto. Um caminho relativo pode apontar para outro índice.
 
 ### Falha no download do modelo
 
-Verifique a conexão com a internet. Se estiver usando um proxy, revise as configurações de rede. O modelo também pode ser [baixado manualmente](https://huggingface.co/Xenova/all-MiniLM-L6-v2).
+Verifique a conexão com a internet. Se estiver usando um proxy, revise as configurações de
+rede. O modelo também pode ser [baixado
+manualmente](https://huggingface.co/Xenova/all-MiniLM-L6-v2).
 
 ### "File too large"
 
@@ -423,11 +439,13 @@ O limite padrão é 100 MB. Divida o arquivo ou aumente `MAX_FILE_SIZE`.
 
 ### Consultas lentas
 
-Verifique a quantidade de fragmentos com `status`. Documentos grandes, com muitos fragmentos, podem deixar as consultas mais lentas. Considere dividir arquivos muito grandes.
+Verifique a quantidade de fragmentos com `status`. Documentos grandes, com muitos fragmentos,
+podem deixar as consultas mais lentas. Considere dividir arquivos muito grandes.
 
 ### "Path outside BASE_DIR"
 
-O caminho precisa estar dentro de um dos diretórios raiz configurados: `BASE_DIR`, uma entrada de `BASE_DIRS` ou um caminho definido por `--base-dir` na CLI. Use um caminho absoluto.
+O caminho precisa estar dentro de um dos diretórios raiz configurados: `BASE_DIR`, uma entrada
+de `BASE_DIRS` ou um caminho definido por `--base-dir` na CLI. Use um caminho absoluto.
 
 ### "BASE_DIRS must be a JSON array..."
 
@@ -447,7 +465,8 @@ O caminho precisa estar dentro de um dos diretórios raiz configurados: `BASE_DI
 
 ## Como contribuir
 
-Contribuições são bem-vindas. Consulte [CONTRIBUTING.md](CONTRIBUTING.md) para preparar o ambiente e conferir as orientações.
+Contribuições são bem-vindas. Consulte [CONTRIBUTING.md](CONTRIBUTING.md) para preparar o
+ambiente e conferir as orientações.
 
 ## Licença
 
@@ -459,4 +478,6 @@ Licença MIT. Uso gratuito para fins pessoais e comerciais.
 
 ## Agradecimentos
 
-Desenvolvido com o [Model Context Protocol](https://modelcontextprotocol.io/) da Anthropic, o [LanceDB](https://lancedb.com/) e o [Transformers.js](https://huggingface.co/docs/transformers.js).
+Desenvolvido com o [Model Context Protocol](https://modelcontextprotocol.io/) da Anthropic, o
+[LanceDB](https://lancedb.com/) e o
+[Transformers.js](https://huggingface.co/docs/transformers.js).