dsh-locator 0.7.5 → 0.7.7

package/README-pt.md

@@ -2,9 +2,9 @@
 
 # 🔎 dsh-locator
 
-**Busca de arquivos em todo o disco, em milissegundos, para o DeepSeek Harness — sem o Everything.**
+**Busque por nome quando lembra do nome e por conteúdo quando lembra da frase; depois abra o arquivo ou volte para a conversa.**
 
-Índice próprio multiplataforma (Windows USN/MFT · macOS FSEvents · Linux inotify), seis ferramentas para o agente — nomes, conteúdo e sessões — e um painel web ordenável.
+Busca de arquivos em todo o disco para o [DeepSeek Harness](https://github.com/deepseek-ai/deepseek-harness) com **índice próprio**: sem instalar o Everything, sem `es.exe`, com as mesmas ferramentas e o mesmo painel no Windows, macOS e Linux.
 
 [![npm version](https://img.shields.io/npm/v/dsh-locator)](https://www.npmjs.com/package/dsh-locator)
 [![npm downloads](https://img.shields.io/npm/dm/dsh-locator)](https://www.npmjs.com/package/dsh-locator)
@@ -12,7 +12,8 @@
 [![version](https://img.shields.io/github/v/tag/PerryLink/dsh-locator?label=version)](https://github.com/PerryLink/dsh-locator/releases)
 [![License](https://img.shields.io/badge/license-Apache%202.0-blue.svg)](LICENSE)
 [![DSH plugin](https://img.shields.io/badge/dsh--plugin-✅-green)](https://github.com/topics/dsh-plugin)
-[![Node](https://img.shields.io/badge/node-%5E22.19%20%7C%7C%20%3E%3D24-brightgreen.svg)](#)
+[![Awesome DSH](https://img.shields.io/badge/awesome--dsh--plugin-listed-2ea44f)](https://github.com/awesome-dsh-plugin/awesome-dsh-plugin)
+[![Node](https://img.shields.io/badge/node-%5E22.19%20%7C%7C%20%3E%3D24-brightgreen.svg)](#versão-e-compatibilidade)
 [![Gitee](https://img.shields.io/badge/Gitee-mirror-c71d23?logo=gitee)](https://gitee.com/perrylink/dsh-locator)
 [![GitCode](https://img.shields.io/badge/GitCode-mirror-1f6feb)](https://gitcode.com/PerryLink/dsh-locator)
 
@@ -24,15 +25,62 @@ dsh plugin --profile web add dsh-locator
 
 </div>
 
-> **Repositório oficial:** [GitHub `PerryLink/dsh-locator`](https://github.com/PerryLink/dsh-locator). Gitee e GitCode são espelhos sincronizados automaticamente; o GitHub é a fonte da verdade.
->
-> Faz parte da [família de plugins DSH](https://github.com/PerryLink) (Apache-2.0). Se ajudar, **uma ⭐ ajuda a próxima pessoa a encontrar**; nada é liberado por isso.
+> **Repositório oficial:** [GitHub `PerryLink/dsh-locator`](https://github.com/PerryLink/dsh-locator); Gitee e GitCode são espelhos sincronizados automaticamente, e o GitHub é a fonte da verdade. Faz parte da [família de plugins do DSH](https://github.com/PerryLink) (Apache-2.0) e está listado no [awesome-dsh-plugin](https://github.com/awesome-dsh-plugin/awesome-dsh-plugin). Uma ⭐ ajuda a próxima pessoa a encontrá-lo; nada fica bloqueado atrás dela.
+
+## Índice
+
+- [De relance](#de-relance)
+- [Como difere de Everything / Spotlight / grep](#como-difere-de-everything--spotlight--grep)
+- [Instalação](#instalação)
+- [Primeira execução](#primeira-execução)
+- [Duas buscas](#duas-buscas)
+- [Painel web](#painel-web)
+- [Ferramentas](#ferramentas)
+- [Linguagem de consulta](#linguagem-de-consulta)
+- [Configuração](#configuração)
+- [Desempenho e recursos](#desempenho-e-recursos)
+- [Suporte de plataformas](#suporte-de-plataformas)
+- [Solução de problemas](#solução-de-problemas)
+- [Compilar a partir do código-fonte](#compilar-a-partir-do-código-fonte)
+- [Design](#design)
+- [Limitações](#limitações)
+- [Memória](#memória)
+- [Segurança e privacidade](#segurança-e-privacidade)
+- [Versão e compatibilidade](#versão-e-compatibilidade)
+- [Roteiro](#roteiro)
+- [Licença](#licença)
+
+## De relance
+
+Buscar arquivos tem duas formas:
+
+- **Você lembra do nome mas não do local.** `glob`/`grep` percorrem o workspace a cada chamada: ótimo quando você conhece o diretório, doloroso quando lembra só de metade do nome.
+- **Você lembra de uma frase, de uma decisão ou de um trecho, não do arquivo nem da conversa.** Um índice de nomes não ajuda, e os logs de sessão do DSH também são dados de primeira classe.
+
+O `dsh-locator` junta os dois em um único plugin:
+
+| Recurso | Como usar |
+|---|---|
+| Busca por nome / caminho | `locator_search`, ou o modo padrão do painel |
+| Busca no corpo dos arquivos | `locator_find`, ou o modo **Buscar conteúdo** do painel |
+| Busca em sessões do DSH | As mesmas ferramentas; os resultados trazem `sessionId` / `messageId` e o painel pode voltar à conversa |
+| Abrir / revelar | As ferramentas devolvem caminhos; o painel revela com duplo clique, `Ctrl+O` abre e `Ctrl+Enter` insere `@"caminho"` no compositor |
+| Consumo externo | `locator_export` grava um espelho SQLite somente leitura |
+
+O índice é local: sem chamadas de rede, sem telemetria, sem uploads; o plugin nunca modifica, move ou apaga os arquivos indexados.
 
-`dsh-locator` indexa uma vez os diretórios escolhidos, guarda o resultado num instantâneo compacto, aplica as mudanças do sistema de arquivos e responde consultas de nome/caminho em dezenas de milissegundos sobre mais de um milhão de entradas. O agente recebe `locator_search`, `locator_status`, `locator_rebuild` e `locator_export`; as pessoas têm um **painel global** na Web GUI (`Ctrl+Shift+F` ou a lupa no rodapé da barra lateral).
+## Como difere de Everything / Spotlight / grep
 
-## Por que outro buscador?
+| | dsh-locator | Everything | Spotlight | `glob` / `grep` |
+|---|---|---|---|---|
+| Plataformas | Windows / macOS / Linux / WSL | Windows | macOS | Multiplataforma |
+| Índice | Persistente, próprio | Persistente (USN do NTFS) | Índice do sistema (metadados/conteúdo) | Percorre a cada chamada |
+| Busca no conteúdo | Arquivos de texto + mensagens de sessão do DSH | Só nomes por padrão | Sim, varia por sistema | Sim, sem índice |
+| Salto para sessão | Resultados trazem `sessionId` / `messageId` | Não | Não | Não |
+| Ferramentas para agentes | Seis ferramentas, uma linguagem de consulta | Precisa de CLI/serviço | Precisa de scripts próprios | Nativas, sem índice persistente |
+| Velocidade no Windows | Perto do Everything (USN opcional) | Mais rápido e leve | Não se aplica | Mais lento que um índice |
 
-`glob` e `grep` percorrem o workspace a cada chamada: rápidos quando você sabe o diretório, lentos quando lembra só parte de um nome. O Everything é excelente no Windows, mas só existe no Windows; envolvê-lo deixa macOS, Linux, WSL e hosts remotos de fora. O `dsh-locator` é dono do índice, então as mesmas ferramentas funcionam onde Node e Go rodam.
+Resumindo: a **ideia** do Everything (índice persistente + consultas estruturadas) foi implementada de forma independente e multiplataforma, com as sessões do DSH por cima. Não é um invólucro do Everything.
 
 ## Instalação
 
@@ -40,150 +88,328 @@ dsh plugin --profile web add dsh-locator
 # npm (recomendado)
 dsh plugin --profile web add dsh-locator
 
-# GitHub main
+# fixar uma versão
+dsh plugin --profile web add dsh-locator@0.7.7
+
+# branch principal do GitHub
 dsh plugin --profile web add github:PerryLink/dsh-locator
 
-# do código
+# a partir de um checkout
 pnpm install
 pnpm build
-pnpm build:engine
+pnpm build:engine        # motor Go da plataforma atual
 dsh plugin --profile web add /caminho/absoluto/dsh-locator
 
-# tarball
+# a partir de um tarball (saída do npm pack; troque pela versão real)
 npm pack
-dsh plugin --profile web add /caminho/absoluto/dsh-locator-0.5.0.tgz
+dsh plugin --profile web add /caminho/absoluto/dsh-locator-0.7.7.tgz
 ```
 
-O pacote npm inclui motores pré-compilados para `linux-x64`, `linux-arm64`, `win32-x64`, `win32-arm64`, `darwin-x64` e `darwin-arm64`.
+- O pacote inclui motores pré-compilados para `linux-x64`, `linux-arm64`, `win32-x64`, `win32-arm64`, `darwin-x64` e `darwin-arm64`; não é preciso Go local.
+- Se o espelho npm estiver atrasado, adicione `--registry=https://registry.npmjs.org` ao comando.
+- Depois de instalar em um perfil Web **em execução**, **recarregue a página** (`F5`): as ferramentas do host podem montar na hora, mas o painel do navegador é carregado do boot graph ao abrir a página. Perfis headless/TUI só têm as ferramentas.
+- Atualizar: `dsh plugin --profile web add dsh-locator@latest` e depois `F5`. Uma mudança de esquema do conteúdo reconstrói o banco uma vez.
+- Desinstalar: `dsh plugin --profile web remove dsh-locator`; para manter a configuração mas desativar, `enabled: false`.
+
+## Primeira execução
+
+Na primeira montagem o motor indexa as raízes configuradas (padrão: seu diretório pessoal) e grava o snapshot e o banco de conteúdo no diretório de cache da plataforma:
+
+| Plataforma | Diretório de estado padrão |
+|---|---|
+| Windows | `%LOCALAPPDATA%\dsh-locator` |
+| macOS | `~/Library/Application Support/dsh-locator` |
+| Linux | `$XDG_CACHE_HOME/dsh-locator` ou `~/.cache/dsh-locator` |
+
+A primeira varredura de um diretório pessoal grande lê o disco; os próximos inícios carregam o snapshot. As requisições são atendidas **durante** essa varredura: a busca devolve o que já foi indexado com `indexing: true`, e o rodapé do painel avisa que o índice ainda está sendo construído.
+
+Por padrão, `node_modules`, `.git`, `.hg`, `.svn`, `.cache`, `__pycache__`, `.venv`, `venv` e `.next` são ignorados por nome; `excludes` altera a lista.
+
+Experimente:
+
+```text
+Encontre os PDFs que alterei na semana passada
+Onde "contentRefreshMs" foi discutido?
+Em qual conversa este desenho foi decidido?
+```
 
-Ao instalar num perfil Web já em execução, **recarregue a página** (`F5`): as ferramentas podem montar a quente, mas o painel (`client.js`) vem do boot graph no carregamento. Perfis headless/TUI não montam painel.
+## Duas buscas
+
+### Por nome: `locator_search`
+
+Sintaxe no estilo Everything devolvendo caminho, tamanho, data de modificação, extensão e tipo. Ideal para “o nome contém report”, “PDFs alterados esta semana”, “vídeos com mais de 50 MB”.
+
+Ordenação, paginação e `limit`/`offset` são feitos no motor do host; consultas comuns sobre 1,51 M de entradas respondem em dezenas de milissegundos.
+
+### Por conteúdo: `locator_find`
+
+Pesquisa no **corpo** de arquivos de texto e mensagens de sessão do DSH e devolve trechos com a origem:
+
+- resultados de arquivo trazem caminho e podem ser abertos ou revelados;
+- resultados de sessão trazem `sessionId` e `messageId`, então o painel abre a conversa e destaca a mensagem;
+- substrings em chinês e inglês funcionam (tokenizador trigram, sem segmentação de palavras).
+
+Como o índice de conteúdo se comporta:
+
+- **Preguiçoso por padrão.** Nada é construído na inicialização; a primeira busca de conteúdo (`locator_find` ou o modo conteúdo do painel) inicia a construção em segundo plano, e `contentLazy: false` volta à construção no arranque. A primeira consulta informa `building: true` em vez de devolver vazio sem explicação.
+- **Reinício reaproveitando.** Se o banco existe, ele é atualizado de forma incremental; a construção completa (primeiro logs de sessão, depois corpos de arquivo) só acontece se o banco não existe, tem esquema antigo, ficou incompleto por uma construção interrompida ou não abre.
+- **Atualização incremental** a cada `contentRefreshMs` (5 minutos por padrão), relendo só arquivos e sessões cujo mtime mudou; `0` desativa.
+- **Sessões arquivadas e ativas.** Arquivadas são ignoradas a menos que `contentIncludeArchived: true`; um log que ainda está sendo escrito só é indexado após `contentActiveSessionDelayMs` (2 minutos) de quietude, para não descomprimi-lo a cada atualização. Sessões apagadas saem do índice quando os arquivos desaparecem.
+- **Orçamento e truncamento.** Padrões: 1 MB por arquivo de texto, 200.000 arquivos, 1 GB de corpos e as 100 sessões mais recentes. Ao atingir o orçamento, arquivos que chegam depois na ordem de varredura são ignorados; o `locator_find` informa `content budget reached` e o estado HTTP traz `truncated: true`. Aumente `contentMaxTotalBytes` ou reduza `contentExcludes`.
+- **Árvores de dependências não são lidas.** `node_modules`, `.cargo`, `.bun`, `.pnpm`, `site-packages`, `toolchain`, … são ignorados por padrão via `contentExcludes`; caso contrário, código de bibliotecas esgotaria o orçamento antes dos seus documentos. O índice de nomes continua cobrindo esses caminhos.
+
+A construção roda dentro do processo anfitrião do DSH, mas leituras de arquivo e descompressão zstd são assíncronas e os dois laços cedem o controle a cada ~8 ms: em um corpus de 28,6 MB o maior bloqueio do laço de eventos caiu de 968 ms para cerca de 20 ms, então carregar e trocar sessões continua fluido. As **consultas** de conteúdo rodam em uma worker thread com conexão somente leitura: palavras comuns levam cerca de 100 ms e termos raros alguns milissegundos, sem bloquear o host.
 
 ## Painel web
 
-![Painel de busca do dsh-locator: resultados Markdown filtrados por caminho, com contagem, tempo e colunas ordenáveis](docs/assets/panel-en.png)
+![Painel de busca do dsh-locator: modo conteúdo ativado, mostrando correspondências no corpo e trechos](docs/assets/panel-en.png)
 
-Pressione `Ctrl+Shift+F` em qualquer lugar da Web GUI, ou clique na lupa no rodapé da barra lateral. O painel se comunica com o host por rotas na mesma origem (`/dsh-locator/search`, `/dsh-locator/content`, `/dsh-locator/status`, `/dsh-locator/reveal` e `/dsh-locator/open`), sem segundo servidor e sem porta extra.
+Pressione `Ctrl+Shift+F` em qualquer lugar da GUI web, ou clique na lupa no pé da barra lateral.
 
-* Consulta vazia: entradas recentes por data; ao digitar, debounce de 110 ms e a mesma sintaxe das ferramentas.
-* Clique no cabeçalho para ordenar por nome, tamanho, data ou caminho; outro clique inverte.
-* `Somente arquivos` / `Somente pastas` filtram o tipo; marcar **Buscar conteúdo** alterna entre a busca por nomes e a busca no conteúdo dos arquivos e das mensagens de sessão, e os acertos mostram um trecho de uma linha. O rodapé mostra resultados, limite e tempo.
-* `↑`/`↓` seleciona, `Enter` copia, `Ctrl+O` abre, `Ctrl+Enter` insere `@"caminho"` no compositor; o clique duplo revela um arquivo no gerenciador de arquivos e, num resultado de sessão, abre a conversa correspondente e destaca a mensagem encontrada por um instante. `Esc` fecha.
-* A interface segue `navigator.language` (zh/en/es/pt/hi).
+- Consulta vazia lista as entradas modificadas mais recentemente; ao digitar, a mesma sintaxe das ferramentas é usada após 110 ms de debounce.
+- Clique no cabeçalho de uma coluna para ordenar por nome, tamanho, data de modificação ou caminho.
+- Alterne **somente arquivos** / **somente diretórios** para filtrar o tipo.
+- Marque **Buscar conteúdo** para trocar nomes por corpos de arquivo e mensagens de sessão; enquanto o índice é construído o rodapé mostra o estado e o painel consulta de novo.
+- `↑`/`↓` selecionam, `Enter` copia o caminho, `Ctrl+O` abre, `Ctrl+Enter` insere `@"caminho"` no compositor e `Esc` fecha.
+- Duplo clique em um arquivo revela no Explorer/Finder/`xdg-open`; duplo clique em uma sessão abre a conversa na mensagem encontrada.
+- O texto do painel segue `navigator.language` (zh/en/es/pt/hi).
+
+O painel usa rotas de mesma origem — `/dsh-locator/search`, `/dsh-locator/content`, `/dsh-locator/content/rebuild`, `/dsh-locator/status`, `/dsh-locator/reveal`, `/dsh-locator/open` — então não precisa de outro servidor nem de outra porta. Perfis sem servidor web não o montam.
 
 ## Ferramentas
 
-| Ferramenta | Uso |
+| Ferramenta | O que faz |
+|---|---|
+| `locator_search` | Consulta nomes e caminhos com filtros `ext:`, `size:`, `dm:`, `path:`, ordenação e paginação. |
+| `locator_find` | Busca em corpos de arquivo e mensagens de sessão; devolve trechos, `sessionId`/`messageId` e o estado do índice de conteúdo. |
+| `locator_status` | Raízes, contagens do índice de nomes, estado do watcher, diretório de estado e caminho do motor. (O progresso do conteúdo é informado pelo `locator_find` e pelo painel.) |
+| `locator_rebuild` | Substitui o índice de nomes por uma varredura em segundo plano; as buscas usam o índice antigo até o novo ficar pronto. |
+| `locator_reindex` | Atualiza ou reconstrói o índice de conteúdo: incremental por padrão, `full: true` apaga e reconstrói. |
+| `locator_export` | Grava um espelho SQLite somente leitura do índice de nomes (tabela `entries`) para ferramentas SQL externas. |
+
+## Linguagem de consulta
+
+Palavras soltas são substrings do nome unidas por AND. Filtros no estilo Everything se combinam com elas:
+
+| Exemplo | Significado |
 |---|---|
-| `locator_search` | Consulta com sintaxe estilo Everything. |
-| `locator_find` | Busca no corpo de arquivos e nas mensagens de sessão do DSH; os acertos trazem um trecho e, em conversas, `sessionId`/`messageId`. |
-| `locator_status` | Raízes, entradas, watcher, modo USN e erros. |
-| `locator_rebuild` | Reconstrói em segundo plano; buscas continuam no índice antigo. |
-| `locator_reindex` | Atualiza ou reconstrói o índice de conteúdo: incremental por padrão, `full: true` descarta e reconstrói. |
-| `locator_export` | Cópia somente leitura em SQLite (`entries(path, name, dir, size, mtime_ms, ext)`). |
+| `report` | o nome contém `report` |
+| `report ext:pdf` | …e a extensão é `pdf` |
+| `ext:ts,js` / `ext:!tmp` | incluir ou excluir extensões |
+| `*.sln` / `?ata` | curingas `*` e `?` |
+| `"annual report"` | frase com espaço |
+| `!archive` | negar um termo |
+| `path:src` | o caminho completo contém `src` |
+| `size:>10mb` / `size:1kb..2mb` | comparações de tamanho |
+| `dm:today` / `dm:thisweek` / `dm:2026-01-01` | data de modificação |
+| `folder:` / `file:` | somente diretórios / somente arquivos |
+| `case:1` / `wholeword:1` | sensível a maiúsculas / limites de palavra |
+
+O `locator_search` também aceita `sort` (`name`, `path`, `size`, `mtime`, `ext`), `desc`, `offset`, `limit`, `regex`, `caseSensitive` e `wholeWord`.
+
+## Configuração
+
+Cada campo é um campo de configuração do Schemastery; sobrescreva a entrada `dsh-locator` no patch do perfil, por exemplo:
+
+```yaml
+- id: dsh-locator
+  name: dsh-locator
+  config:
+    roots: ['/home/me/Documents', '/home/me/notes']
+    contentMaxTotalBytes: 2000000000
+    contentExcludes: ['node_modules', '.git', '.cargo', 'site-packages']
+```
 
-### Busca por conteúdo
+| Chave | Padrão | Significado |
+|---|---|---|
+| `enabled` | `true` | Chave geral; `false` não monta ferramentas nem inicia o motor. |
+| `roots` | diretório pessoal | Diretórios a indexar; pode haver vários. |
+| `excludes` | nomes de desenvolvimento/cache | Globs por nome ignorados pelo índice de nomes. |
+| `watch` | `true` | Aplicar notificações do sistema de arquivos. |
+| `refreshIntervalMs` | `1800000` | Cadência de reconstrução quando não há watcher nativo (kqueue ou falha do watcher); `0` desativa. |
+| `scanWorkers` | `0` | Concorrência de leitura de diretórios; `0` usa o número de CPUs. |
+| `windowsUsn` | `false` | Tentar a enumeração USN/MFT do NTFS antes da varredura (Windows, administrador; com fallback automático). |
+| `memoryLimitMB` | `0` | Limite suave do heap Go do motor em MiB; `0` deixa com `GOMEMLIMIT`/`GOGC`. |
+| `contentIndex` | `true` | Construir o índice de corpos e mensagens de sessão; `false` deixa a busca por nome com custo de conteúdo quase zero. |
+| `contentLazy` | `true` | Construir o índice de conteúdo na primeira busca em vez de no arranque. |
+| `contentMaxFileBytes` | `1000000` | Bytes lidos de um arquivo de texto. |
+| `contentMaxTotalBytes` | `1000000000` | Total de bytes de corpos guardados; `0` = sem limite. |
+| `contentMaxFiles` | `200000` | Arquivos de texto indexados por construção; `0` = sem limite. |
+| `contentMaxSessions` | `100` | Logs de sessão mais recentes indexados; `0` = todos. |
+| `contentRefreshMs` | `300000` | Cadência de atualização incremental do conteúdo; `0` desativa. |
+| `contentIncludeArchived` | `false` | Indexar também sessões arquivadas. |
+| `contentActiveSessionDelayMs` | `120000` | Indexar um log de sessão só após esse tempo de quietude. |
+| `contentSessionDirs` | `[]` | Diretórios de sessão extras; vazio = `$DSH_HOME/sessions`. |
+| `contentExcludes` | nomes de dependências/toolchains | Segmentos ou substrings de caminho ignorados pelo índice de conteúdo; o de nomes continua cobrindo. |
+| `stateDir` | `''` | Diretório do snapshot e do banco de conteúdo; vazio = cache da plataforma. Use um diretório por processo do DSH. |
+
+`binaryPath`, `maxResults`, `startupTimeoutMs` e `requestTimeoutMs` também existem para motores personalizados, limites de página e prazos; os padrões atendem a maioria dos casos.
+
+## Desempenho e recursos
+
+Medido em uma máquina de desenvolvimento WSL2 (Linux, cache de página quente) e um diretório pessoal real; sua máquina varia com disco, número de arquivos, cache e GC.
+
+**Índice de nomes**
+
+| Métrica | Resultado |
+|---|---|
+| Varredura a frio | ~1,51 M de entradas em 11–12 s |
+| Tamanho do snapshot | ~171 MB para 1,51 M de entradas |
+| Consulta a quente (`locator_search`) | 6–25 ms para consultas comuns; varreduras `path:` ~70 ms |
+| Busca durante uma reconstrução | O índice antigo continua servindo até o novo ficar pronto |
+| Memória de pico na varredura | Centenas de MB; o motor é um processo filho e respeita `memoryLimitMB` / `GOMEMLIMIT` |
 
-`locator_find` procura no corpo de arquivos de texto e nas mensagens de sessão do DSH por meio de um índice FTS5 local em SQLite. Subcadeias em chinês e inglês funcionam sem segmentação de palavras; cada acerto traz um trecho e, quando vem de uma conversa, `sessionId` e `messageId`.
+**Índice de conteúdo** (diretório pessoal real, orçamento de 1 GB)
 
-O índice de conteúdo é preguiçoso por padrão: nada é construído na inicialização e a primeira busca de conteúdo inicia a construção em segundo plano (`contentLazy: false` constrói desde o início). Ao reiniciar, o plugin reaproveita o banco existente e o atualiza de forma incremental; a indexação completa (primeiro os logs de sessão, depois o corpo dos arquivos) só roda quando o banco não existe, tem uma versão de esquema antiga ou não pode ser aberto. Depois disso, uma atualização incremental a cada `contentRefreshMs` (5 minutos) relê apenas os arquivos e as sessões cujo mtime mudou. O `locator_reindex` dispara um dos dois modos manualmente.
+| Métrica | Resultado (0.7.x, diretório real) |
+|---|---|
+| Cobertura | ~95,8 k arquivos de texto / 95 sessões / 1.050 mensagens |
+| Reconstrução completa | ~3,5 min em segundo plano; host p95 14 ms / máx 115 ms durante ela |
+| Atualização incremental (sem mudanças) | ~12 s (dominado pelo dump de 1,51 M de entradas do motor) |
+| Latência do host ocioso | p50 2 ms / p95 3 ms / máx 6 ms |
+| Tamanho do banco | ~3,1 GB (cerca de 3× o orçamento de corpos) |
+| Consulta de conteúdo | ~100 ms para palavras comuns, poucos ms para raras (worker thread, host não bloqueia) |
 
-Enquanto uma indexação está em andamento, as buscas continuam respondendo com o que já está indexado; a ferramenta e o painel mostram o estado da indexação.
+**Configurações mais econômicas**
 
-Os limites padrão são 1 MB por arquivo de texto, 200.000 arquivos, as 100 sessões mais recentes e 1 GB de texto — tudo configurável. Pastas de dependências e toolchains (`node_modules`, `.cargo`, `.bun`, `.pnpm`, `site-packages`, `toolchain`, …) ficam de fora por padrão — senão consomem o orçamento antes dos seus próprios documentos — e `contentExcludes` muda essa lista. O índice lê e descomprime de forma assíncrona e cede o event loop a cada ~8 ms (28,6 MB: 968 ms → 19 ms), então não trava o carregamento nem a troca de sessão; sessões arquivadas ficam de fora a menos que `contentIncludeArchived: true`, e uma sessão que está sendo escrita espera `contentActiveSessionDelayMs`.
+- Só busca por nome: `contentIndex: false` zera o trabalho de conteúdo.
+- Manter conteúdo usando menos disco: reduza `contentMaxTotalBytes` (ex.: 256000000) ou `contentMaxFileBytes`, ou aumente `contentRefreshMs`.
+- Cobrir mais arquivos: aumente `contentMaxTotalBytes` / `contentMaxFiles` e confira se `contentExcludes` não está excluindo árvores de documentos reais.
+- O banco de conteúdo é cache: apagar `stateDir` reconstrói e nunca toca nos arquivos originais.
 
-### Sintaxe de consulta
+## Suporte de plataformas
 
-```text
-relatorio                palavras AND no nome
-"duas palavras"          frase literal
-*.go  ?                  curingas
-ext:pdf,docx  ext:!tmp   por extensão (ou negação)
-path:src                 subcadeia do caminho completo
-size:>10mb  1kb..2mb     tamanho
-dm:today  dm:thisweek    data de modificação
-folder:  file:           só pastas / só arquivos
-!tmp                     negar
-case:1  wholeword:1      maiúsculas / palavra inteira
+| Plataforma | Varredura + snapshot | Atualizações ao vivo | Observações |
+|---|---|---|---|
+| Linux | sim | inotify, recursivo | Descritores de vigilância são por diretório; árvores enormes podem atingir `fs.inotify.max_user_watches`. |
+| Windows | sim | `ReadDirectoryChangesW`, recursivo | Não precisa de administrador nem do Everything. Enumeração USN/MFT opcional com privilégios elevados. Mudanças do WSL em `/mnt/<drive>` podem não gerar notificações; reconstrua essas raízes. |
+| macOS | sim | FSEvents nos binários cgo publicados, recursivo e sem limite | kqueue é o fallback com `CGO_ENABLED=0` (até 4.096 diretórios); mudanças de conteúdo dependem da reconstrução periódica. |
+
+### Windows e o diário USN
+
+O motor inclui um decodificador USN, um caminho rápido opcional e uma sonda. O caminho fica **desativado por padrão** (`windowsUsn: false`) porque o ioctl do volume exige privilégios de administrador; foi validado de ponta a ponta em um runner Windows do GitHub Actions (administrador, volume NTFS real):
+
+- 1.345.546 registros MFT lidos, 1.345.539 caminhos resolvidos
+- 164.209 entradas em `C:\Windows` (122.915 arquivos, 41.294 diretórios)
+- `scan --usn --root C:\Windows` indexou 164.216 entradas em 7,8 s; uma consulta respondeu em 9,6 ms
+- o diário de mudanças foi lido (8.233 registros em uma execução) e um diário inativo em `D:` caiu para a varredura com aviso
+
+Teste você mesmo:
+
+```powershell
+# PowerShell elevado (ou: Start-Process -Verb RunAs <caminho> ...)
+& ".\bin\win32-x64\indexd.exe" usn-probe --volume C: --root "C:\Windows" --limit 5 --journal 5
 ```
 
-## Configuração essencial
+Ele imprime o id/USNs do diário, enumera a MFT (registros por segundo, arquivos/diretórios sob a raiz, caminhos de exemplo) e decodifica os últimos registros do diário. Sem elevação falha com `Access is denied`; o parser e a reconstrução de caminhos são cobertos por testes unitários em todas as plataformas.
 
-| Chave | Valor |
-|---|---|
-| `roots` | Diretórios indexados; vazio = diretório pessoal. |
-| `excludes` | Globs por nome (`node_modules`, `.git`, …). |
-| `watch` | Ativa notificações do sistema. |
-| `refreshIntervalMs` | Reconstrução periódica quando não há watcher nativo. |
-| `windowsUsn` | Caminho rápido USN/MFT (Windows, administrador; padrão `false`). |
-| `scanWorkers` | Leitores de diretório em paralelo; 0 = CPU. |
-| `contentIndex` | Constrói o índice de conteúdo de arquivos e sessões (padrão `true`). |
-| `contentLazy` | Constrói o índice de conteúdo na primeira busca de conteúdo em vez de na inicialização; `false` constrói em segundo plano desde o início (padrão `true`). |
-| `contentMaxFileBytes` | Bytes lidos de cada arquivo de texto (padrão `1000000`). |
-| `contentMaxTotalBytes` | Total de bytes de conteúdo mantido; `0` = sem limite (padrão `1000000000`). |
-| `contentMaxFiles` | Máximo de arquivos de texto indexados a cada execução; `0` = sem limite (padrão `200000`). |
-| `contentMaxSessions` | Sessões mais recentes indexadas; `0` = todas (padrão `100`). |
-| `contentRefreshMs` | Ritmo da atualização incremental de conteúdo; `0` desativa (padrão `300000`). |
-| `contentIncludeArchived` | Indexa também sessões arquivadas; padrão `false`. |
-| `contentActiveSessionDelayMs` | Só indexa um log de sessão depois de ficar quieto esse tempo (padrão `120000`). |
-| `contentSessionDirs` | Diretórios adicionais de sessões; vazio = `$DSH_HOME/sessions`. |
-| `contentExcludes` | Trechos de caminho que a busca por conteúdo ignora (dependências e toolchains); o índice de nomes continua igual. |
-| `stateDir` | Diretório do instantâneo; vazio = cache do sistema. |
-
-
-## Plataformas
-
-| Plataforma | Varredura | Atualizações |
-|---|---|---|
-| Linux | varredura paralela | inotify recursivo |
-| Windows | varredura ou USN/MFT (admin) | `ReadDirectoryChangesW`; USN retoma após reinício |
-| macOS | varredura | FSEvents nos binários cgo; kqueue como fallback |
+Com `windowsUsn: true` (ou `indexd scan --usn`) o motor enumera a MFT em vez de percorrer diretórios e monta caminhos a partir do mapa de pais FRN. Uma varredura USN bem-sucedida grava `usn-state.json` (id do diário, próximo USN, raízes) e mantém o FRN em cada registro; no próximo `serve --usn` o motor reproduz o diário a partir desse cursor antes de responder, então arquivos criados enquanto estava parado aparecem sem varredura completa. Um diário envolvido, apagado ou inconsistente cai para o watcher portátil. Ele mantém o handle do volume e consulta o diário a cada dois segundos, aplicando criações, exclusões e renomeações via `usn.ApplyChanges` (o mesmo mapa FRN, atualizado no local). Registros USN **não trazem tamanho nem data de modificação**: os resultados são corretos para nomes e caminhos, o `locator_status` marca esse índice com `USN`, e o daemon faz stat da página devolvida para que as linhas mostrem tamanhos e datas reais; filtros `size:`/`dm:` sobre o índice inteiro continuam aproximados até uma passada de metadados. Qualquer falha (sem elevação, volume não suportado, registros demais) cai para a varredura portátil com aviso; nunca desativa a busca.
 
-No Windows, `scan --usn` grava `usn-state.json` (id do diário, próximo USN, raízes) e `serve --usn` reproduz o diário antes de servir: um arquivo criado com o daemon parado aparece após reiniciar sem reescanear. Diário desatualizado ou removido cai no watcher portátil.
+O Everything lê a Master File Table do NTFS pelo diário USN, e é por isso que seu primeiro índice é quase instantâneo. O `dsh-locator` mantém a varredura portátil como padrão (sem serviço, sem UAC, qualquer sistema de arquivos) e usa USN/MFT como caminho rápido opcional onde o processo tem `GENERIC_READ` (administrador), com reprodução do diário entre reinícios. O caminho portátil continua sendo o fallback.
 
-## Desempenho
+## Solução de problemas
 
-Conteúdo medido na mesma máquina (cache quente): 20.000 arquivos / 40 MB → 15,1 s e 71 MB; 200.000 arquivos / 331 MB → 31,5 s e 711 MB; atualização incremental do índice completo (1,3 M entradas) 2,9 s; reiniciar reaproveita o banco e leva 4,6 s no corpus de 200.000 arquivos. O banco ocupa 2–3 vezes o texto indexado.
+**O painel não aparece depois de instalar.**
+Recarregue a página (`F5`); confirme que instalou no perfil `web` e que o painel carrega do boot graph. Perfis headless/TUI nunca montam painel.
 
-- 1,2 M de entradas: consulta a quente 25–35 ms; busca durante a varredura ~2 ms.
-- `C:\Windows` (164.216 entradas) indexado por USN em 7,8 s num runner de CI; consulta 9,6 ms.
-- `locator_export` de 1,24 M de linhas: 477 MB, 6,4 s.
+**Um arquivo recém-criado não aparece.**
+A notificação pode não ter chegado (comum com gravações do WSL em `/mnt/c`, compartilhamentos de rede e alguns overlays de contêiner). Espere um instante ou rode `locator_rebuild` para essa raiz. O modo USN reproduz o diário ao reiniciar.
 
-## Design
+**A busca de conteúdo não devolve nada.**
+Veja `building` no resultado do `locator_find`: a primeira busca dispara a construção preguiçosa e os resultados podem ser parciais até terminar (o painel consulta de novo sozinho). Confirme também que a extensão é de texto, o arquivo não passa de `contentMaxFileBytes`, não é excluído por `contentExcludes` e a sessão não está arquivada (arquivadas são ignoradas por padrão).
+
+**O banco de conteúdo está enorme / o disco cresce rápido.**
+Veja [Desempenho e recursos](#desempenho-e-recursos): reduza o orçamento ou use `contentIndex: false`. Apagar `stateDir` dispara uma reconstrução.
 
-![Arquitetura do dsh-locator: sistemas de arquivos → varredura/vigilância → instantâneo compacto → motor de consulta → ferramentas / painel](docs/assets/architecture.svg)
+**Aparece um aviso de `inotify`.**
+Diretórios demais atingem o limite do kernel; o índice continua utilizável e as mudanças dependem de reconstruções periódicas. Aumente `fs.inotify.max_user_watches` ou reduza `roots`.
 
-* **Varredura paralela**: fila limitada e lotes por diretório para o pai existir antes dos filhos.
-* **Memória**: registros de 40 B, nomes numa arena compartilhada, tabela de caminhos aberta; o caminho completo só é reconstruído ao devolver resultados.
-* **Consulta**: termos compilados uma vez, divididos em fragmentos e um heap limitado escolhe `offset+limit`.
-* **Persistência**: arquivo temporário + rename atômico; o instantâneo é a fonte de inicialização.
-* **Protocolo**: NDJSON por stdio; sem porta nem superfície de rede.
+**O comportamento mudou após atualizar.**
+Rode `dsh plugin --profile web add dsh-locator@latest` e `F5`. Uma mudança de esquema do conteúdo reconstrói o banco uma vez. Veja o [CHANGELOG](CHANGELOG.md).
 
-## Compilar do código
+## Compilar a partir do código-fonte
 
-Requer Node `^22.19 || >=24.9`, pnpm e Go 1.22+.
+Requisitos: Node `^22.19 || >=24.9`, pnpm e Go 1.22+ para o motor.
 
 ```sh
 pnpm install
 pnpm build
-pnpm build:engine:all
-pnpm check
+pnpm build:engine:all   # ou build:engine para a plataforma atual
+pnpm check              # typecheck + testes + verificação de empacotamento/instalação
 ```
 
-O motor Go fica em `engine/`; testes: `cd engine && go test ./...`.
+O motor é um módulo Go separado em `engine/`; seus testes rodam com `cd engine && go test ./...`. O backend FSEvents do macOS precisa de cgo e é compilado no CI de macOS. Os testes Node rodam em Linux, Windows e macOS no CI.
+
+## Design
+
+![Arquitetura do dsh-locator: sistemas de arquivos → varredura/vigilância → snapshot compacto → motor de consulta → ferramentas do agente / painel web](docs/assets/architecture.svg)
 
-## Limites
+```
+DeepSeek Harness
+  └─ dsh-locator (plugin TypeScript)
+       ├─ locator_search / locator_find / locator_status / locator_rebuild /
+       │  locator_reindex / locator_export
+       ├─ client.js: overlay Ctrl+Shift+F (slot shell.overlay)
+       ├─ POST /dsh-locator/{search,content,status,reveal,open} (mesma origem)
+       ├─ armazenamento de conteúdo: SQLite FTS5 (trigram) no processo anfitrião,
+       │  consultas em worker thread
+       └─ processo filho: indexd serve  (Go, NDJSON por stdio)
+            ├─ scanner: varredura recursiva, exclusões, progresso
+            ├─ index:   arena de nomes + registros fixos + tabela de caminhos aberta
+            ├─ query:   parser, matcher, seleção top-K, ordenação, paginação
+            ├─ watcher: inotify (Linux) / ReadDirectoryChangesW (Windows)
+            └─ snapshot: arquivo único, mmap-friendly, renomeação atômica
+```
 
-* A busca por conteúdo lê apenas arquivos de texto (por extensão) e os logs de sessão do DSH; PDFs, documentos do Office e imagens não têm o texto extraído. Por padrão o corpo indexado fica limitado a 1 GB / 200.000 arquivos, então um diretório pessoal enorme guarda só a primeira fatia alcançada.
-* Não é um driver de sistema de arquivos; cobre apenas as raízes configuradas.
-* inotify usa um descritor por diretório; árvores enormes podem estourar o limite do kernel (há aviso e o instantâneo continua utilizável).
-* Escritas do WSL em `/mnt/c` podem não gerar notificações do Windows; reconstrua essas raízes.
-* macOS: FSEvents nos binários publicados; kqueue (máx. 4.096 diretórios) em builds `CGO_ENABLED=0`. Mudanças de conteúdo dependem da reconstrução periódica.
+- **Scanner paralelo.** Leitores de diretório drenam uma fila limitada e gravam um lote por diretório (`AddBatch`), então o registro pai existe antes dos filhos entrarem na fila. A fila não bloqueia: se estiver cheia, aquela subárvore é varrida em linha.
+- **Layout de memória.** Registros guardam deslocamento/comprimento do nome em uma arena de bytes e um id de pai; caminhos completos só são reconstruídos para a página de resultados e filtros `path:`. Isso evita um cabeçalho de string por arquivo.
+- **Tabela de caminhos.** Uma tabela de endereçamento aberto com slots `id+1` mantém busca/atualização perto de 12 bytes por entrada em vez dos ~50 de um `map[string]int32`.
+- **Motor de consulta.** Termos e filtros são compilados uma vez, comparados em blocos paralelos e reduzidos com um max-heap limitado: as `offset+limit` linhas são selecionadas sem ordenar milhões de correspondências.
+- **Índice de conteúdo.** SQLite FTS5 no host com tokenizador trigram (substrings UTF-8, CJK); a lista de arquivos vem da própria varredura do motor e logs de sessão são descomprimidos com zstd do Node.
+- **Consistência do conteúdo.** Um lock de construção por processo serializa escritores que compartilham `stateDir`, uma marca de construção completa força reconstrução após uma interrompida, e um handle obsoleto é detectado por dispositivo+inode para que a reconstrução de outro processo não deixe o host lendo um banco desvinculado.
+- **Persistência.** O snapshot é gravado em arquivo temporário e renomeado; um contador de geração permite ao daemon salvar só quando o índice mudou. Lápides são compactadas quando as exclusões passam de um limite.
+- **Protocolo.** Uma requisição/resposta JSON por linha em stdio, com eventos `scan`, `stats`, `warning`, `error` e `rebuilt`. Sem portas, sem superfície de autenticação, sem listeners de rede.
+- **Somente leitura.** O motor abre arquivos apenas para metadados; nunca escreve nos caminhos indexados.
+
+## Limitações
+
+- A busca de conteúdo lê apenas arquivos de texto (por extensão) e logs de sessão do DSH; PDF, Office e imagens não têm texto extraído.
+- O orçamento de conteúdo é consumido na ordem de varredura, não por importância do arquivo; arquivos posteriores não são buscáveis ao atingir o limite (`truncated` é true).
+- O índice cobre as raízes configuradas; não é um driver do sistema de arquivos.
+- O inotify do Linux vigia um descritor por diretório; um diretório pessoal com centenas de milhares de diretórios pode exceder o limite do kernel. O plugin avisa e o snapshot continua utilizável; reconstruções se recuperam.
+- Gravações do WSL em `/mnt/c` podem não produzir notificações do Windows (o watcher não vê o fluxo do escritor 9p). Reconstrua essas raízes.
+- Compartilhamentos de rede só são varridos se acessíveis como diretórios comuns; não há feed de mudanças específico de SMB.
+- O conteúdo das sessões vem de logs locais; mensagens ainda não gravadas em disco não são buscáveis.
+- Dois processos do DSH compartilhando um `stateDir` devem ser evitados: o lock de construção serializa escritores, mas não compartilha um handle de banco aberto.
+- O macOS usa FSEvents (recursivo) nos binários publicados; uma compilação com `CGO_ENABLED=0` cai para kqueue, limitado a 4.096 diretórios, com mudanças de conteúdo dependendo da reconstrução periódica.
+- USN/MFT do Windows é opcional e só é usado se o processo puder ler o volume e o diário estiver ativo; caso contrário, usa-se a varredura portátil.
+
+## Memória
+
+O motor é um único processo Go e respeita as variáveis padrão `GOMEMLIMIT` e `GOGC` (ou `memoryLimitMB` na configuração). Um índice de 1,2–1,5 M de entradas chega a várias centenas de MB de RSS com o GC padrão; use `GOMEMLIMIT=600MiB` (limite suave, o runtime troca CPU por memória) ou `GOGC=50` quando o host estiver apertado de RAM. Nenhum altera o formato do snapshot. Na instalação ao vivo usada para os números acima, o processo anfitrião do DSH (incluindo o cache de páginas do banco de conteúdo) ficava por volta de 700 MB de RSS com o índice construído, e a latência do host ocioso permanecia em p50 2 ms.
 
 ## Segurança e privacidade
 
-O banco de dados de conteúdo e o bloqueio de compilação são criados com permissões `0600`, e o diretório de estado com `0700`: outros usuários locais não podem ler os documentos indexados nem o texto das sessões.
+- O índice é local: sem chamadas de rede, sem telemetria, sem uploads. O plugin nunca modifica, move ou apaga arquivos indexados.
+- O banco de conteúdo e o lock de construção são criados `0600`, e o diretório de estado `0700`: outros usuários locais não conseguem ler documentos indexados nem o texto de sessões.
+- O snapshot e o banco de conteúdo contêm nomes, caminhos e corpos; trate o diretório de estado como dado privado. Apagá-lo limpa o cache.
+- Dê a cada processo concorrente do DSH um `stateDir` separado.
+
+## Versão e compatibilidade
+
+- Node `^22.19.0 || >=24.9.0`; DSH `>=0.2.1-rc.2 <0.3.0` (veja `engines` no `package.json`).
+- As versões são publicadas com procedência do GitHub Actions, então a origem do pacote npm é verificável; Gitee / GitCode são sincronizados por um workflow de espelho.
+- Registro de mudanças: [CHANGELOG.md](CHANGELOG.md); dúvidas e relatos: [Issues](https://github.com/PerryLink/dsh-locator/issues).
+
+## Roteiro
+
+Não é um compromisso, apenas a direção atual:
 
-O índice é local: sem rede, sem telemetria, sem uploads. O instantâneo contém nomes e caminhos; trate-o como dado privado. O plugin nunca modifica, move ou apaga os arquivos indexados.
+1. Verificar o runtime desktop Electron em uma instalação real do Windows.
+2. Pré-visualizações e agrupamento de resultados no painel.
+3. Cobertura de runtime em Windows on ARM / Linux ARM.
+4. Arena de nomes em minúsculas e pré-filtro trigram para índices muito grandes.
+5. Compactação incremental do snapshot e diários por raiz.
 
 ## Licença