dsh-locator 0.7.6 → 0.8.0

package/CHANGELOG.md

@@ -1,5 +1,25 @@
 # Changelog
 
+## 0.8.0 — 2026-11-12
+
+Search and locate: all three stores in one panel, and a Word/Notepad++-style highlight in the conversation.
+
+* **One combined search**: the new `POST /dsh-locator/combined` route queries content (bodies and sessions), files and folders in one request, keeps the old `/search` and `/content` routes for tools and compatibility, and returns grouped results in content → files → folders order with per-group counts. Paths found by both content and name are merged into the content row and counted.
+* **All scopes on by default**: the panel now has three independent checkboxes (Content, Files, Folders), all checked; unchecking one narrows the search. Empty queries and one-character queries never start the lazy content build, so opening the panel stays cheap.
+* **Conversation highlight**: double-clicking (or pressing Enter on) a session hit opens the conversation and paints the matched words with a translucent amber highlight (CSS Custom Highlight API, follows scrolling, centered on arrival). The scroll lock releases as soon as the reader scrolls or presses a key; `Esc` clears the highlight. Long sessions load older pages until the message is present, and `hidden="until-found"` rows are expanded with `beforematch`.
+* **Panel rebuild**: grouped listbox with sticky group headers, per-group counts and truncation hints, relevance ordering for content and the sort menu for names, scope preference persistence, content-index progress with a retry, and light/dark theme tokens instead of `prefers-color-scheme`.
+* **Keyboard and accessibility**: Enter activates the selected hit, `Ctrl+Shift+C` copies the path (Everything-style), `Ctrl+Shift+O` reveals it, `Alt+1–3` toggle scopes, Home/End/PageUp/PageDown move the selection, and a minimal dialog focus trap restores focus on close. Rows expose `role=option` / `aria-selected`; the panel is a combobox + listbox with a polite live region.
+* Fixed: duplicate React keys for several session hits, the unstyled snippet line, and the fake content total. Tests: 37 unit tests (combined scope gating, merge/dedupe, lazy-build guards, plus the existing content/plugin suites); `scripts/verify.mjs` now also syntax-checks `client.js` and asserts the new route and highlight markers.
+* No content-index schema change: upgrading does not rebuild the database. File-body hits still reveal the file in the file manager (line-level preview in DSH is the next step); assistant messages are located by phrase because their DOM rows carry no message id.
+
+## 0.7.7 — 2026-11-11
+
+Documentation release.
+
+* README (zh/en) rewritten against the 0.7.x behaviour and measurements: stale content defaults (1 MB / 1 GB / 100 sessions, previously documented as 4 MB / 2 GB / 200), refreshed performance tables, corrected `locator_status` scope, comparison with Everything/Spotlight/grep, resource tuning, troubleshooting, version compatibility and roadmap.
+* Spanish, Portuguese and Hindi READMEs brought to the same structure and section set.
+* The npm package page therefore receives the current documentation; no runtime changes.
+
 ## 0.7.6 — 2026-11-11
 
 Remaining-risk pass: sharing a cache directory, engine re-scans, and platform coverage.

package/README-es.md

@@ -2,9 +2,9 @@
 
 # 🔎 dsh-locator
 
-**Búsqueda de archivos en todo el disco, en milisegundos, para DeepSeek Harness — sin Everything.**
+**Busca por nombre cuando recuerdas el nombre y por contenido cuando recuerdas la frase; después abre el archivo o vuelve a la conversación.**
 
-Índice propio multiplataforma (Windows USN/MFT · macOS FSEvents · Linux inotify), seis herramientas para el agente —nombres, contenido y sesiones— y un panel web ordenable.
+Búsqueda de archivos en todo el disco para [DeepSeek Harness](https://github.com/deepseek-ai/deepseek-harness) con su **propio** índice: sin instalar Everything, sin `es.exe`, con las mismas herramientas y el mismo panel en Windows, macOS y 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)](#versión-y-compatibilidad)
 [![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>
 
-> **Repositorio oficial:** [GitHub `PerryLink/dsh-locator`](https://github.com/PerryLink/dsh-locator). Gitee y GitCode son espejos sincronizados automáticamente; GitHub es la fuente de verdad.
->
-> Forma parte de la [familia de plugins DSH](https://github.com/PerryLink) (Apache-2.0). Si te sirve, **una ⭐ ayuda a que la próxima persona lo encuentre**; no desbloquea nada.
+> **Repositorio oficial:** [GitHub `PerryLink/dsh-locator`](https://github.com/PerryLink/dsh-locator); Gitee y GitCode son réplicas sincronizadas automáticamente y GitHub es la fuente de verdad. Forma parte de la [familia de plugins de DSH](https://github.com/PerryLink) (Apache-2.0) y está listado en [awesome-dsh-plugin](https://github.com/awesome-dsh-plugin/awesome-dsh-plugin). Una ⭐ ayuda a que más gente lo encuentre; no hay nada bloqueado detrás de ella.
+
+## Índice
+
+- [De un vistazo](#de-un-vistazo)
+- [En qué se diferencia de Everything / Spotlight / grep](#en-qué-se-diferencia-de-everything--spotlight--grep)
+- [Instalación](#instalación)
+- [Primera ejecución](#primera-ejecución)
+- [Dos búsquedas](#dos-búsquedas)
+- [Panel web](#panel-web)
+- [Herramientas](#herramientas)
+- [Lenguaje de consulta](#lenguaje-de-consulta)
+- [Configuración](#configuración)
+- [Rendimiento y recursos](#rendimiento-y-recursos)
+- [Soporte de plataformas](#soporte-de-plataformas)
+- [Solución de problemas](#solución-de-problemas)
+- [Compilar desde el código fuente](#compilar-desde-el-código-fuente)
+- [Diseño](#diseño)
+- [Limitaciones](#limitaciones)
+- [Memoria](#memoria)
+- [Seguridad y privacidad](#seguridad-y-privacidad)
+- [Versión y compatibilidad](#versión-y-compatibilidad)
+- [Hoja de ruta](#hoja-de-ruta)
+- [Licencia](#licencia)
+
+## De un vistazo
+
+Buscar archivos tiene dos formas:
+
+- **Recuerdas el nombre pero no la ubicación.** `glob`/`grep` recorren el espacio de trabajo en cada llamada: bien si conoces el directorio, molesto si solo recuerdas medio nombre.
+- **Recuerdas una frase, una decisión o un fragmento, no el archivo ni la conversación.** Un índice de nombres no ayuda, y los registros de sesión de DSH también son datos de primera clase.
+
+`dsh-locator` reúne ambos en un solo plugin:
+
+| Capacidad | Cómo se usa |
+|---|---|
+| Búsqueda por nombre / ruta | `locator_search`, o el modo por defecto del panel |
+| Búsqueda en el cuerpo del archivo | `locator_find`, o el modo **Buscar contenido** del panel |
+| Búsqueda en sesiones de DSH | Las mismas herramientas; los resultados llevan `sessionId` / `messageId` y el panel puede volver a la conversación |
+| Abrir / mostrar | Las herramientas devuelven rutas; el panel abre con doble clic, `Ctrl+O` abre y `Ctrl+Enter` inserta `@"ruta"` en el compositor |
+| Consumo externo | `locator_export` escribe una réplica SQLite de solo lectura |
+
+El índice es local: sin llamadas de red, sin telemetría, sin subidas; el plugin nunca modifica, mueve ni borra los archivos indexados.
 
-`dsh-locator` indexa una vez los directorios que elijas, guarda el resultado en una instantánea compacta, aplica los cambios del sistema de archivos y responde consultas de nombre/ruta en decenas de milisegundos sobre más de un millón de entradas. El agente recibe `locator_search`, `locator_status`, `locator_rebuild` y `locator_export`; las personas tienen un **panel global** en la Web GUI (`Ctrl+Shift+F` o la lupa del pie de la barra lateral).
+## En qué se diferencia de Everything / Spotlight / grep
 
-## ¿Por qué otro buscador?
+| | dsh-locator | Everything | Spotlight | `glob` / `grep` |
+|---|---|---|---|---|
+| Plataformas | Windows / macOS / Linux / WSL | Windows | macOS | Multiplataforma |
+| Índice | Persistente, propio | Persistente (USN de NTFS) | Índice del sistema (metadatos/contenido) | Recorrido en cada llamada |
+| Búsqueda en contenido | Archivos de texto + mensajes de sesión de DSH | Solo nombres por defecto | Sí, varía según el sistema | Sí, sin índice |
+| Salto a sesión | Los resultados llevan `sessionId` / `messageId` | No | No | No |
+| Herramientas para agentes | Seis herramientas, un lenguaje de consulta | Requiere CLI/servicio | Requiere scripts propios | Nativas, sin índice persistente |
+| Velocidad en Windows | Cerca de Everything (USN opcional) | La más rápida y ligera | No aplica | Más lenta que un índice |
 
-`glob` y `grep` recorren el workspace en cada llamada: rápidos si conoces el directorio, lentos si solo recuerdas parte de un nombre. Everything es excelente en Windows, pero solo existe en Windows; envolverlo deja fuera macOS, Linux, WSL y hosts remotos. `dsh-locator` es dueño del índice, así que las mismas herramientas funcionan en cualquier sitio donde corran Node y Go.
+En resumen: la **idea** de Everything (índice persistente + consultas estructuradas) está implementada de forma independiente y multiplataforma, con las sesiones de DSH añadidas encima. No es un envoltorio de Everything.
 
 ## Instalación
 
@@ -40,154 +88,335 @@ dsh plugin --profile web add dsh-locator
 # npm (recomendado)
 dsh plugin --profile web add dsh-locator
 
-# GitHub main
+# fijar una versión
+dsh plugin --profile web add dsh-locator@0.7.7
+
+# rama principal de GitHub
 dsh plugin --profile web add github:PerryLink/dsh-locator
 
-# desde el código
+# desde un checkout
 pnpm install
 pnpm build
-pnpm build:engine
+pnpm build:engine        # motor Go para la plataforma actual
 dsh plugin --profile web add /ruta/absoluta/dsh-locator
 
-# tarball
+# desde un tarball (salida de npm pack; sustituye la versión real)
 npm pack
-dsh plugin --profile web add /ruta/absoluta/dsh-locator-0.5.0.tgz
+dsh plugin --profile web add /ruta/absoluta/dsh-locator-0.7.7.tgz
+```
+
+- El paquete incluye motores precompilados para `linux-x64`, `linux-arm64`, `win32-x64`, `win32-arm64`, `darwin-x64` y `darwin-arm64`; no hace falta Go local.
+- Si tu réplica de npm va con retraso, añade `--registry=https://registry.npmjs.org` al comando.
+- Tras instalar en un perfil Web **en ejecución**, **recarga la página** (`F5`): las herramientas del host pueden montarse al momento, pero el panel del navegador se carga del boot graph al abrir la página. Los perfiles headless/TUI solo tienen las herramientas.
+- Actualizar: `dsh plugin --profile web add dsh-locator@latest` y luego `F5`. Un cambio de esquema del contenido reconstruye la base una vez.
+- Desinstalar: `dsh plugin --profile web remove dsh-locator`; para mantener la configuración pero desactivarlo, `enabled: false`.
+
+## Primera ejecución
+
+En el primer montaje el motor indexa las raíces configuradas (por defecto, tu directorio personal) y escribe la instantánea y la base de contenido en el directorio de caché de la plataforma:
+
+| Plataforma | Directorio de estado por defecto |
+|---|---|
+| Windows | `%LOCALAPPDATA%\dsh-locator` |
+| macOS | `~/Library/Application Support/dsh-locator` |
+| Linux | `$XDG_CACHE_HOME/dsh-locator` o `~/.cache/dsh-locator` |
+
+El primer escaneo de un directorio personal grande lee el disco; los arranques posteriores cargan la instantánea. Las peticiones se atienden **durante** ese escaneo: la búsqueda devuelve lo ya indexado con `indexing: true` y el pie del panel indica que el índice sigue construyéndose.
+
+Por defecto se omiten `node_modules`, `.git`, `.hg`, `.svn`, `.cache`, `__pycache__`, `.venv`, `venv` y `.next` por nombre; `excludes` cambia la lista.
+
+Prueba con:
+
+```text
+Busca los PDF que cambié la semana pasada
+¿Dónde se habló de "contentRefreshMs"?
+¿En qué conversación se decidió este diseño?
 ```
 
-El paquete npm incluye motores precompilados para `linux-x64`, `linux-arm64`, `win32-x64`, `win32-arm64`, `darwin-x64` y `darwin-arm64`.
+## Dos búsquedas
 
-Si instalas en un perfil Web ya en ejecución, **recarga la página** (`F5`): las herramientas pueden montarse en caliente, pero el panel (`client.js`) se carga desde el boot graph al abrir la página. Los perfiles headless/TUI no montan panel.
+### Por nombre: `locator_search`
+
+Sintaxis estilo Everything que devuelve ruta, tamaño, fecha de modificación, extensión y tipo. Adecuada para «el nombre contiene report», «PDF modificados esta semana», «vídeos de más de 50 MB».
+
+La ordenación, la paginación y `limit`/`offset` los hace el motor del host; las consultas habituales sobre 1,51 M de entradas responden en decenas de milisegundos.
+
+### Por contenido: `locator_find`
+
+Busca en el **cuerpo** de archivos de texto y mensajes de sesión de DSH y devuelve fragmentos con su origen:
+
+- los aciertos de archivo llevan ruta y se pueden abrir o mostrar;
+- los aciertos de sesión llevan `sessionId` y `messageId`, así el panel abre la conversación y resalta el mensaje;
+- funcionan subcadenas en chino e inglés (tokenizador trigram, sin segmentación de palabras).
+
+Comportamiento del índice de contenido:
+
+- **Perezoso por defecto.** Al iniciar el plugin no se construye nada; la primera búsqueda de contenido (`locator_find` o el modo contenido del panel) arranca la construcción en segundo plano, y `contentLazy: false` recupera la construcción al arranque. La primera consulta informa `building: true` en lugar de devolver un resultado vacío sin explicación.
+- **Reinicio con reutilización.** Si existe la base, se actualiza de forma incremental; la construcción completa (primero logs de sesión y luego cuerpos de archivo) solo ocurre si falta la base, el esquema es antiguo, la construcción anterior quedó a medias o la base no se puede abrir.
+- **Actualización incremental** cada `contentRefreshMs` (5 minutos por defecto), releyendo solo archivos y sesiones cuya mtime cambió; `0` la desactiva.
+- **Sesiones archivadas y activas.** Las archivadas se omiten salvo `contentIncludeArchived: true`; un log que se sigue escribiendo se indexa tras `contentActiveSessionDelayMs` (2 minutos) de calma, para no descomprimirlo en cada actualización. Las sesiones borradas salen del índice cuando desaparecen sus archivos.
+- **Presupuesto y truncado.** Valores por defecto: 1 MB por archivo de texto, 200.000 archivos, 1 GB de cuerpos y las 100 sesiones más recientes. Al alcanzar el presupuesto se omiten los archivos que llegan después en el orden de escaneo; `locator_find` informa `content budget reached` y el estado HTTP lleva `truncated: true`. Sube `contentMaxTotalBytes` o reduce `contentExcludes`.
+- **Los árboles de dependencias no se leen.** `node_modules`, `.cargo`, `.bun`, `.pnpm`, `site-packages`, `toolchain`, … se omiten por defecto con `contentExcludes`; de lo contrario el código de librerías agotaría el presupuesto antes que tus documentos. El índice de nombres sí los cubre.
+
+La construcción ocurre dentro del proceso anfitrión de DSH, pero las lecturas y la descompresión zstd son asíncronas y ambos bucles ceden el paso cada ~8 ms: en un corpus de 28,6 MB el bloqueo más largo del bucle de eventos bajó de 968 ms a unos 20 ms, así que la carga y el cambio de sesión no se ven afectados. Las **consultas** de contenido se ejecutan en un hilo worker con conexión de solo lectura: las palabras comunes tardan unos 100 ms y las raras unos milisegundos, sin bloquear al host.
 
 ## Panel web
 
-![Panel de búsqueda de dsh-locator: resultados Markdown filtrados por ruta, con recuento, tiempo y columnas ordenables](docs/assets/panel-en.png)
+![Panel de búsqueda de dsh-locator: modo contenido activado, con aciertos en el cuerpo y fragmentos](docs/assets/panel-en.png)
+
+Pulsa `Ctrl+Shift+F` en cualquier parte de la GUI web, o haz clic en la lupa del pie de la barra lateral.
 
-Pulsa `Ctrl+Shift+F` en cualquier parte de la Web GUI, o haz clic en la lupa del pie de la barra lateral. El panel consulta el mismo índice mediante rutas del host del mismo origen (`/dsh-locator/search`, `/dsh-locator/content`, `/dsh-locator/status`, `/dsh-locator/reveal` y `/dsh-locator/open`), sin segundo servidor ni puerto extra.
+- Una consulta vacía lista las entradas modificadas más recientemente; al escribir se usa la misma sintaxis que las herramientas tras 110 ms de debounce.
+- Haz clic en la cabecera de una columna para ordenar por nombre, tamaño, fecha de modificación o ruta.
+- Alterna **solo archivos** / **solo directorios** para filtrar el tipo.
+- Marca **Buscar contenido** para pasar de nombres a cuerpos de archivo y mensajes de sesión; mientras se construye el índice el pie muestra el estado y el panel vuelve a consultar.
+- `↑`/`↓` seleccionan, `Enter` copia la ruta, `Ctrl+O` abre, `Ctrl+Enter` inserta `@"ruta"` en el compositor y `Esc` cierra.
+- Doble clic en un archivo lo muestra en Explorer/Finder/`xdg-open`; doble clic en una sesión abre la conversación en el mensaje encontrado.
+- El texto del panel sigue `navigator.language` (zh/en/es/pt/hi).
 
-* Consulta vacía: entradas recientes por fecha; al escribir, debounce de 110 ms y la misma sintaxis que las herramientas.
-* Clic en una columna para ordenar por nombre, tamaño, fecha o ruta; otro clic invierte.
-* `Solo archivos` / `Solo carpetas` filtran por tipo; la barra inferior muestra aciertos, límite y tiempo.
-* Marca **Buscar contenido** para pasar de los nombres al contenido de los archivos y a los mensajes de sesión; cada acierto muestra un fragmento de una línea.
-* `↑`/`↓` selecciona, `Enter` copia, `Ctrl+O` abre, `Ctrl+Enter` inserta `@"ruta"` en el compositor y `Esc` cierra.
-* El doble clic sobre un archivo abre su ubicación en el gestor de archivos; el doble clic sobre un resultado de sesión abre esa conversación y resalta el mensaje encontrado por un momento.
-* La interfaz sigue `navigator.language` (zh/en/es/pt/hi).
+El panel usa rutas del mismo origen — `/dsh-locator/search`, `/dsh-locator/content`, `/dsh-locator/content/rebuild`, `/dsh-locator/combined`, `/dsh-locator/status`, `/dsh-locator/reveal`, `/dsh-locator/open` — así que no necesita otro servidor ni otro puerto. Los perfiles sin servidor web no lo montan.
+
+- **Los tres ámbitos están activos por defecto**: contenido (cuerpos + sesiones), archivos y carpetas; desmarca cualquiera para acotar. Los resultados se agrupan **contenido → archivos → carpetas** con el recuento por grupo; el contenido se ordena por relevancia y los grupos de nombres siguen el menú de orden.
+- **Doble clic o `Enter` activa un resultado**: una sesión abre la conversación y pinta las palabras encontradas con un resaltado ámbar translúcido que sigue el desplazamiento, se centra al llegar y se limpia con `Esc`; archivos y carpetas se muestran en el gestor de archivos. `Ctrl+Shift+C` copia la ruta, `Ctrl+O` abre, `Ctrl+Enter` inserta `@file` y `Alt+1–3` alterna los ámbitos.
+- Las consultas de contenido requieren al menos dos caracteres; las consultas vacías o de un carácter no inician la construcción del índice.
 
 ## Herramientas
 
-| Herramienta | Uso |
+| Herramienta | Qué hace |
 |---|---|
-| `locator_search` | Consulta el índice con sintaxis estilo Everything. |
-| `locator_find` | Busca en el contenido de los archivos y en los mensajes de sesión de DSH; los aciertos traen un fragmento y, cuando vienen de una conversación, `sessionId`/`messageId`. |
-| `locator_status` | Raíces, entradas, watcher, modo USN y errores. |
-| `locator_rebuild` | Reconstruye en segundo plano; las búsquedas siguen usando el índice anterior. |
-| `locator_reindex` | Refresca o reconstruye el índice de contenido: incremental por defecto; `full: true` lo borra y lo vuelve a construir. |
-| `locator_export` | Copia de solo lectura en SQLite (`entries(path, name, dir, size, mtime_ms, ext)`). |
+| `locator_search` | Consulta nombres y rutas con filtros `ext:`, `size:`, `dm:`, `path:`, ordenación y paginación. |
+| `locator_find` | Busca en cuerpos de archivo y mensajes de sesión; devuelve fragmentos, `sessionId`/`messageId` y el estado del índice de contenido. |
+| `locator_status` | Raíces, recuentos del índice de nombres, estado del watcher, directorio de estado y ruta del motor. (El progreso del contenido lo informan `locator_find` y el panel). |
+| `locator_rebuild` | Sustituye el índice de nombres por un escaneo en segundo plano; las búsquedas usan el índice antiguo hasta que el nuevo esté listo. |
+| `locator_reindex` | Actualiza o reconstruye el índice de contenido: incremental por defecto, `full: true` lo borra y reconstruye. |
+| `locator_export` | Escribe una réplica SQLite de solo lectura del índice de nombres (tabla `entries`) para herramientas SQL externas. |
 
-### Búsqueda por contenido
+## Lenguaje de consulta
 
-`locator_find` busca en el contenido de los archivos de texto y en los mensajes de sesión de DSH mediante un índice SQLite FTS5 local. Las subcadenas en chino e inglés funcionan sin necesidad de segmentar palabras.
+Las palabras sueltas son subcadenas del nombre unidas con AND. Los filtros estilo Everything se combinan con ellas:
 
-Cada acierto devuelve un fragmento; si viene de una conversación, incluye `sessionId` y `messageId`, de modo que el panel puede abrir esa sesión y resaltar el mensaje encontrado.
+| Ejemplo | Significado |
+|---|---|
+| `report` | el nombre contiene `report` |
+| `report ext:pdf` | …y la extensión es `pdf` |
+| `ext:ts,js` / `ext:!tmp` | incluir o excluir extensiones |
+| `*.sln` / `?ata` | comodines `*` y `?` |
+| `"annual report"` | frase con espacio |
+| `!archive` | negar un término |
+| `path:src` | la ruta completa contiene `src` |
+| `size:>10mb` / `size:1kb..2mb` | comparaciones de tamaño |
+| `dm:today` / `dm:thisweek` / `dm:2026-01-01` | fecha de modificación |
+| `folder:` / `file:` | solo directorios / solo archivos |
+| `case:1` / `wholeword:1` | sensible a mayúsculas / límites de palabra |
+
+`locator_search` también acepta `sort` (`name`, `path`, `size`, `mtime`, `ext`), `desc`, `offset`, `limit`, `regex`, `caseSensitive` y `wholeWord`.
+
+## Configuración
+
+Cada campo es un campo de configuración de Schemastery; sobrescribe la entrada `dsh-locator` en el patch del perfil, por ejemplo:
+
+```yaml
+- id: dsh-locator
+  name: dsh-locator
+  config:
+    roots: ['/home/me/Documents', '/home/me/notes']
+    contentMaxTotalBytes: 2000000000
+    contentExcludes: ['node_modules', '.git', '.cargo', 'site-packages']
+```
 
-El índice de contenido es perezoso por defecto: al iniciar no se construye nada y la primera búsqueda de contenido lo arranca en segundo plano (`contentLazy: false` lo construye desde el arranque). Al reiniciar, el plugin reutiliza la base de datos existente y la actualiza de forma incremental; solo construye el índice completo (primero los registros de sesión, luego el contenido de los archivos) cuando la base no existe, tiene una versión de esquema antigua o no se puede abrir. Después, el refresco incremental se repite cada `contentRefreshMs` (5 minutos) y solo relee los archivos y las sesiones cuya `mtime` cambió; `locator_reindex` permite lanzar a mano cualquiera de los dos modos.
+| Clave | Valor por defecto | Significado |
+|---|---|---|
+| `enabled` | `true` | Interruptor general; `false` no monta herramientas ni arranca el motor. |
+| `roots` | directorio personal | Directorios a indexar; puede haber varios. |
+| `excludes` | nombres de desarrollo/caché | Globs por nombre que omite el índice de nombres. |
+| `watch` | `true` | Aplicar notificaciones del sistema de archivos. |
+| `refreshIntervalMs` | `1800000` | Cadencia de reconstrucción cuando no hay watcher nativo (kqueue o fallo del watcher); `0` la desactiva. |
+| `scanWorkers` | `0` | Concurrencia de lectura de directorios; `0` usa el número de CPU. |
+| `windowsUsn` | `false` | Probar la enumeración USN/MFT de NTFS antes del recorrido (Windows, administrador; con reserva automática). |
+| `memoryLimitMB` | `0` | Límite blando del heap Go del motor en MiB; `0` lo deja a `GOMEMLIMIT`/`GOGC`. |
+| `contentIndex` | `true` | Construir el índice de cuerpos y mensajes de sesión; `false` deja la búsqueda por nombre con un coste de contenido casi nulo. |
+| `contentLazy` | `true` | Construir el índice de contenido en la primera búsqueda en lugar de al iniciar. |
+| `contentMaxFileBytes` | `1000000` | Bytes leídos de un archivo de texto. |
+| `contentMaxTotalBytes` | `1000000000` | Total de bytes de cuerpos guardados; `0` = sin límite. |
+| `contentMaxFiles` | `200000` | Archivos de texto indexados por construcción; `0` = sin límite. |
+| `contentMaxSessions` | `100` | Logs de sesión más recientes indexados; `0` = todos. |
+| `contentRefreshMs` | `300000` | Cadencia de actualización incremental del contenido; `0` la desactiva. |
+| `contentIncludeArchived` | `false` | Indexar también las sesiones archivadas. |
+| `contentActiveSessionDelayMs` | `120000` | Indexar un log de sesión solo tras este tiempo de calma. |
+| `contentSessionDirs` | `[]` | Directorios de sesión adicionales; vacío = `$DSH_HOME/sessions`. |
+| `contentExcludes` | nombres de dependencias/toolchains | Segmentos o subcadenas de ruta que omite el índice de contenido; el de nombres sí los cubre. |
+| `stateDir` | `''` | Directorio de la instantánea y la base de contenido; vacío = caché de la plataforma. Usa uno distinto por proceso de DSH. |
+
+`binaryPath`, `maxResults`, `startupTimeoutMs` y `requestTimeoutMs` también están disponibles para motores personalizados, límites de página y tiempos de espera; los valores por defecto sirven para casi todo.
+
+## Rendimiento y recursos
+
+Medido en una máquina de desarrollo WSL2 (Linux, caché de página caliente) y un directorio personal real; tu equipo variará según disco, número de archivos, caché y GC.
+
+**Índice de nombres**
+
+| Métrica | Resultado |
+|---|---|
+| Escaneo en frío | ~1,51 M de entradas en 11–12 s |
+| Tamaño de la instantánea | ~171 MB para 1,51 M de entradas |
+| Consulta en caliente (`locator_search`) | 6–25 ms para consultas comunes; escaneos `path:` ~70 ms |
+| Búsqueda durante una reconstrucción | El índice antiguo sigue sirviendo hasta que el nuevo está listo |
+| Memoria pico de escaneo | Cientos de MB; el motor es un proceso hijo y respeta `memoryLimitMB` / `GOMEMLIMIT` |
 
-Mientras hay una construcción en marcha, las búsquedas siguen respondiendo con lo que ya está indexado, y la herramienta y el panel informan del estado del proceso.
+**Índice de contenido** (directorio personal real, presupuesto de 1 GB)
 
-Los límites actuales son 1 MB por archivo de texto, 200 000 archivos, las 100 sesiones más recientes y 1 GB de contenido en total; todos se pueden ajustar en la configuración. Las carpetas de dependencias y toolchains (`node_modules`, `.cargo`, `.bun`, `.pnpm`, `site-packages`, `toolchain`, …) se omiten por defecto — si no, se comen el presupuesto antes que tus propios documentos — y `contentExcludes` cambia esa lista. El índice lee y descomprime de forma asíncrona y cede el bucle de eventos cada ~8 ms (28,6 MB: 968 ms → 19 ms), así que no frena la carga ni el cambio de sesión; las sesiones archivadas no se indexan salvo `contentIncludeArchived: true`, y una sesión que se está escribiendo espera `contentActiveSessionDelayMs`.
+| Métrica | Resultado (0.7.x, directorio real) |
+|---|---|
+| Cobertura | ~95,8 k archivos de texto / 95 sesiones / 1.050 mensajes |
+| Reconstrucción completa | ~3,5 min en segundo plano; el host p95 14 ms / máx 115 ms durante ella |
+| Actualización incremental (sin cambios) | ~12 s (dominado por el dump de 1,51 M de entradas del motor) |
+| Latencia del host en reposo | p50 2 ms / p95 3 ms / máx 6 ms |
+| Tamaño de la base | ~3,1 GB (unas 3× el presupuesto de cuerpos) |
+| Consulta de contenido | ~100 ms para palabras comunes, pocos ms para raras (hilo worker, el host no se bloquea) |
 
-### Sintaxis de consulta
+**Configuraciones más económicas**
 
-```text
-reporte                  palabras AND en el nombre
-"dos palabras"           frase literal
-*.go  ?                  comodines
-ext:pdf,docx  ext:!tmp   por extensión (o negación)
-path:src                 subcadena de la ruta completa
-size:>10mb  1kb..2mb     tamaño
-dm:today  dm:thisweek    fecha de modificación
-folder:  file:           solo carpetas / solo archivos
-!tmp                     negar
-case:1  wholeword:1      mayúsculas / palabra completa
+- Solo búsqueda por nombre: `contentIndex: false` reduce el trabajo de contenido a cero.
+- Mantener contenido usando menos disco: baja `contentMaxTotalBytes` (p. ej. 256000000) o `contentMaxFileBytes`, o sube `contentRefreshMs`.
+- Cubrir más archivos: sube `contentMaxTotalBytes` / `contentMaxFiles` y comprueba que `contentExcludes` no excluye árboles de documentos reales.
+- La base de contenido es una caché: borrar `stateDir` la reconstruye y nunca toca los archivos originales.
+
+## Soporte de plataformas
+
+| Plataforma | Escaneo + instantánea | Actualizaciones en vivo | Notas |
+|---|---|---|---|
+| Linux | sí | inotify, recursivo | Los descriptores de vigilancia son por directorio; árboles enormes pueden alcanzar `fs.inotify.max_user_watches`. |
+| Windows | sí | `ReadDirectoryChangesW`, recursivo | No hace falta administrador ni Everything. Enumeración USN/MFT opcional con privilegios elevados. Los cambios de WSL en `/mnt/<unidad>` pueden no generar notificaciones; reconstruye esas raíces. |
+| macOS | sí | FSEvents en los binarios cgo publicados, recursivo y sin límite | kqueue es la reserva con `CGO_ENABLED=0` (hasta 4.096 directorios); los cambios de contenido dependen de la reconstrucción periódica. |
+
+### Windows y el diario USN
+
+El motor incluye un decodificador USN, una ruta rápida opcional y una sonda. La ruta está **desactivada por defecto** (`windowsUsn: false`) porque el ioctl del volumen necesita permisos de administrador; se ha validado de extremo a extremo en un runner Windows de GitHub Actions (administrador, volumen NTFS real):
+
+- 1.345.546 registros MFT leídos, 1.345.539 rutas resueltas
+- 164.209 entradas bajo `C:\Windows` (122.915 archivos, 41.294 directorios)
+- `scan --usn --root C:\Windows` indexó 164.216 entradas en 7,8 s; una consulta respondió en 9,6 ms
+- se leyó el diario de cambios (8.233 registros en una ejecución) y un diario inactivo en `D:` cayó al recorrido con un aviso
+
+Pruébalo tú mismo:
+
+```powershell
+# PowerShell elevado (o: Start-Process -Verb RunAs <ruta> ...)
+& ".\bin\win32-x64\indexd.exe" usn-probe --volume C: --root "C:\Windows" --limit 5 --journal 5
 ```
 
-## Configuración esencial
+Imprime el id/USNs del diario, enumera la MFT (registros por segundo, archivos/directorios bajo la raíz, rutas de ejemplo) y decodifica los últimos registros del diario. Sin elevación falla con `Access is denied`; el parser y la reconstrucción de rutas están cubiertos por pruebas unitarias en todas las plataformas.
 
-| Clave | Valor |
-|---|---|
-| `roots` | Directorios a indexar; vacío = directorio personal. |
-| `excludes` | Globs por nombre (`node_modules`, `.git`, …). |
-| `watch` | Activa las notificaciones del sistema. |
-| `refreshIntervalMs` | Reconstrucción periódica si no hay watcher nativo. |
-| `windowsUsn` | Ruta rápida USN/MFT (Windows, administrador; por defecto `false`). |
-| `scanWorkers` | Lectores de directorio en paralelo; 0 = CPU. |
-| `stateDir` | Directorio de la instantánea; vacío = caché del sistema. |
-| `contentIndex` | Activa la construcción del índice de contenido de archivos y mensajes de sesión (por defecto `true`). |
-| `contentLazy` | Construye el índice de contenido en la primera búsqueda de contenido en vez de al iniciar; `false` lo construye en segundo plano desde el arranque (por defecto `true`). |
-| `contentMaxFileBytes` | Máximo de bytes que se leen de cada archivo de texto (por defecto `1000000`). |
-| `contentMaxTotalBytes` | Total de bytes de contenido que se conservan; `0` = sin límite (por defecto `1000000000`). |
-| `contentMaxFiles` | Archivos de texto indexados en cada construcción; `0` = sin límite (por defecto `200000`). |
-| `contentMaxSessions` | Sesiones más recientes indexadas; `0` = todas (por defecto `100`). |
-| `contentRefreshMs` | Cadencia del refresco incremental de contenido; `0` lo desactiva (por defecto `300000`). |
-| `contentIncludeArchived` | Indexa también las sesiones archivadas; por defecto `false`. |
-| `contentActiveSessionDelayMs` | Solo indexa un registro de sesión tras estar quieto este tiempo (por defecto `120000`). |
-| `contentSessionDirs` | Directorios de sesión adicionales; vacío = `$DSH_HOME/sessions` (por defecto `[]`). |
-| `contentExcludes` | Tramos de ruta que la búsqueda por contenido omite (dependencias y toolchains); el índice de nombres no cambia. |
-
-
-## Plataformas
-
-| Plataforma | Exploración | Actualizaciones |
-|---|---|---|
-| Linux | recorrido paralelo | inotify recursivo |
-| Windows | recorrido o USN/MFT (admin) | `ReadDirectoryChangesW`; USN reanuda tras reinicio |
-| macOS | recorrido | FSEvents en binarios cgo; kqueue como respaldo |
+Con `windowsUsn: true` (o `indexd scan --usn`) el motor enumera la MFT en vez de recorrer directorios y construye rutas desde el mapa de padres FRN. Un escaneo USN correcto escribe `usn-state.json` (id del diario, siguiente USN, raíces) y conserva el FRN en cada registro; en el siguiente `serve --usn` el motor reproduce el diario desde ese cursor antes de responder, así los archivos creados mientras estaba parado aparecen sin un escaneo completo. Un diario envuelto, borrado o inconsistente cae al watcher portátil. Mantiene el handle del volumen y consulta el diario cada dos segundos, aplicando altas, bajas y renombrados mediante `usn.ApplyChanges` (el mismo mapa FRN, actualizado in situ). Los registros USN **no llevan tamaño ni fecha de modificación**: los resultados son correctos para nombres y rutas, `locator_status` marca ese índice con `USN`, y el daemon hace stat de la página devuelta para que las filas muestren tamaños y fechas reales; los filtros `size:`/`dm:` sobre todo el índice siguen siendo aproximados hasta que se ejecuta una pasada de metadatos. Cualquier fallo (sin elevación, volumen no soportado, demasiados registros) cae al recorrido portátil con un aviso; nunca desactiva la búsqueda.
 
-En Windows, `scan --usn` guarda `usn-state.json` (id del diario, siguiente USN, raíces) y `serve --usn` reproduce el diario antes de servir: un archivo creado con el daemon detenido aparece al reiniciar sin reescanear. Un diario desactualizado o desmontado cae al watcher portátil.
+Everything lee la Master File Table de NTFS a través del diario USN, por eso su primer índice es casi instantáneo. `dsh-locator` mantiene el recorrido de directorios portátil como opción por defecto (sin servicio, sin UAC, cualquier sistema de archivos) y usa USN/MFT como ruta rápida opcional donde el proceso tiene `GENERIC_READ` (administrador), con reproducción del diario entre reinicios. El recorrido portátil sigue siendo la reserva.
 
-## Rendimiento
+## Solución de problemas
 
-Contenido medido en la misma máquina (caché caliente): 20 000 archivos / 40 MB → 15,1 s y 71 MB; 200 000 archivos / 331 MB → 31,5 s y 711 MB; refresco incremental del índice completo (1,3 M entradas) 2,9 s; reiniciar reutiliza la base y tarda 4,6 s en el corpus de 200 000 archivos. La base ocupa 2–3 veces el texto indexado.
+**El panel no aparece tras la instalación.**
+Recarga la página (`F5`); confirma que instalaste en el perfil `web` y que el panel se carga del boot graph. Los perfiles headless/TUI nunca montan panel.
 
-- 1,2 M de entradas: consulta en caliente 25–35 ms; búsqueda durante el escaneo ~2 ms.
-- `C:\Windows` (164 216 entradas) indexado por USN en 7,8 s en un runner de CI; consulta 9,6 ms.
-- `locator_export` de 1,24 M de filas: 477 MB, 6,4 s.
+**Un archivo recién creado no aparece.**
+Puede que la notificación no haya llegado (habitual con escrituras de WSL en `/mnt/c`, recursos de red y algunos overlays de contenedores). Espera un momento o ejecuta `locator_rebuild` para esa raíz. El modo USN reproduce el diario al reiniciar.
 
-## Diseño
+**La búsqueda de contenido no devuelve nada.**
+Mira `building` en el resultado de `locator_find`: la primera búsqueda lanza la construcción perezosa y los resultados pueden ser parciales hasta que termine (el panel vuelve a consultar solo). Comprueba también que la extensión es de texto, el archivo no supera `contentMaxFileBytes`, no está excluido por `contentExcludes` y la sesión no está archivada (las archivadas se omiten por defecto).
+
+**La base de contenido es enorme / el disco crece rápido.**
+Consulta [Rendimiento y recursos](#rendimiento-y-recursos): baja el presupuesto o pon `contentIndex: false`. Borrar `stateDir` provoca una reconstrucción.
 
-![Arquitectura de dsh-locator: sistemas de archivos → escaneo/vigilancia → instantánea compacta → motor de consulta → herramientas / panel](docs/assets/architecture.svg)
+**Aparece un aviso de `inotify`.**
+Demasiados directorios alcanzan el límite del kernel; el índice sigue siendo usable y los cambios dependen de reconstrucciones periódicas. Sube `fs.inotify.max_user_watches` o reduce `roots`.
 
-* **Escaneo paralelo**: cola acotada, lotes por directorio para que el padre exista antes que los hijos.
-* **Memoria**: registros de 40 B, nombres en una arena compartida, tabla de rutas abierta; la ruta completa se reconstruye solo al devolver resultados.
-* **Consulta**: los términos se compilan una vez, se reparten por fragmentos y un heap acotado selecciona `offset+limit`.
-* **Persistencia**: archivo temporal + rename atómico; el snapshot es la fuente de arranque.
-* **Protocolo**: NDJSON por stdio; sin puerto ni superficie de red.
+**El comportamiento cambió tras actualizar.**
+Ejecuta `dsh plugin --profile web add dsh-locator@latest` y `F5`. Un cambio de esquema del contenido reconstruye la base una vez. Consulta [CHANGELOG](CHANGELOG.md).
 
-## Compilar desde el código
+## Compilar desde el código fuente
 
-Requiere Node `^22.19 || >=24.9`, pnpm y Go 1.22+.
+Requisitos: Node `^22.19 || >=24.9`, pnpm y Go 1.22+ para el motor.
 
 ```sh
 pnpm install
 pnpm build
-pnpm build:engine:all
-pnpm check
+pnpm build:engine:all   # o build:engine para la plataforma actual
+pnpm check              # typecheck + pruebas + verificación de empaquetado/instalación
 ```
 
-El motor Go vive en `engine/`; pruebas: `cd engine && go test ./...`.
+El motor es un módulo Go independiente en `engine/`; sus pruebas se ejecutan con `cd engine && go test ./...`. El backend FSEvents de macOS necesita cgo y se compila en CI de macOS. Las pruebas de Node se ejecutan en Linux, Windows y macOS en CI.
 
-## Límites
+## Diseño
 
-* La búsqueda por contenido solo lee archivos de texto (por extensión) y los registros de sesión del DSH; los PDF, documentos de Office e imágenes no se extraen. De forma predeterminada el cuerpo indexado se limita a 1 GB / 200.000 archivos, así que en un directorio personal enorme solo queda la primera parte que se alcanza.
-* No es un driver de sistema de archivos; cubre solo las raíces configuradas.
-* inotify consume un descriptor por directorio; árboles enormes pueden agotar el límite del kernel (se avisa y la instantánea sigue usable).
-* Escrituras WSL en `/mnt/c` pueden no generar notificaciones de Windows; reconstruye esas raíces.
-* macOS: FSEvents en los binarios publicados; kqueue (máx. 4.096 directorios) en compilaciones `CGO_ENABLED=0`. Los cambios de contenido dependen de la reconstrucción periódica.
+![Arquitectura de dsh-locator: sistemas de archivos → escaneo/vigilancia → instantánea compacta → motor de consultas → herramientas del agente / panel web](docs/assets/architecture.svg)
+
+```
+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} (mismo origen)
+       ├─ almacén de contenido: SQLite FTS5 (trigram) en el proceso anfitrión,
+       │  consultas en un hilo worker
+       └─ proceso hijo: indexd serve  (Go, NDJSON por stdio)
+            ├─ scanner: recorrido recursivo, exclusiones, progreso
+            ├─ index:   arena de nombres + registros fijos + tabla de rutas abierta
+            ├─ query:   parser, matcher, selección top-K, orden, paginación
+            ├─ watcher: inotify (Linux) / ReadDirectoryChangesW (Windows)
+            └─ snapshot: archivo único, mmap-friendly, renombrado atómico
+```
+
+- **Escáner paralelo.** Los lectores de directorios drenan una cola acotada y escriben un lote por directorio (`AddBatch`), de modo que el registro padre existe antes de encolar sus hijos. La cola no bloquea: si está llena, ese subárbol se escanea en línea.
+- **Disposición en memoria.** Los registros guardan un desplazamiento/longitud de nombre en una arena de bytes y un id de padre; las rutas completas solo se reconstruyen para la página de resultados y los filtros `path:`. Así se evita una cabecera de string por archivo.
+- **Tabla de rutas.** Una tabla de direccionamiento abierto con ranuras `id+1` mantiene búsqueda/actualización en ~12 bytes por entrada en vez de los ~50 de un `map[string]int32`.
+- **Motor de consultas.** Los términos y filtros se compilan una vez, se comparan en trozos paralelos y se reducen con un max-heap acotado: se seleccionan las `offset+limit` filas sin ordenar millones de coincidencias.
+- **Índice de contenido.** SQLite FTS5 en el host con tokenizador trigram (subcadenas UTF-8, CJK); la lista de archivos viene del propio escaneo del motor y los logs de sesión se descomprimen con zstd de Node.
+- **Consistencia del contenido.** Un lock de construcción por proceso serializa escritores que comparten `stateDir`, una marca de construcción completa fuerza la reconstrucción tras una interrumpida, y un handle obsoleto se detecta por dispositivo+inodo para que la reconstrucción de otro proceso no deje al host leyendo una base desvinculada.
+- **Persistencia.** La instantánea se escribe en un archivo temporal y se renombra; un contador de generación permite que el daemon guarde solo cuando el índice cambió. Las lápidas se compactan cuando las bajas superan un umbral.
+- **Protocolo.** Una petición/respuesta JSON por línea en stdio, con eventos `scan`, `stats`, `warning`, `error` y `rebuilt`. Sin puertos, sin superficie de autenticación, sin listeners de red.
+- **Solo lectura.** El motor abre archivos solo para metadatos; nunca escribe en las rutas indexadas.
+
+## Limitaciones
+
+- La búsqueda de contenido solo lee archivos de texto (por extensión) y logs de sesión de DSH; no se extrae texto de PDF, Office ni imágenes.
+- El presupuesto de contenido se consume en orden de escaneo, no por importancia del archivo; los archivos posteriores no son buscables al alcanzar el límite (`truncated` es true).
+- El índice cubre las raíces configuradas; no es un driver del sistema de archivos.
+- Linux inotify vigila un descriptor por directorio; un directorio personal con cientos de miles de directorios puede superar el límite del kernel. El plugin avisa y la instantánea sigue utilizable; las reconstrucciones se ponen al día.
+- Las escrituras de WSL en `/mnt/c` pueden no producir notificaciones de Windows (el watcher no ve el flujo del escritor 9p). Reconstruye esas raíces.
+- Los recursos de red solo se escanean si son accesibles como directorios normales; no hay feed de cambios específico de SMB.
+- El contenido de las sesiones viene de logs locales; los mensajes aún no volcados a disco no son buscables.
+- Dos procesos de DSH compartiendo un `stateDir` deben evitarse: el lock de construcción serializa escritores, pero no puede compartir un handle de base de datos abierto.
+- macOS usa FSEvents (recursivo) en los binarios publicados; una compilación con `CGO_ENABLED=0` cae a kqueue, limitado a 4.096 directorios, con cambios de contenido dependientes de la reconstrucción periódica.
+- USN/MFT de Windows es opcional y solo se usa si el proceso puede leer el volumen y el diario está activo; si no, se usa el recorrido portátil.
+
+- Los aciertos en el cuerpo de un archivo se muestran por ahora en el gestor de archivos (la vista por línea dentro de DSH es el siguiente paso); los mensajes del asistente se localizan por frase porque sus filas del DOM no llevan messageId.
+- El resaltado dentro de la conversación usa la API CSS Custom Highlight; los navegadores antiguos sin ella caen a un contorno de fila.
+
+## Memoria
+
+El motor es un único proceso Go y respeta las variables estándar `GOMEMLIMIT` y `GOGC` (o `memoryLimitMB` en la configuración). Un índice de 1,2–1,5 M de entradas alcanza varios cientos de MB de RSS con el GC por defecto; usa `GOMEMLIMIT=600MiB` (límite blando, el runtime cambia CPU por memoria) o `GOGC=50` cuando el host vaya justo de RAM. Ninguno cambia el formato de la instantánea. En la instalación en vivo usada para las cifras anteriores, el proceso anfitrión de DSH (incluida la caché de páginas de la base de contenido) rondaba los 700 MB de RSS con el índice construido, y la latencia del host en reposo se mantenía en p50 2 ms.
 
 ## Seguridad y privacidad
 
-La base de datos de contenido y el bloqueo de compilación se crean con permisos `0600`, y el directorio de estado con `0700`: otros usuarios locales no pueden leer los documentos indexados ni el texto de las sesiones.
+- El índice es local: sin llamadas de red, sin telemetría, sin subidas. El plugin nunca modifica, mueve ni borra archivos indexados.
+- La base de contenido y el lock de construcción se crean con `0600`, y el directorio de estado con `0700`: otros usuarios locales no pueden leer documentos indexados ni el texto de las sesiones.
+- La instantánea y la base de contenido contienen nombres, rutas y cuerpos; trata el directorio de estado como datos privados. Borrarlo limpia la caché.
+- Da a cada proceso de DSH concurrente un `stateDir` distinto.
+
+## Versión y compatibilidad
+
+- Node `^22.19.0 || >=24.9.0`; DSH `>=0.2.1-rc.2 <0.3.0` (ver `engines` en `package.json`).
+- Las versiones se publican con procedencia de GitHub Actions, así que el origen del paquete npm es verificable; Gitee / GitCode se sincronizan con un workflow de réplica.
+- Registro de cambios: [CHANGELOG.md](CHANGELOG.md); dudas e informes: [Issues](https://github.com/PerryLink/dsh-locator/issues).
+
+## Hoja de ruta
+
+No es un compromiso, solo la dirección actual:
 
-El índice es local: sin red, sin telemetría, sin subidas. La instantánea contiene nombres y rutas; trátala como datos privados. El plugin nunca modifica, mueve ni borra los archivos indexados.
+1. Verificar el runtime de escritorio Electron en una instalación real de Windows.
+2. Vistas previas y agrupación de resultados en el panel.
+3. Cobertura de runtime en Windows on ARM / Linux ARM.
+4. Arena de nombres en minúsculas y prefiltro trigram para índices muy grandes.
+5. Compactación incremental de la instantánea y diarios por raíz.
 
 ## Licencia